Skip to main content

​
Overview

This guide walks you through:
  1. Getting a Mubit API key
  2. Installing Codaph
  3. Setting up your first project
  4. Running your first sync
  5. Exploring the TUI
  6. Setting up MCP integration (optional)
Time to complete: 5-10 minutes

​
Prerequisites

  • A repository you want to inspect
  • A coding agent CLI you use (Codex, Claude Code, or Gemini CLI)
  • Node.js 18 or higher
  • Git installed

​
Step 1: Get Your Mubit API Key

Codaph uses Mubit for shared cloud memory and sync. You need a Mubit API key to enable collaboration features.
1

Create a Mubit account

Navigate to console.mubit.ai and create an account or sign in.
2

Generate an API key

In the Mubit console:
  1. Navigate to the developer/API access area
  2. Click Create API Key
  3. Copy the key and store it securely
Do not commit your Mubit API key to your repository. Use environment variables or Codaph’s secure settings store.
3

Optional: Get an OpenAI key

For OpenAI-assisted query/chat synthesis:
  1. Get an API key from platform.openai.com
  2. Default model is gpt-4.1-mini (configurable via OPENAI_MODEL)
Without OpenAI, Codaph falls back to Mubit responses for queries.

​
Step 2: Install Codaph

See the Installation Guide for detailed instructions. Quick options: 
npm install -g @codaph/codaph
codaph --version

​
Step 3: Configure API Keys

Set your Mubit API key globally (recommended before codaph init): 
codaph setup --mubit-api-key <your-mubit-key>

# Optional: Add OpenAI key for enhanced queries
codaph setup --openai-api-key <your-openai-key>
Keys are stored in ~/.codaph/settings.json. If you skip this step, codaph init will prompt for the Mubit key.

​
Step 4: Initialize Your Project

Navigate to your repository and run the initialization wizard:
1

Navigate to your project

cd /path/to/your/project
2

Run codaph init

codaph init
The wizard will:
  • Prompt for Mubit API key if not configured
  • Detect agent providers (.codex/, .claude/, .gemini/)
  • Let you multi-select which agents to track
  • Set up automatic sync hooks (post-commit, agent-complete)
  • Create .codaph/project.json and .codaph/mcp/claude-code.json
3

Review what was created

ls -la .codaph/
You should see:
  • project.json - Project configuration
  • mcp/claude-code.json - MCP template for Claude Code
For automated environments, use explicit flags:
codaph setup --mubit-api-key <key>
cd /path/to/project
codaph init --yes --providers codex,claude-code

​
Step 5: Run Your First Sync

Pull cloud activity and sync local state: 
codaph pull
codaph pull and codaph sync are equivalent commands. Both run the fast Mubit-first sync path.
What happens during sync:
1

Pull from Mubit

Downloads cloud timeline activity into your local .codaph/ mirror.
2

Deduplicate events

Checks for duplicate events using eventId and skips already-imported items.
3

Update state

Writes sync state to .codaph/mubit-remote-sync-state.json for cooldown tracking.

​
Step 6: Explore the TUI

Launch the terminal UI to browse agent activity: 
codaph tui

​
TUI Quick Reference

  • s - Run sync now (push + pull)
  • r - Pull cloud activity (manual refresh)
  • c - Filter by contributor/actor
  • m - Open Mubit chat panel (requires OpenAI)
Inside a session:
  • View prompts, thoughts, and reasoning
  • Browse file diffs with syntax highlighting
  • See timeline of events with timestamps
Press ? inside the TUI to see all available keyboard shortcuts.

​
Step 7: Query Mubit (Optional)

Ask semantic questions about your codebase: 
codaph mubit query "what changed in auth?" --session <session-id>
With OPENAI_API_KEY configured, Codaph synthesizes concise answers using OpenAI on top of Mubit evidence. Without it, you get raw Mubit responses.

​
Step 8: Backfill History (Optional)

Import older local agent sessions from Codex, Claude Code, or Gemini CLI: 
codaph push
codaph push scans your entire agent history directories (.codex/, .claude/, .gemini/). Run once or occasionally, not daily.
What gets imported:
1

Scan directories

Looks for agent history files in marker directories.
2

Parse sessions

Extracts prompts, thoughts, and events from agent JSON/JSONL files.
3

Ingest to mirror

Writes canonical events to .codaph/ with deduplication.
4

Sync to Mubit

Publishes imported sessions to Mubit for team visibility.

​
Step 9: Set Up MCP Integration (Optional)

Connect Claude Code to Codaph via MCP for programmatic access: 
codaph mcp setup claude --scope user --run
User scope (~/.claude.json) is recommended because one setup works across all repos. Codaph tools accept cwd to target specific projects.
Verify the connection:
  1. Open Claude Code
  2. Navigate to /mcp
  3. Confirm codaph shows connected
See the MCP Setup Guide for troubleshooting and advanced configuration.

​
Verify Your Setup

Check that everything is working: 
codaph doctor
Expected output from codaph status:
  • Mubit runtime: enabled
  • Sync automation: enabled
  • Last remote pull: recent timestamp
  • Agent providers: your selected providers (codex, claude-code, etc.)

​
Team Quickstart

For teams sharing a Mubit project:
1

Everyone runs codaph init

Each team member initializes Codaph in the shared repository.
2

Use the same Mubit project ID

Set --mubit-project-id <owner/repo> or let Codaph auto-detect from git remote origin.
3

Unique actor IDs

Codaph auto-detects actor ID from gh api user, git config, or $USER. Ensure each person has a unique ID.
4

Backfill once

One or more contributors run codaph push to seed Mubit with historical sessions.
5

Everyone syncs daily

Team members run codaph pull to see each other’s agent activity.
See Collaboration with Mubit for advanced team workflows.

​
Troubleshooting

Check your API key:
codaph doctor
Verify key is set:
echo $MUBIT_API_KEY
Or check settings file:
cat ~/.codaph/settings.json
Run a backfill to import local history:
codaph push
Check if agent directories exist:
ls -la .codex .claude .gemini
Check sync state:
codaph status
cat .codaph/mubit-remote-sync-state.json
Try a fresh pull:
codaph pull --refresh
Test the server directly:
codaph mcp
Re-run setup:
codaph mcp setup claude --run
Check Claude Code /mcp panel for errors.
For more help, see the Troubleshooting Guide.

​
Next Steps

TUI Guide

Master all TUI keyboard shortcuts and workflows.

CLI Reference

Explore all available commands and flags.

Collaboration

Set up team workflows with shared Mubit memory.

Architecture

Understand Codaph’s dual-store design and pipeline flow.

Build docs developers (and LLMs) love

Get started for freeTalk to us