FAQ

General

What is Codaph?

Codaph is a project memory system for AI coding agents. It captures, stores, and synchronizes agent sessions across:

Local mirror: Append-only JSONL store in .codaph/ for deterministic timeline rendering
Mubit cloud: Shared collaborative memory for cross-contributor context and semantic search

Supported agents:

Codex (OpenAI)
Claude Code (Anthropic)
Gemini CLI (Google)

Why do I need Codaph?

Without Codaph:

Agent sessions are scattered across local files
No shared context between team members
Can’t query “what did the agent do last week?”
Difficult to audit or review agent changes

With Codaph:

Unified timeline: All agent sessions in one place
Collaborative memory: Team shares agent context via Mubit
Semantic search: Query sessions by content, not just file name
Git-like workflow: push local history, pull team context
Diffs: See exactly what the agent changed

Is Codaph free?

Codaph CLI is open source (check LICENSE file).Mubit cloud (collaborative memory backend) requires an API key:

Get one from console.mubit.ai
Pricing varies (check Mubit website)

Local-only mode is free:

codaph push --local-only
codaph tui  # Local sessions only

How does Codaph relate to Mubit?

Codaph is the CLI/TUI for capturing agent sessions.Mubit is the cloud memory backend that provides:

Shared project runs across contributors
Semantic search and context retrieval
Timeline synchronization

Architecture:

Agent → Codaph → Local Mirror (.codaph/)
               ↓
               → Mubit Cloud (shared memory)

You can use Codaph without Mubit (local-only), but you lose:

Collaborative context
Semantic search
Cloud backups

Setup & Installation

How do I install Codaph?

npm install -g codaph

Verify installation:

codaph --version

Then initialize your project:

cd ~/my-project
codaph init

What is codaph init doing?

codaph init sets up Codaph for your project:

Creates .codaph/ directory (local mirror)
Detects agent providers (Codex, Claude, Gemini)
Prompts for Mubit API key (optional)
Auto-detects GitHub project ID and actor ID
Installs git hooks (optional):
- post-commit: Auto-pull after commits
- post-push: Auto-pull after pushes
Installs agent hooks (optional):
- .codex/hooks/agent-complete: Auto-sync after Codex runs
Saves project settings to .codaph/project.json

Flags:

--yes: Skip prompts, use defaults
--force: Overwrite existing config
--no-auto-sync: Skip hook installation
--providers codex,claude: Explicitly select providers

Do I need a Mubit API key?

No — Codaph works in local-only mode without Mubit.However, without Mubit you lose:

Collaborative context across team members
Cloud backup of agent sessions
Semantic search via codaph mubit query

Get a key from console.mubit.ai and save it:

codaph setup --mubit-api-key your-key-here

Or set as environment variable:

export MUBIT_API_KEY=your-key-here

Can I use Codaph in multiple projects?

Yes — each project has its own .codaph/ directory.Global settings (API keys, actor ID) are shared:

~/.codaph/settings.json

Per-project settings (providers, sync config):

/path/to/project/.codaph/project.json

Project registry (list all Codaph projects):

codaph projects list

Capturing Sessions

How do I capture agent sessions?

Recommended workflow (import history after running agents):

# 1. Run your agent normally
codex exec "fix the bug"

# 2. Import session to Codaph
codaph push

Alternative (direct capture during agent run):

codaph exec "fix the bug"  # Wraps codex exec --json
codaph run "fix the bug"   # Uses @openai/codex-sdk

See Direct Capture for details.

What is codaph push?

codaph push imports agent history from local directories to Codaph:What it does:

Scans agent marker directories (.codex/, .claude/, ~/.config/gemini/)
Reads agent history files (JSON/JSONL)
Parses events and sessions
Writes to local mirror (.codaph/)
Syncs to Mubit cloud (if enabled)
Deduplicates events by ID

Flags:

--providers codex,claude: Select specific providers
--local-only: Skip Mubit sync
--no-worktrees: Don’t scan git worktrees

Example:

codaph push
# Output: Synced 48 events from 3/12 agent history files (sessions: 3)

Does Codaph slow down my agent?

No — Codaph imports history after agents run, not during.Direct capture (codaph run / codaph exec) adds:

Minimal latency (~5-10ms per event for local mirror write)
Mubit writes are async and fail-open (don’t block agent)

