Troubleshooting

This page covers common Codaph issues and the fastest recovery path.

Start Here (Quick Diagnostics)

Run these first:

codaph status
codaph doctor --mubit

codaph status explains repo automation and recent sync state. codaph doctor explains resolved runtime configuration.

Claude Code /mcp Shows Codaph MCP as failed

Symptoms:

• Claude Code /mcp shows codaph with status failed
• reconnect fails immediately

What is usually happening:

• the configured command is invalid for Claude Code’s MCP launcher
• a stale or duplicate Codaph MCP entry is taking precedence
• bun run ... script wrappers fail in the MCP process environment

What to do:

1. Regenerate or inspect the Codaph template:

codaph init
cat .codaph/mcp/claude-code.json

1. Prefer user-scope setup and let Codaph print/run the correct command:

codaph mcp setup claude --scope user --run

1. If codaph is not installed globally, use the npx fallback:

codaph mcp setup claude --mode npx --scope user --run

1. Disable/remove stale duplicate Codaph entries in Claude Code /mcp.
2. Restart Claude Code and verify /mcp again.

Quick terminal check:

codaph mcp

If the process starts and waits (no immediate exit), the MCP server is launching correctly.

See MCP Setup (Claude Code) for manual claude mcp add and JSON config examples.

codaph import Looks Stuck or Runs for a Long Time

Symptoms:

• spinner keeps moving, but progress feels slow
• Mubit write timed out messages appear
• import takes much longer than expected

What is usually happening:

• codaph import is scanning local agent history (Codex / Claude Code / Gemini CLI) and writing to Mubit
• Mubit writes are slow or timing out
• some events may still succeed, so the run is partial rather than fully broken

What to do:

1. Retry with a longer timeout:

codaph import --mubit-write-timeout-ms 30000

1. If you only need the local mirror first, run local-only and retry cloud later:

codaph import --local-only
codaph sync

1. Check cloud results after import:

codaph status

Notes:

• Codaph batches Mubit ingest during import, but cloud latency can still dominate runtime.
• Repeated timeout messages do not always mean zero progress. Some writes may already have succeeded.

Teammate Sees Fewer Prompts Than You Do

Symptoms:

• same repo, same Mubit key, same project id
• teammate sees some of your prompts, but not all

What this usually means:

• sharing works
• cloud pull is partial (snapshot-limited)
• your local machine also has extra history from codaph import

What to check:

codaph status
cat .codaph/project.json

Compare on both machines:

• mubitProjectId
• mubitRunScope
• snapshot fingerprint (fp=...)
• received, imported, dedup

If both users have the same snapshot fingerprint, they are pulling the same cloud snapshot.

What to do:

• run codaph sync again on the teammate machine
• run codaph import on the originating machine to backfill history into Mubit
• use a smaller/fresher session for demos when snapshot limits matter

Read Mubit Collaboration for the full explanation.

codaph sync Does Not Show Historical Agent Sessions

Symptoms:

• codaph sync runs quickly but old local agent sessions do not appear

This is expected.

codaph sync is the fast daily sync path. Historical agent replay moved to:

codaph import

Use codaph import once (or occasionally) when you need local history backfill.

Mubit Shows Disabled (Mubit:off)

Symptoms:

• TUI header shows Mubit:off
• cloud pull fails
• Mubit query commands show disabled state

Checks:

codaph doctor --mubit

Fixes:

• set MUBIT_API_KEY
• run codaph init again if you skipped Mubit during setup
• verify your shell environment is available in the terminal where you run Codaph
• confirm you did not force --no-mubit

Auto-Sync Is Off

Symptoms:

• codaph status shows Automation: disabled
• commits do not trigger Codaph sync behavior

Fix:

codaph sync setup --yes

If agent-complete hook setup is partial, Codaph prints a manual command to attach:

codaph hooks run agent-complete --quiet

Git post-commit hook can still be enabled even when agent-complete auto-detection is unavailable.

Another Sync Is Already Running

Symptoms:

• Another Codaph sync is already running for this repo

Cause:

• another sync process is active
• or a previous run exited unexpectedly and left a stale lock

What to do:

• wait a few seconds and retry
• rerun codaph sync (Codaph now attempts to reclaim stale locks automatically)

No Agent History for This Repo

Symptoms:

• push/import output says No agent history for this repo

What it means:

• Codaph scanned local agent history/transcript locations
• no session/transcript files matched the current repository path (or linked Git worktree paths)

What to do:

• confirm you are in the correct repo root
• confirm the agent sessions/transcripts you expect were created in this repo path or linked worktree paths
• run codaph import --cwd /absolute/path/to/repo if you are invoking from another directory
• if you intentionally want only the current path, use codaph import --no-worktrees
• try codaph import --providers codex (or claude-code / gemini-cli) to isolate one provider during debugging

Mubit Query Returns Weak Results

Symptoms:

• answer is empty or generic
• evidence list is small

What to do:

• ask a narrower question
• point to a specific file, prompt, or session
• increase --limit
• use --raw or --no-agent to debug the underlying Mubit response

Example:

codaph mubit query "what changed in auth.ts recently?" --limit 12
codaph mubit query "what changed in auth.ts during the last session?" --session <session-id> --limit 12

TUI Layout Looks Broken

Symptoms:

• borders wrap or clip
• panes overlap

Fixes:

• use a wider terminal window
• reduce terminal zoom
• use a monospaced font
• restart the terminal after upgrading Codaph

Reset Local Codaph State (Safe)

Use this when local mirror files are inconsistent and you want to rebuild from scratch.

rm -rf .codaph
codaph import
codaph sync

This resets local state only. It does not delete Mubit cloud data.