Skip to main content

​
Doctor Command

The codaph doctor command provides a comprehensive diagnostic report of your Codaph setup. 
codaph doctor
Example Output: 
cwd: /Users/you/project
repoId(local): a1b2c3d4e5f6
Mubit project id: owner/repo
Mubit run scope: project
Mubit actor id: yourusername
env MUBIT_API_KEY present: yes
flag/env key resolved: yes
Mubit requested: yes
Mubit runtime: enabled
Mubit run scope preview: codaph:owner/repo
Mubit write timeout: 15000ms
Sync automation: enabled (post-commit:on, agent-complete:on, autoPull:on, tuiWarm:on, cooldown=300s)
Remote sync state: lastSuccess=2026-03-03T08:15:22.123Z received=148 imported=12 dedup=136 sameSnapshot=0 capped=no pending=no
OpenAI key present: no
OpenAI agent: disabled
Mubit setup looks valid from env/flags.

​
What Doctor Checks

  • Current working directory and repo identification
  • Mubit configuration: API key, project ID, actor ID, run scope
  • Environment variables: MUBIT_API_KEY, CODEX_PATH, etc.
  • Sync automation: Hook status, cooldown settings
  • Remote sync state: Last successful sync, deduplication stats
  • OpenAI integration: API key and agent status
Source: src/index.ts:557 (doctor function)

​
Common Issues

​
Mubit Sync Issues

​
”Mubit is disabled”

Error: Mubit is disabled. Set MUBIT_API_KEY (or MUBIT_APIKEY) and use --mubit.
Cause: No Mubit API key found in environment or settings. Fix:
  1. Get an API key from console.mubit.ai
  2. Save it globally:
codaph setup --mubit-api-key your-key-here
Or set as environment variable: 
export MUBIT_API_KEY=your-key-here
  1. Verify with:
codaph doctor
Look for: Mubit runtime: enabled

​
”Mubit write failed”

Error: Mubit write failed: timeout after 15000ms
Cause: Network timeout or slow connection to Mubit API. Fix:
  1. Check network connectivity:
ping api.mubit.ai
  1. Increase timeout:
codaph push --mubit-write-timeout-ms 30000
  1. For bulk imports, use local-only mode then repair:
codaph push --local-only
codaph repair cloud
Architecture note: The ingest pipeline has a fail-open circuit breaker after consecutive Mubit errors. Local mirror writes always succeed; cloud writes are best-effort. Source: src/lib/ingest-pipeline.ts:167

​
High Deduplication Count

Observation: codaph pull shows dedup=348, imported=0
Cause: Events already exist in local mirror (duplicate sync). This is normal if:
  • You’ve already run codaph pull recently
  • Multiple users are syncing the same project
  • You ran codaph repair cloud (replays existing events)
No action needed — deduplication is working correctly.

​
”Suspected Server Cap”

Diagnostic: Mubit snapshot appears capped (events=1200 despite requested 1200); Codaph is deduping locally.
Cause: Mubit timeline API has a maximum page size limit. Impact: You may not see events beyond the cap in a single pull. Mitigation:
  • Codaph automatically deduplicates across multiple pulls
  • Increase pull frequency (reduce cooldown)
  • Use session-scoped runs for large projects
Note: This is a snapshot API limitation, not a Codaph error. Local sync continues correctly. Source: src/mubit-remote-sync.ts:395

​
Sync Automation Issues

​
Git Hooks Not Triggering

Symptom: git commit doesn’t trigger codaph pull
Check hook installation: 
cat .git/hooks/post-commit
Should contain: 
codaph hooks run post-commit --quiet
Reinstall hooks: 
codaph init --force
Verify automation settings: 
codaph doctor
Look for: Sync automation: enabled (post-commit:on, ...) Source: src/sync-automation.ts:89

​
”Another Codaph sync is already running”

Error: Another Codaph sync is already running for this repo. Try again in a few seconds.
Cause: Sync lock file (.codaph/sync-lock.json) exists from previous operation. Fix:
  1. Wait a few seconds for the other process to finish
  2. If stuck (crashed process), manually remove lock:
rm .codaph/sync-lock.json
  1. Verify no other Codaph processes are running:
ps aux | grep codaph
Source: src/sync-automation.ts:84

​
Cooldown Preventing Pull

Symptom: codaph pull says “No remote changes detected” immediately after push
Cause: Remote pull cooldown (default 300s = 5 minutes) prevents excessive API calls. Check cooldown: 
codaph doctor
Look for: cooldown=300s Override for single pull: 
codaph pull --refresh
Adjust global cooldown: Edit ~/.codaph/settings.json: 
{
  "remotePullCooldownSec": 60
}
Source: src/sync-automation.ts:96

​
Agent Provider Issues

​
”No agent providers detected”