Recommended workflow avoids any overhead:

codex exec "..."   # Normal agent speed
codaph push        # Import after (runs in ~1-2 seconds)

Can I capture sessions from multiple agents?

Yes — Codaph supports multiple providers simultaneously:

codaph init --providers codex,claude,gemini
codaph push

Supported providers:

Codex (OpenAI): .codex/history/
Claude Code (Anthropic): .claude/projects/*/history/
Gemini CLI (Google): ~/.config/gemini/history/

All sessions appear in unified timeline:

codaph sessions
# Shows sessions from all providers

Syncing & Collaboration

What is codaph pull?

codaph pull syncs agent sessions from Mubit cloud to your local mirror.Workflow:

Fetches timeline from Mubit project run
Parses events from multiple sources:
- Main timeline (codaph:<project>)
- Prompt timeline (codaph:<project>:prompt)
- Session summaries (codaph:<project>:session-summary)
- Diffs (codaph:<project>:diff)
Writes events to local mirror (.codaph/)
Deduplicates by event ID
Updates sync state (.codaph/mubit-remote-sync-state.json)

Example:

codaph pull
# Output: Synced 148 remote events (12 new, 136 dedup)

How do teammates share agent context?

Via Mubit project runs:

Alice runs agent and pushes:
```
codex exec "add feature X"
codaph push
```

Bob pulls Alice’s context:

codaph pull
codaph sessions  # Sees Alice's session

Bob runs agent with Alice’s context:

codex exec "improve feature X"
codaph push

Mubit run scope (default: project):

All team members write to codaph:owner/repo
Shared timeline across contributors
Semantic search spans all sessions

What is the difference between push and pull?

Command	Direction	Source	Destination
`codaph push`	Local → Cloud	Agent history files	Codaph mirror + Mubit
`codaph pull`	Cloud → Local	Mubit timeline	Codaph mirror

Typical workflow:

# After running agents locally
codaph push

# Fetch teammates' sessions
codaph pull

# View combined timeline
codaph tui

What is sync automation?

Sync automation runs codaph pull automatically via git hooks:Git hooks:

post-commit: Pull after each commit
post-push: Pull after push to remote

Agent hooks:

.codex/hooks/agent-complete: Pull after Codex run
.claude/hooks/agent-complete: Pull after Claude Code run

Enable during init:

codaph init  # Prompts for hook installation

Or manually:

codaph init --force  # Reinstalls hooks

Disable:

rm .git/hooks/post-commit
rm .git/hooks/post-push

See Sync Automation for details.

Advanced Features

What are git worktrees and how does Codaph handle them?

Git worktrees let you check out multiple branches simultaneously:

git worktree add ../myapp-feature feature/auth
git worktree add ../myapp-hotfix hotfix/bug

Codaph automatically detects worktrees and imports agent history from all:

cd ~/myapp
codaph push
# Scans: ~/myapp, ~/myapp-feature, ~/myapp-hotfix

Disable worktree scanning:

codaph push --no-worktrees

See Worktree Support for details.

What is codaph repair cloud?

codaph repair cloud replays your local mirror to Mubit cloud.Use when:

Cloud sync was interrupted
Events missing from Mubit
Changed project ID or run scope

What it does:

Scans local .codaph/sessions/
Reads all events from JSONL files
Writes to Mubit with deduplication
Republishes shared artifacts (session summaries, diffs)

Example:

codaph repair cloud
# Output: backfill sessions=12 attempted=348 accepted=348

See Repair Cloud for details.

Can I run Codaph in CI/CD?

Yes — use --json flag for machine-readable output:

codaph push --json
codaph pull --json
codaph status --json

Example CI step:

- name: Sync agent sessions
  run: |
    export MUBIT_API_KEY=${{ secrets.MUBIT_API_KEY }}
    codaph pull
    codaph push --providers codex
  env:
    MUBIT_API_KEY: ${{ secrets.MUBIT_API_KEY }}

Non-interactive mode (no prompts):

codaph init --yes
codaph push --json

What is the TUI?

TUI (Text User Interface) is an interactive terminal viewer:

codaph tui

Features:

Session list: Browse all captured sessions
Timeline view: See event stream for a session
Diff view: Review code changes
Keyboard navigation: Arrow keys, vim bindings
Live updates: Auto-refreshes on new sessions

Requirements:

Interactive terminal (no CI/headless)
Minimum size: 80x24
ANSI color support

Alternative (CLI):

codaph sessions
codaph timeline --session abc123
codaph diff --session abc123

Troubleshooting

How do I debug Codaph issues?

Start with diagnostics:

codaph doctor

This checks:

Mubit API key
Project configuration
Sync automation status
Recent sync errors

Check sync state:

codaph status
cat .codaph/mubit-remote-sync-state.json | jq

View sync logs:

tail -f .codaph/sync-automation-log.jsonl

See Troubleshooting for common issues.

Why is Mubit disabled?

Error: Mubit is disabled. Set MUBIT_API_KEY...Cause: No API key found.Fix:

codaph setup --mubit-api-key your-key-here
# Or:
export MUBIT_API_KEY=your-key-here

Verify:

codaph doctor
# Look for: "Mubit runtime: enabled"

Why are no sessions appearing?

Check agent history exists:

ls .codex/history/
ls ~/.claude/projects/*/history/

