Quickstart

Codaph captures agent prompts, reasoning, and file diffs from your coding agents into shared Mubit memory.

Fast Path (2 commands)

npm i -g @codaph/codaph
codaph enable

codaph enable auto-detects your agents, installs hooks, and prompts for a Mubit key (optional – works local-only too). Then run codaph tui to explore.

Detailed Setup

The rest of this guide covers manual setup for those who want more control.

What You Need

Required:

A repository you want to inspect
A coding agent CLI you use (Codex, Claude Code, or Gemini CLI)
A Mubit API key for team memory (get one at console.mubit.ai, or skip for local-only)

Only needed for source/development install:

Bun 1.3.9+

Optional (recommended for query/chat quality):

OPENAI_API_KEY for OpenAI-assisted synthesis in codaph mubit query and TUI chat
OPENAI_MODEL only if you want to override the default OpenAI model (gpt-4.1-mini)

Before You Start: Keys and What They Do

Codaph uses Mubit for shared cloud memory and sync. You must configure a Mubit API key to use Mubit-backed sync and collaboration features.

Codaph can also use OpenAI for small query/chat responses on top of Mubit evidence. This is optional and affects codaph mubit query ... and the TUI chat panel (m) when agent mode is enabled.

By default, Codaph uses gpt-4.1-mini for OpenAI-assisted synthesis/chat. You can override it with OPENAI_MODEL or --openai-model <model>.

If you do not configure OpenAI, Codaph falls back to Mubit responses.

Get a Mubit API Key

Create your Mubit key before running the first sync.

Open mubit.ai, then go to console.mubit.ai.
Create an account or sign in.
Open the developer/API access area in the console.
Create an API key and copy it.
Store it securely. Do not commit it to your repository.

Add Your Keys (Recommended Setup Path)

Set global keys first so codaph init can run without prompting for missing credentials.

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

If you want OpenAI-assisted query/chat answers, add your OpenAI key too:

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

You can also use environment variables instead of codaph setup:

export MUBIT_API_KEY=<your-mubit-key>
# Optional:
export OPENAI_API_KEY=<your-openai-key>
# Optional model override (default is gpt-4.1-mini):
export OPENAI_MODEL=<your-model>

codaph init still prompts for a Mubit API key if one is not configured yet, so the wizard-first path remains valid.

Install Codaph

Choose one install path.

Option A: Published binary (recommended for most users)

Start by verifying the installed binary:

codaph --help

If you run through npx, use this fallback form when your shell does not resolve the scoped binary automatically:

npx --yes --package @codaph/codaph codaph --help

Option B: Run from source (contributors / local development)

Use this path when you are developing Codaph itself.

cd /Users/anilp/Code/codaph
bun install
bun run typecheck
bun run build

Run commands with bun run cli ... while developing from source.

Initialize Codaph in a Project

Open the repository you want to inspect and run:

cd /absolute/path/to/your/project
codaph init

What codaph init does:

creates repo-local .codaph/project.json
writes .codaph/mcp/claude-code.json (Claude Code MCP config template)
prompts for a Mubit API key if one is not configured yet
detects .codex, .claude, .gemini folders and lets you multi-select agent integrations (recognized providers are preselected)
enables repo-scoped auto-sync hooks (post-commit, and agent-complete when detectable)
stores repo sync settings

If you do not have a Mubit key yet, the wizard points you to console.mubit.ai.

Optional: Connect Claude Code via MCP

Codaph can expose a local MCP server so Claude Code can inspect Codaph status, sessions, timelines, and diffs.

Recommended setup (user scope / global):

codaph mcp setup claude --scope user --run

codaph init also writes a reusable template at:

.codaph/mcp/claude-code.json

Use that template when you prefer manual JSON merge into ~/.claude.json or repo .mcp.json.

See MCP Setup (Claude Code) for claude mcp add examples, JSON examples, and troubleshooting.

Optional: Use The Repo Skill With An Agent

