Skip to main content
Import local agent history (Codex, Claude Code, Gemini CLI) into Codaph’s .codaph/ mirror and Mubit cloud memory.

​
Usage

codaph push [options]
Alias: codaph import (compatibility)

​
Description

The push command:
  1. Scans local agent history directories (.codex/, .claude/, .gemini/)
  2. Parses agent session files (JSONL format)
  3. Imports events to .codaph/ mirror
  4. Uploads events to Mubit (if enabled)
  5. Publishes shared session artifacts (diffs, summaries)
This is typically run once after codaph init to backfill historical sessions. Daily workflow uses codaph pull instead.

​
Flags

​
--cwd
string
Working directory (defaults to current directory)
​
--providers
string
Comma-separated agent providers to importOptions:
  • codex,claude-code,gemini (specific providers)
  • all (all supported providers)
  • auto (auto-detect from project settings)
Default: auto-detect or project settings
​
--local-only
boolean
default:"false"
Import to local .codaph/ only (skip Mubit upload)
​
--no-worktrees
boolean
default:"false"
Skip scanning git worktreesBy default, push scans main repo + worktrees for agent history
​
--json
boolean
default:"false"
Output JSON instead of human-readable summary

​
Mubit Configuration

​
--mubit-api-key
string
Override Mubit API key (or use MUBIT_API_KEY env var)
​
--mubit-project-id
string
Override Mubit project ID
​
--mubit-actor-id
string
Override actor ID

​
Examples

​
Basic Push

codaph push
Output: 
⠋ Scanning agent history [##############] 45s | scan 120/120 | match 45 | events 1523 | line 8934 | session abc123de | ~/.codex/sessions/2024-01/session_abc123.jsonl
Push (local->cloud): local events imported=1523, files=45/120, sessions=12, Mubit=on | providers=Codex:e1523/f45
Push complete. Daily `codaph pull` does not replay local agent history.

​
Push Specific Providers

codaph push --providers codex,claude-code

​
Local-Only Push

codaph push --local-only
Imports to .codaph/ mirror without uploading to Mubit.

​
Push All Providers

codaph push --providers all

​
Skip Worktrees

codaph push --no-worktrees

​
JSON Output

codaph push --json

{
  "repoId": "owner/my-project",
  "actorId": "alice",
  "summary": {
    "scannedFiles": 120,
    "matchedFiles": 45,
    "importedEvents": 1523,
    "importedSessions": 12
  },
  "providers": {
    "codex": {
      "scannedFiles": 80,
      "matchedFiles": 30,
      "importedEvents": 1200,
      "importedSessions": 8,
      "error": null
    },
    "claude-code": {
      "scannedFiles": 40,
      "matchedFiles": 15,
      "importedEvents": 323,
      "importedSessions": 4,
      "error": null
    }
  },
  "mubitRequested": true,
  "mubitEnabled": true
}

​
Output Details

​
Progress Display

⠋ Scanning agent history [##############] 45s | scan 120/120 | match 45 | events 1523 | line 8934 | session abc123de | ~/.codex/sessions/2024-01/session_abc123.jsonl
  • scan - Files scanned / total files
  • match - Files matched (valid agent session files)
  • events - Events imported so far
  • line - Current line in file
  • session - Current session ID being processed
  • File path - Current file being scanned

​
Summary

Push (local->cloud): local events imported=1523, files=45/120, sessions=12, Mubit=on | providers=Codex:e1523/f45, Claude Code:e323/f15
  • imported - Total events added to .codaph/ mirror
  • files - Matched files / scanned files
  • sessions - Unique sessions imported
  • Mubit - on (uploaded), off (local-only), or requested-unavailable (failed)
  • providers - Per-provider breakdown (events/files)

​
Agent Provider History

​
Codex (OpenAI)

History Location:
  • ~/.codex/sessions/ (SDK/CLI sessions)
  • {project}/.codex/sessions/ (project-scoped)
File Format: JSONL (one event per line) Auto-detection: Looks for .codex/ marker directory

​
Claude Code (Anthropic)

History Location:
  • ~/.claude/sessions/ (global)
  • {project}/.claude/sessions/ (project-scoped)
File Format: JSONL Auto-detection: Looks for .claude/ marker directory

​
Gemini CLI (Google)

History Location:
  • ~/.gemini/sessions/ (global)
  • {project}/.gemini/sessions/ (project-scoped)
File Format: JSONL Auto-detection: Looks for .gemini/ marker directory

​
Worktree Support

By default, push scans git worktrees for agent history: 
# Main repo
~/my-project/.codex/sessions/

# Worktree 1
~/worktrees/my-project-feature-a/.codex/sessions/

# Worktree 2
~/worktrees/my-project-bugfix/.codex/sessions/
Disable with --no-worktrees.

​
Incremental Push

Push is incremental by default:
  • Deduplicates events based on eventId
  • Only imports new events not already in .codaph/
  • Safe to run multiple times
Re-running codaph push after new agent sessions: 
codaph push
# Output: imported=23 (only new events since last push)

​
Workflow

​
Initial Backfill

# After codaph init
codaph push

​
Periodic Re-push

# After accumulating new agent sessions
codaph push
# Only imports new events (incremental)

​
Daily Workflow

# Don't use push for daily workflow
# Use pull instead:
codaph pull  # Fast cloud → local sync

​
Troubleshooting

​
No Agent History Found

Push (local->cloud): No agent history for this repo (matched 0 of 120 local agent history files).
Cause: No agent session files matched the current repo. Fix:
  • Verify agent provider is configured
  • Check agent history directories exist
  • Run agent at least once to generate sessions

​
Provider Import Failed

Codex history import failed: Error reading sessions directory
Fix:
  • Check file permissions on ~/.codex/sessions/
  • Verify agent history files are valid JSONL

​
Mubit Upload Failed

Mubit write failed: Authentication failed
Fix: 
codaph setup --mubit-api-key mb_live_...
# OR
export MUBIT_API_KEY=mb_live_...

Build docs developers (and LLMs) love

Get started for freeTalk to us