Skip to main content

​
Usage

codaph hooks run <hook-name> [options]
Executes Codaph automation hooks that trigger syncs after git operations or agent completions.

​
Hook Types

​
post-commit

Runs after git commits to sync changes to Mubit. 
codaph hooks run post-commit

​
post-push

Runs after git pushes to sync changes to Mubit. 
codaph hooks run post-push

​
agent-complete

Runs when an agent coding session completes. 
codaph hooks run agent-complete

​
Options

​
--provider
string
Agent provider for agent-complete hook: codex, claude-code, or gemini-cli.
​
--quiet
boolean
default:"false"
Suppress output (useful for git hooks).
​
--cwd
string
Working directory path. Defaults to current directory.
​
--install
boolean
default:"false"
Install the hook into git hooks directory.

​
Hook Installation

Hooks are automatically installed during codaph init but can be manually installed:

​
Install post-commit hook

codaph hooks run post-commit --install
This creates .git/hooks/post-commit with: 
#!/bin/sh
codaph hooks run post-commit --quiet

​
Install agent-complete hook

codaph hooks run agent-complete --provider codex --install
This installs provider-specific hooks in:
  • Codex: .codex/hooks/on-agent-complete
  • Claude Code: .claude/hooks/on-agent-complete
  • Gemini CLI: .gemini/hooks/on-agent-complete

​
Hook Behavior

When a hook runs:
  1. Checks sync lock - Skips if another sync is running
  2. Acquires lock - Prevents concurrent syncs
  3. Runs sync workflow:
    • Push phase: Syncs local events to Mubit
    • Pull phase: Fetches remote updates (if cooldown elapsed)
  4. Releases lock - Allows future syncs
  5. Logs results - Appends to .codaph/sync-automation-log.jsonl

​
Sync Triggers

Hooks are triggered by:
HookTriggerWhen
post-commitGit commitAfter git commit completes
post-pushGit pushAfter git push completes
agent-completeAgent session endWhen Codex/Claude/Gemini finishes

​
Cooldown

Remote pulls have a cooldown to avoid excessive API calls:
  • Default: 300 seconds (5 minutes)
  • Configurable: Set in project settings
Hooks will:
  • Always run local push
  • Skip remote pull if within cooldown window

​
Sync Lock

The sync lock (.codaph/sync-lock.json) prevents concurrent syncs: 
{
  "locked": true,
  "lockedAt": "2026-03-01T10:00:00.000Z",
  "pid": 12345
}
If a hook finds an existing lock:
  • Waits up to 5 seconds
  • Skips if lock still held
  • Removes stale locks (process not running)

​
Automation Log

Hook runs are logged to .codaph/sync-automation-log.jsonl: 
{"trigger":"post-commit","startedAt":"2026-03-01T10:00:00.000Z","finishedAt":"2026-03-01T10:00:15.000Z","pushed":156,"pulled":0,"lockWaited":false}

​
Troubleshooting

​
Hook not running

  1. Verify hook is installed: 
    ls -la .git/hooks/post-commit
  2. Check hook is executable: 
    chmod +x .git/hooks/post-commit
  3. Verify automation is enabled: 
    codaph status

​
Hook hangs

  1. Check for stuck lock: 
    cat .codaph/sync-lock.json
  2. Remove stale lock: 
    rm .codaph/sync-lock.json

​
Hook failures

  1. Check automation log: 
    tail .codaph/sync-automation-log.jsonl
  2. Run hook manually with verbose output: 
    codaph hooks run post-commit

​
Examples

​
Test post-commit hook

codaph hooks run post-commit

​
Test agent-complete for Codex

codaph hooks run agent-complete --provider codex

​
Silent execution (for git hooks)

codaph hooks run post-commit --quiet

​
Reinstall all hooks

codaph hooks run post-commit --install
codaph hooks run post-push --install
codaph hooks run agent-complete --provider codex --install
codaph hooks run agent-complete --provider claude-code --install

Build docs developers (and LLMs) love

Get started for freeTalk to us