Codaph also includes a repo-shared skill that teaches an agent when to use pull, mubit context, checkpoint, diagnose, handoff, and reflect.

The skill lives at:

skills/codaph-observability/SKILL.md

When your agent supports skills, reference the local absolute path to that file in the prompt:

[$codaph-observability](/absolute/path/to/codaph/skills/codaph-observability/SKILL.md)

This is useful when you want Codaph to be part of the normal workflow for Claude Code, Codex, or Gemini CLI instead of remembering each command manually.

See Skills for the full workflow and examples.

Run Your First Sync

Run the fast daily sync path after initialization:

codaph sync

What codaph sync does:

runs the fast Mubit-first sync path
pulls cloud activity into your local .codaph mirror
uses repo-local sync state and automation settings
does not replay global agent history by default (Codex / Claude Code / Gemini CLI)

Use this command for normal day-to-day usage.

Open the TUI

Launch the terminal UI to browse sessions, prompts, thoughts, and diffs:

codaph tui

Inside the TUI:

press s to run sync now (push + pull)
press r to pull cloud activity now (manual fallback)
press enter on a session to inspect prompts, thoughts, and diffs
press c to filter by contributor

Ask Mubit a Question (Optional OpenAI-assisted)

You can query Mubit directly from the CLI at project scope or narrow to one session when needed:

codaph mubit query "what changed in auth?"
codaph mubit query "what is the current direction of this repo?" --rank-by freshness
codaph mubit query "what changed in auth?" --session <session-id>

Codaph returns a Mubit response by default. If OPENAI_API_KEY is configured, Codaph can synthesize a shorter answer using OpenAI (gpt-4.1-mini by default) on top of Mubit evidence.

Use --agent or --no-agent to control OpenAI-assisted behavior for a specific query. Use --openai-model <model> to override the model for that command. Use --rank-by freshness for “current state”, “what changed”, and handoff questions. Add --explain when you want MuBit ranking diagnostics and they are available on your tenant.

In the TUI, press m to open the Mubit chat panel. OpenAI-assisted chat is optional and uses the same key/model settings when enabled.

Use Context, Checkpoints, And Handoffs (Optional Workflow)

After setup, these commands are the main building blocks for cross-agent continuity:

codaph pull --full
codaph mubit context "what should the next agent know?"
codaph mubit snapshot
codaph mubit activity --limit 20 --exclude-derived --projection compact
codaph checkpoint "before-auth-refactor"
codaph doctor mubit
codaph mubit diagnose "auth failure in CI"
codaph handoff list

Use them when you need more than the default sync and tui loop, especially when switching between Claude Code, Codex, and Gemini CLI.

Backfill Historical Agent Sessions (Optional)

If you want older local agent sessions (Codex / Claude Code / Gemini CLI) to appear in Codaph and Mubit, run:

codaph import

Use codaph import once (or occasionally). It is not part of the default daily sync path. Use --providers <csv|all|auto> if you want to limit the backfill to specific agents.

Check Status

Check local sync state and Mubit diagnostics when you finish setup:

codaph status

codaph status shows:

auto-sync state
last local push timestamp
last remote pull timestamp
Mubit snapshot diagnostics (including snapshot cap hints)

Team Quickstart (Shared Mubit Memory)

For a team using the same repo:

Everyone runs codaph init in the repo.
Everyone uses the same Mubit backend key and project id.
Each person has a unique actor id (auto-detected in most cases).
One or more contributors run codaph import to backfill local agent history.
Everyone runs codaph sync and opens codaph tui.

Read Mubit Collaboration for details and current limits.

Non-Interactive Setup (CI / demos / scripted envs)

Use explicit flags in scripted environments:

codaph setup --mubit-api-key <your-key>
# Optional OpenAI-assisted query/chat:
codaph setup --openai-api-key <your-openai-key>
cd /absolute/path/to/your/project
codaph init --yes
codaph sync

If Something Looks Wrong

Start with diagnostics before resetting anything:

codaph status
codaph doctor mubit

Then check Troubleshooting.