Overview Codeph can automatically sync your local mirror and Mubit cloud memory using:
Git hooks - Trigger sync after commits and pushesAgent-complete hooks - Trigger sync when agents finish tasksAuto-pull on TUI - Warm the TUI with latest cloud data on open
From src/sync-automation.ts, automation reduces manual codaph sync commands while keeping your timeline fresh.
Git Hooks Post-Commit Hook Installed in .git/hooks/post-commit, runs after every git commit:
#!/bin/sh # .git/hooks/post-commit (installed by codaph init) codaph hooks run post-commit --quiet
Triggers a background sync to capture the repo state:
// From src/sync-automation.ts:284 async function runGitPostCommitHook ( cwd : string ) { const lock = await acquireSyncLock ( cwd ); try { await markPendingSyncTrigger ( cwd , repoId , 'post-commit' ); await runSyncWorkflow ( cwd , 'post-commit' , settings ); } finally { await releaseSyncLock ( cwd , lock ); } }
Post-commit hooks capture git status snapshots for agent context.
Post-Push Hook Installed in .git/hooks/post-push, runs after git push:
#!/bin/sh # .git/hooks/post-push (installed by codaph init) codaph hooks run post-push --quiet
Triggers sync and uploads to Mubit cloud.
Agent-Complete Hooks Overview Agent-complete hooks trigger sync when coding agents finish tasks. Different agents have different hook mechanisms:
Codex
Claude Code
Gemini CLI
Hook : .codex/hooks/agent-completeCodex runs this hook after completing a run: #!/bin/sh # .codex/hooks/agent-complete codaph hooks run agent-complete --provider codex --quiet
Installed by codaph init when Codex is detected. Hook : .claude/hooks/agent-completeClaude Code hook (future support): #!/bin/sh # .claude/hooks/agent-complete codaph hooks run agent-complete --provider claude-code --quiet
Claude Code hook support is experimental. Check agent provider docs for current status.
Hook : .gemini/hooks/agent-completeGemini CLI hook (future support): #!/bin/sh # .gemini/hooks/agent-complete codaph hooks run agent-complete --provider gemini --quiet
Installation Hooks are installed during codaph init:
// From src/sync-automation.ts:418-468 async function installProviderAgentCompleteHookBestEffort ( provider : AgentProviderId , cwd : string , hookCommands : string [] ) { const markerDir = agentProviderMarkerDir ( provider ); const hookDir = join ( cwd , markerDir , 'hooks' ); const hookPath = join ( hookDir , 'agent-complete' ); await mkdir ( hookDir , { recursive: true }); await writeFile ( hookPath , `#!/bin/sh \n ${ hookCommands . join ( ' \n ' ) } \n ` , { mode: 0o755 }); }
Agent-complete hooks require agents to support hook execution. Verify support with codaph doctor.
Sync Lock From src/sync-automation.ts:113-177, Codaph prevents concurrent sync operations:
interface SyncLock { acquired : boolean ; pid : number ; ts : string ; trigger : SyncTriggerSource ; }
Lock file : .codaph/sync-lock.json{ "acquired" : true , "pid" : 12345 , "ts" : "2024-03-01T10:00:00Z" , "trigger" : "post-commit" }
Stale locks (older than 5 minutes) are automatically released.
Sync Automation Settings From src/settings-store.ts, automation is configured per-project:
interface SyncAutomationSettings { enabled : boolean ; // Master switch gitPostCommit : boolean ; // Enable post-commit hook gitPostPush : boolean ; // Enable post-push hook (future) agentComplete : boolean ; // Enable agent-complete hooks agentCompleteProviders : AgentProviderId []; // Which agents to hook autoWarmTuiOnOpen : boolean ; // Auto-pull when TUI opens autoPullOnSync : boolean ; // Pull cloud data during sync remotePullCooldownSec : number ; // Minimum seconds between pulls }
Default Configuration const defaults : SyncAutomationSettings = { enabled: true , gitPostCommit: true , gitPostPush: false , agentComplete: true , agentCompleteProviders: [], // Auto-detected during init autoWarmTuiOnOpen: true , autoPullOnSync: true , remotePullCooldownSec: 30 };
Configuration Examples Enable all automation
Disable automation
Selective agent hooks
Manual configuration
codaph init --yes # Enables git hooks and agent-complete hooks for detected providers
codaph init --no-auto-sync # Skips hook installation, manual sync only
codaph init --agent-hooks codex,claude-code # Only install hooks for Codex and Claude Code
Edit .codaph/project.json: { "syncAutomation" : { "enabled" : true , "gitPostCommit" : true , "agentComplete" : true , "agentCompleteProviders" : [ "codex" ], "autoWarmTuiOnOpen" : false , "remotePullCooldownSec" : 60 } }
Cooldown Behavior From src/sync-automation.ts:230-262, Codaph rate-limits cloud pulls:
function shouldRunRemotePullNow ( lastPullAt : string | null , cooldownSec : number ) : boolean { if ( ! lastPullAt ) { return true ; // Never pulled before } const lastPullMs = Date . parse ( lastPullAt ); const nowMs = Date . now (); const elapsedMs = nowMs - lastPullMs ; const cooldownMs = cooldownSec * 1000 ; return elapsedMs >= cooldownMs ; }
Default cooldown : 30 secondsThis prevents excessive Mubit API calls during rapid git operations.
Manual codaph pull bypasses cooldown with --refresh flag.
Sync Trigger Sources From src/sync-automation.ts:16, Codaph tracks what triggered each sync:
type SyncTriggerSource = | 'manual' // User ran codaph sync | 'post-commit' // Git post-commit hook | 'post-push' // Git post-push hook | 'agent-complete' // Agent-complete hook | 'tui-warm' ; // TUI auto-warm on open
Sync Automation Log Location : .codaph/sync-automation-log.jsonlRecords all automated sync operations:
{ "ts" : "2024-03-01T10:00:00Z" , "trigger" : "post-commit" , "lockWaited" : false , "lockBusy" : false , "durationMs" : 1234 } { "ts" : "2024-03-01T10:05:00Z" , "trigger" : "agent-complete" , "provider" : "codex" , "lockWaited" : true , "lockBusy" : false , "durationMs" : 2345 }
Hook Manager Warnings From src/sync-automation.ts:539-583, Codaph detects hook manager conflicts:
function detectHookManagerWarnings ( cwd : string ) : string [] { const warnings : string [] = []; // Check for Husky if ( existsSync ( join ( cwd , '.husky' ))) { warnings . push ( 'Husky detected - may override Codaph git hooks' ); } // Check for Lefthook if ( existsSync ( join ( cwd , 'lefthook.yml' ))) { warnings . push ( 'Lefthook detected - may override Codaph git hooks' ); } return warnings ; }
Hook managers like Husky or Lefthook may override Codaph hooks. Manually integrate Codaph hook commands into your hook manager configuration.
Husky Integration Example # .husky/post-commit #!/bin/sh . "$( dirname " $0 ")/_/husky.sh" # Your existing hooks codaph hooks run post-commit --quiet
TUI Auto-Warm When autoWarmTuiOnOpen is enabled, the TUI runs a background pull on startup:
// From src/index.ts TUI initialization if ( auto . autoWarmTuiOnOpen && shouldRunRemotePullNow ( lastPullAt , cooldown )) { // Background pull without blocking TUI render runSyncPullPhase ({ cwd , flags , settings , triggerSource: 'tui-warm' }). catch ( err => console . warn ( 'Background pull failed:' , err )); }
This ensures you see recent cloud activity immediately when opening the TUI.
Disabling Automation Temporary Disable Skip automation for a single command:
git commit -m "WIP" --no-verify # Skips all git hooks including Codaph
Permanent Disable Remove hooks:
rm .git/hooks/post-commit rm .git/hooks/post-push rm .codex/hooks/agent-complete
Or disable in settings:
codaph init --no-auto-sync --force
Troubleshooting
Symptoms : codaph status shows no recent automation triggersDiagnosis :# Check hook files exist ls -la .git/hooks/post-commit ls -la .codex/hooks/agent-complete # Check hook is executable file .git/hooks/post-commit # Should show: executable # Check for hook manager conflicts codaph doctor
Fix :# Reinstall hooks codaph init --force # Make hooks executable chmod +x .git/hooks/post-commit chmod +x .codex/hooks/agent-complete
Symptoms : codaph status shows lock acquired with old timestampFix :# Remove stale lock rm .codaph/sync-lock.json # Or wait 5 minutes for automatic cleanup
Symptoms : Excessive Mubit API callsFix :# Increase cooldown in .codaph/project.json # "remotePullCooldownSec": 300 // 5 minutes # Or disable auto-pull # "autoPullOnSync": false
Agent-complete hook not triggered
Symptoms : Agent completes but no sync happensDiagnosis :# Check agent supports hooks codaph doctor # Manually test hook codaph hooks run agent-complete --provider codex
Fix : Verify agent supports hook execution. Some agents may require additional configuration.Best Practices
Enable automation during init
Accept defaults for most projects.
Verify hooks after init
# Check hooks installed ls -la .git/hooks/ ls -la .codex/hooks/ # Test a hook git commit --allow-empty -m "test codaph hooks" codaph status # Should show recent automation
Adjust cooldown for your workflow
Fast iterations : 30s (default)Normal development : 60-120sLarge teams : 300s (5min)
Integrate with hook managers
If using Husky/Lefthook, add Codaph commands to your hook manager config instead of letting Codaph install hooks directly.
See Also
Architecture How sync fits into the data flow
Hooks Command Manual hook execution
Status Command View automation state
Init Command Configure automation during setup