Try explicit provider:

codaph push --providers codex

Check mirror:

ls .codaph/sessions/

Pull from Mubit:

codaph pull
codaph sessions

What if git hooks conflict with other tools?

Codaph hooks call codaph hooks run <hook>, which:

Acquires sync lock
Runs codaph pull (if automation enabled)
Releases lock

Hook managers (e.g., Husky) are detected automatically.Manual hook integration:

# .git/hooks/post-commit
#!/bin/sh

# Your other hooks
npm run lint-staged

# Codaph hook
codaph hooks run post-commit --quiet || true

The || true ensures Codaph errors don’t block commits.

Architecture & Security

Where is my data stored?

Local mirror (.codaph/):

Append-only JSONL files
Session metadata in sessions/*/events.jsonl
Manifest in manifest.json
Sparse indexes for performance

Mubit cloud (if enabled):

Events written to project runs
Stored in Mubit infrastructure
Subject to Mubit privacy policy

Settings:

Global: ~/.codaph/settings.json
Per-project: .codaph/project.json

Is my code sent to Mubit?

Yes, if Mubit is enabled and you run codaph push.What is sent:

Event payloads (prompts, responses, tool calls)
Code snippets from diffs
File paths (redacted by default)

What is NOT sent:

Full file contents (only diffs)
Credentials (redacted via security module)
Environment variables (redacted)

Redaction (src/lib/security.ts:26):

Strips secrets from payloads
Removes common credential patterns
Configurable via settings

Local-only mode:

codaph push --local-only

No data sent to Mubit.

What is the dual-store architecture?

Codaph uses two storage systems:1. Local JSONL mirror (.codaph/):

Purpose: Deterministic timeline/diff rendering
Format: Append-only JSONL (one event per line)
Indexes: Manifest, sparse indexes, eventId dedup
Always succeeds: Writes never fail

2. Mubit cloud memory:

Purpose: Shared context, semantic search
Format: Mubit API (events + artifacts)
Run scopes: Project or session-level
Fail-open: Errors don’t block local writes

Event flow:

Agent → IngestPipeline → Mirror (local) + Mubit (cloud)

See Architecture Overview for details.

How does deduplication work?

Events are deduplicated by eventId hash:

eventId = sha256(
  source + threadId + sequence + eventType + timestamp
).slice(0, 24)

Deduplication happens at:

Mirror write: eventId index prevents duplicates locally
Mubit write: Mubit API deduplicates by eventId
Pull: Events already in mirror are skipped

Why high dedup counts are normal:

Multiple pulls without new remote events
Repair cloud replaying existing events
Team members pushing same sessions

Quickstart — Get started in 5 minutes
Troubleshooting — Common issues and solutions
Development — Architecture deep dive
API Reference — Complete CLI documentation

Get Started

Core Concepts

Guides

Advanced

Help

General

Setup & Installation

Capturing Sessions

Syncing & Collaboration

Advanced Features

Troubleshooting

Architecture & Security

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

Help

​General

​Setup & Installation

​Capturing Sessions

​Syncing & Collaboration

​Advanced Features

​Troubleshooting

​Architecture & Security

​Related

Build docs developers (and LLMs) love

General

Setup & Installation

Capturing Sessions

Syncing & Collaboration

Advanced Features

Troubleshooting

Architecture & Security

Related