Skip to main content
Initialize Codaph for a project, creating .codaph/ directory and configuring sync automation.

​
Usage

codaph init [options]

​
Description

The init command:
  1. Creates .codaph/ directory for local event storage
  2. Configures agent providers (Codex, Claude Code, Gemini CLI)
  3. Installs sync automation hooks (git post-commit, agent-complete)
  4. Saves project settings
  5. Generates MCP server configuration templates
Run this once per project after codaph setup.

​
Flags

​
--cwd
string
Project directory (defaults to current directory)Auto-detects git repo root if inside a git repository
​
--name
string
Project name (defaults to directory basename or detected project ID)
​
--mubit-project-id
string
Mubit project ID (auto-detected from git remote owner/repo if available)
​
--mubit-run-scope
string
Mubit run scope: project or session
  • project (default with project ID) - Shared run across contributors
  • session - Separate run per session
​
--providers
string
Comma-separated agent providers: codex, claude-code, geminiExamples:
  • codex,claude-code
  • all (all providers)
  • auto (auto-detect from marker directories)
Interactive multi-select prompt if not specified
​
--agent-hooks
string
Comma-separated providers for agent-complete hooksExamples:
  • codex,claude-code
  • all
  • none (skip agent-complete hooks)
Interactive multi-select prompt if not specified
​
--no-auto-sync
boolean
default:"false"
Skip installing sync automation hooks
​
--yes
boolean
default:"false"
Accept defaults without prompting (non-interactive mode)
​
--force
boolean
default:"false"
Reinstall automation hooks even if already enabled
​
--json
boolean
default:"false"
Output JSON instead of human-readable text

​
Examples

​
Interactive Init

cd ~/my-project
codaph init
Prompts for:
  • Agent providers (auto-detects from .codex/, .claude/, .gemini/)
  • Agent-complete hook providers

​
Non-interactive Init

codaph init --yes
Uses auto-detected defaults for all options.

​
Specify Providers

codaph init --providers codex,claude-code --agent-hooks codex

​
Skip Automation

codaph init --no-auto-sync

​
Custom Project ID

codaph init --mubit-project-id my-org/my-project

​
Output

$ codaph init

✓ Initialized Codaph /home/alice/my-project
Repo id: owner/my-project
Mubit API: ✓ configured
Mubit project: owner/my-project | run scope: project
Agents: Codex, Claude Code | recognized=Codex, Claude Code
Local project config: /home/alice/my-project/.codaph/project.json
Claude MCP template: /home/alice/my-project/.codaph/mcp/claude-code.json
MCP setup: use `codaph mcp setup claude` (user-scope recommended) or merge the template
Auto-sync: enabled (post-commit:on, agent-complete:on)
Agent hooks: Codex, Claude Code
ℹ Next
  1. codaph pull (cloud -> local, daily)
  2. codaph push (optional one-time agent history backfill)
  3. codaph tui

​
JSON Output

{
  "cwd": "/home/alice/my-project",
  "repoId": "owner/my-project",
  "projectConfigPath": "/home/alice/my-project/.codaph/project.json",
  "claudeMcpTemplatePath": "/home/alice/my-project/.codaph/mcp/claude-code.json",
  "mubitConfigured": true,
  "mubitProjectId": "owner/my-project",
  "mubitRunScope": "project",
  "recognizedAgentProviders": ["codex", "claude-code"],
  "agentProviders": ["codex", "claude-code"],
  "automation": {
    "enabled": true,
    "gitPostCommit": true,
    "agentComplete": true,
    "agentCompleteProviders": ["codex", "claude-code"]
  }
}

​
Files Created

  • .codaph/ - Event storage directory
  • .codaph/project.json - Project configuration
  • .codaph/mcp/claude-code.json - MCP server template
  • .git/hooks/post-commit - Git hook (if automation enabled)
  • .codex/.codaph-hook - Codex agent hook (if selected)
  • .claude/.codaph-hook - Claude Code agent hook (if selected)

​
Next Steps

After initialization: 
# Sync cloud activity to local
codaph pull

# Optional: backfill historical agent sessions
codaph push

# Browse sessions in TUI
codaph tui

Build docs developers (and LLMs) love

Get started for freeTalk to us