Symptom: codaph push reports scan 0/0 | match 0 | events 0
Cause: No agent marker directories (.codex/, .claude/, etc.) found. Fix:
  1. Run an agent first:
codex exec "test prompt"
  1. Verify marker directory exists:
ls -la .codex/
  1. Explicitly specify providers:
codaph init --providers codex,claude
Supported providers:
  • Codex (OpenAI): .codex/
  • Claude Code (Anthropic): .claude/
  • Gemini CLI (Google): ~/.config/gemini/
Source: src/lib/agent-providers.ts:54

​
Provider History Import Failed

Error: Codex history import failed: ENOENT: no such file or directory
Cause: Agent history directory missing or inaccessible. Fix:
  1. Check agent history location:
# Codex
ls ~/.codex/history/

# Claude Code  
ls ~/.claude/projects/*/history/

# Gemini CLI
ls ~/.config/gemini/history/
  1. Verify file permissions:
chmod -R u+r ~/.codex/
  1. Skip failed provider:
codaph push --providers codex
Source: src/index.ts:1449

​
Session/Timeline Issues

​
”Session not found”

Error: Session abc123de not found
Cause: Session ID doesn’t exist in local mirror. Fix:
  1. List available sessions:
codaph sessions
  1. Pull latest from Mubit:
codaph pull
  1. Verify session ID format (8+ hex chars):
codaph sessions | grep abc123

​
Empty Timeline

Symptom: codaph timeline --session abc123 shows no events
Cause: Session exists but has no events, or events filtered out. Fix:
  1. Check session exists:
codaph sessions
  1. Try without filters:
codaph timeline --session abc123
  1. Check mirror directly:
cat .codaph/sessions/abc123de/events.jsonl | wc -l

​
TUI Issues

​
”TUI requires an interactive terminal”

Error: TUI requires an interactive terminal.
Cause: Running in non-interactive environment (CI, piped input, etc.). Fix: Use CLI commands instead: 
codaph sessions
codaph timeline --session abc123
codaph diff --session abc123

​
TUI Rendering Issues

Symptom: Garbled text, overlapping lines, or incorrect colors
Fix:
  1. Check terminal size:
echo $COLUMNS $LINES
Minimum: 80x24
  1. Try different terminal:
TERM=xterm-256color codaph tui
  1. Update terminal emulator to support:
    • ANSI colors
    • UTF-8
    • Cursor positioning

​
Installation Issues

​
”command not found: codaph”

Cause: Codaph not installed or not in PATH. Fix: 
# Install globally
npm install -g codaph

# Verify
which codaph
codaph --version

​
Permission Denied

Error: EACCES: permission denied, mkdir '.codaph'
Cause: No write permissions in current directory. Fix: 
# Check permissions
ls -la

# Fix ownership
sudo chown -R $(whoami) .

# Or run in different directory
cd ~/my-project
codaph init

​
Diagnostic Commands

​
Check Configuration

codaph doctor
Comprehensive diagnostic report.

​
Check Sync Status

codaph status
Shows:
  • Local mirror stats
  • Last sync times
  • Automation status
  • Pending triggers

​
Inspect Sync State

cat .codaph/mubit-remote-sync-state.json | jq
Shows:
  • Last successful sync timestamp
  • Timeline counts
  • Deduplication stats
  • Error messages

​
Check Sync Logs

tail -f .codaph/sync-automation-log.jsonl
Real-time sync automation events.

​
Verify Mirror Integrity

# Count sessions
ls .codaph/sessions/ | wc -l

# Count events
find .codaph/sessions/ -name "events.jsonl" -exec wc -l {} + | tail -1

# Check manifest
cat .codaph/manifest.json | jq

​
Advanced Diagnostics

​
Enable Verbose Logging

codaph push --verbose
codaph pull --verbose
codaph repair cloud --verbose

​
Force Refresh

codaph pull --refresh
Ignores cooldown and forces fresh fetch from Mubit.

​
Test Mubit Connectivity

codaph mubit query "test" --session dummy
Attempts to query Mubit API. If it fails, check:
  • API key validity
  • Network connectivity
  • Firewall/proxy settings

​
Repair Cloud Sync

codaph repair cloud
Replays local mirror to Mubit. Use when:
  • Cloud sync was interrupted
  • Events missing from Mubit
  • Changed project ID or run scope

​
Getting Help

If issues persist:
  1. Check documentation: docs.codaph.dev
  2. Run diagnostics: codaph doctor
  3. Check logs: .codaph/sync-automation-log.jsonl
  4. Report issues: github.com/codaph/codaph/issues
Include:
  • Output of codaph doctor
  • Error messages (redact sensitive data)
  • Steps to reproduce
  • Operating system and Node.js version

Build docs developers (and LLMs) love

Get started for freeTalk to us