Installation

Overview

Codaph can be installed in three ways:

npm (Global) - Recommended for most users
npx (No Install) - Quick testing without global install
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:

Install the package

npm install -g @codaph/codaph

Verify installation

codaph --version
codaph --help

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:

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:

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.

Clone the repository

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

Install dependencies

bun install

Run type check and tests

bun run typecheck
bun test

Build the project

bun run build

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

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

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:

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
Recommended
Optional

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

Environment Setup

After installation, configure your environment:

Get a Mubit API key

Create one at console.mubit.ai

Configure Codaph

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

Or use environment variables:

export MUBIT_API_KEY=<your-key>

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

Verify configuration

codaph doctor

Configuration Files

Codaph stores configuration in these locations:

Global Settings

Location: ~/.codaph/settings.jsonStores:

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.jsonTracks initialized projects:

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

Project Configuration

Location: <project>/.codaph/project.jsonPer-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.jsonClaude Code MCP configuration template:

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

Upgrade Codaph

Keep Codaph up to date:

npm
npx
Source

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

npx always uses the latest version by default. No manual update needed.Force cache clear:

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

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:

Check npm global bin location:
```
npm config get prefix
```

Add to PATH:

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

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:

Try the standalone installer:

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

Or use Homebrew (macOS):
```
brew install oven-sh/bun/bun
```
Or download from bun.sh/download

Uninstall Codaph

npm
npx
Source

npm uninstall -g @codaph/codaph

Optional: Remove configuration:

rm -rf ~/.codaph

No uninstall needed - npx doesn’t persist packages.Optional: Clear npm cache:

npm cache clean --force

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.

Get Started

Core Concepts

Guides

Advanced

Help

Overview

Method 1: npm (Global Install)

Advantages

Use When

Method 2: npx (No Install)

Advantages

Use When

MCP Setup with npx

Method 3: From Source (Development)

Development Commands

Advantages

Use When

Verify Installation

System Requirements

Environment Setup

Configuration Files

Upgrade Codaph

Troubleshooting

Uninstall Codaph

Next Steps

Quickstart Guide

CLI Overview

MCP Setup

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

Help

​Overview

​Method 1: npm (Global Install)

​Advantages

​Use When

​Method 2: npx (No Install)

​Advantages

​Use When

​MCP Setup with npx

​Method 3: From Source (Development)

​Development Commands

​Advantages

​Use When

​Verify Installation

​System Requirements

​Environment Setup

​Configuration Files

​Upgrade Codaph

​Troubleshooting

​Uninstall Codaph

​Next Steps

Quickstart Guide

CLI Overview

MCP Setup

Troubleshooting

Build docs developers (and LLMs) love

Overview

Method 1: npm (Global Install)

Advantages

Use When

Method 2: npx (No Install)

Advantages

Use When

MCP Setup with npx

Method 3: From Source (Development)

Development Commands

Advantages

Use When

Verify Installation

System Requirements

Environment Setup

Configuration Files

Upgrade Codaph

Troubleshooting

Uninstall Codaph

Next Steps