Installation

Install Codaph via npm, npx, or from source with bun

Overview

Codaph can be installed in three ways:

1. npm (Global) - Recommended for most users
2. npx (No Install) - Quick testing without global install
3. From Source - For contributors and local development

Node.js requirement: Codaph requires Node.js 18 or higher.

Method 1: npm (Global Install)

Install Codaph globally to use the codaph command anywhere:

1. Install the package

   npm install -g @codaph/codaph
   
2. Verify installation

   codaph --version
   codaph --help
   
3. Update to latest version

   npm update -g @codaph/codaph
   

Uninstall

npm uninstall -g @codaph/codaph

Advantages

• Fast command access: codaph is on your PATH
• Auto-updates: Use npm update -g to stay current
• Works everywhere: Available in all directories

Use When

• You use Codaph regularly across multiple projects
• You want the fastest command execution
• You’re comfortable with global npm packages

Method 2: npx (No Install)

Run Codaph on-demand without installing:

Basic Usage

npx @codaph/codaph --version
npx @codaph/codaph init
npx @codaph/codaph tui

npx downloads the package on first use in each session. This adds startup time but ensures you’re always using the latest version.

Advantages

• No global install: Keeps your system clean
• Always latest: Fetches newest version each run
• Easy testing: Try Codaph without commitment

Use When

• You’re evaluating Codaph before committing
• You prefer not to install global packages
• You want to ensure latest version every time

MCP Setup with npx

When using npx, adjust MCP configuration:

codaph mcp setup claude --mode npx --run

Or manually:

claude mcp add --scope user codaph -- npx --yes --package @codaph/codaph codaph mcp

Method 3: From Source (Development)

For contributors or local development:

1. Install Bun

   Codaph uses Bun for development:

   curl -fsSL https://bun.sh/install | bash
   

   Or visit bun.sh for other installation methods.

   Requires Bun 1.3.9 or higher.

2. Clone the repository

   git clone https://github.com/mubit-ai/codaph.git
   cd codaph
   
3. Install dependencies

   bun install
   
4. Run type check and tests

   bun run typecheck
   bun test
   
5. Build the project

   bun run build
   

   This creates dist/index.js with the shebang for direct execution.

6. Run from source

   Use bun run cli instead of codaph:

   bun run cli --version
   bun run cli init --cwd /path/to/project
   bun run cli tui
   

Development Commands

Run CLI

bun run cli <command>

Advantages

• Full control: Modify source code locally
• Latest changes: Use unreleased features
• Debugging: Add console.log and inspect behavior
• Contributing: Required for pull requests

Use When

• You’re contributing to Codaph
• You need bleeding-edge features
• You’re debugging issues or testing fixes
• You want to understand the codebase

Verify Installation

After installation, verify Codaph is working:

Check Version

codaph --version
# or
npx @codaph/codaph --version
# or
bun run cli --version

Expected output from codaph --version:

0.1.15

Version numbers will vary. The important thing is seeing a version string without errors.

System Requirements

Required

• Node.js 18 or higher
• Git (for auto-detection of project metadata)
• Terminal with ANSI color support (for TUI)

Recommended

• Mubit API key (for cloud sync)
• gh CLI (for auto-detecting GitHub actor ID)
• Coding agent CLI (Codex, Claude Code, or Gemini CLI)

Optional

• OpenAI API key (for enhanced query/chat)
• Bun 1.3.9+ (for development from source)

Environment Setup

After installation, configure your environment:

1. Get a Mubit API key

   Create one at console.mubit.ai

2. Configure Codaph

   codaph setup --mubit-api-key <your-key>
   

   Or use environment variables:

   export MUBIT_API_KEY=<your-key>
   
3. Optional: Add OpenAI

   codaph setup --openai-api-key <your-openai-key>
   

   Or:

   export OPENAI_API_KEY=<your-key>
   export OPENAI_MODEL=gpt-4.1-mini  # optional override
   
4. Verify configuration

   codaph doctor
   

Configuration Files

Codaph stores configuration in these locations:

Global Settings

Location: ~/.codaph/settings.json

Stores:

• Mubit API key
• OpenAI API key
• Mubit actor ID
• Per-project settings

{
  "mubitApiKey": "sk-...",
  "openAiApiKey": "sk-...",
  "mubitActorId": "your-username",
  "projects": {
    "/path/to/project": {
      "mubitProjectId": "owner/repo",
      "agentProviders": ["codex", "claude-code"]
    }
  }
}

Project Registry

Location: ~/.codaph/registry.json

Tracks initialized projects:

{
  "projects": ["/path/to/project-1", "/path/to/project-2"],
  "lastProjectPath": "/path/to/project-1"
}

Project Configuration

Location: <project>/.codaph/project.json

Per-project settings:

{
  "schema": "codaph.project.v2",
  "projectPath": "/path/to/project",
  "repoId": "owner/repo",
  "mubitProjectId": "owner/repo",
  "agentProviders": ["codex"],
  "syncAutomation": {
    "enabled": true,
    "gitPostCommit": true,
    "agentComplete": true
  }
}

MCP Template

Location: <project>/.codaph/mcp/claude-code.json

Claude Code MCP configuration template:

{
  "mcpServers": {
    "codaph": {
      "type": "stdio",
      "command": "codaph",
      "args": ["mcp"]
    }
  }
}

Upgrade Codaph

Keep Codaph up to date:

npm

npm update -g @codaph/codaph
codaph --version

npx

npx always uses the latest version by default. No manual update needed.

Force cache clear:

npm cache clean --force
npx @codaph/codaph --version

Source

cd /path/to/codaph
git pull origin main
bun install
bun run build
bun run cli --version

Troubleshooting

Command not found: codaph

If codaph is not on your PATH after npm install -g:

1. Check npm global bin location:

   npm config get prefix
   

2. Add to PATH:

   export PATH="$(npm config get prefix)/bin:$PATH"
   

3. Or use npx:

   npx @codaph/codaph --version
   

Permission denied

On Linux/macOS, you may need sudo:

sudo npm install -g @codaph/codaph

Or configure npm to install globally without sudo:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @codaph/codaph

Node version too old

Codaph requires Node.js 18+. Check your version:

node --version

Upgrade via nvm:

nvm install 20
nvm use 20
npm install -g @codaph/codaph

Bun installation fails

If Bun install fails:

1. Try the standalone installer:

   curl -fsSL https://bun.sh/install | bash
   

2. Or use Homebrew (macOS):

   brew install oven-sh/bun/bun
   

3. Or download from bun.sh/download

Uninstall Codaph

npm

npm uninstall -g @codaph/codaph

Optional: Remove configuration:

rm -rf ~/.codaph

npx

No uninstall needed - npx doesn’t persist packages.

Optional: Clear npm cache:

npm cache clean --force

Source

rm -rf /path/to/codaph

Optional: Remove configuration:

rm -rf ~/.codaph

Removing ~/.codaph deletes your API keys and project settings. Export important data first.

Next Steps

After installation:

Quickstart Guide

Get your first project set up in minutes.

CLI Overview

Learn about available commands and flags.

MCP Setup

Connect Claude Code via MCP.

Troubleshooting

Solutions to common problems.