codex-threads

codex-threads builds a local searchable index of Codex session archives under ~/.codex and Claude Code project transcripts under ~/.claude, then exposes thread, message, event, and raw-session commands that future agent threads can run from any repo.

Install

make install-local

That installs codex-threads into ~/.local/bin.

First run

codex-threads --json doctor
codex-threads --json sync
codex-threads --json --source claude sync

Command surface

codex-threads --json doctor
codex-threads --json sync
codex-threads --json sync --rebuild
codex-threads --json --source codex sync
codex-threads --json --source claude sync
codex-threads --json threads list --limit 20
codex-threads --json --source claude threads list --limit 20
codex-threads --json threads resolve "tweet idea"
codex-threads --json threads read <thread-id>
codex-threads --json messages search "build a CLI" --limit 20
codex-threads --json messages context <message-id> --before 3 --after 3
codex-threads --json events read <thread-id> --limit 50
codex-threads --json raw session <thread-id>

JSON policy

Under --json, the CLI writes JSON to stdout only.

• Success output is command-specific and stable for each command family.
• Error output uses:

{
  "ok": false,
  "error": {
    "code": "index_missing",
    "message": "index not found at /Users/you/.codex-threads/index.sqlite; run `codex-threads sync` first"
  }
}

Examples:

{
  "ok": true,
  "rebuild": false,
  "scanned_files": 42,
  "indexed_threads": 42,
  "indexed_messages": 318,
  "updated_threads": 42,
  "skipped_threads": 0,
  "removed_threads": 0,
  "last_sync": "1712799668",
  "index_path": "/Users/you/.codex-threads/index.sqlite"
}

{
  "query": "build a CLI",
  "count": 2,
  "hits": [
    {
      "message": {
        "message_id": "thread-id:m4",
        "thread_id": "thread-id",
        "ordinal": 4,
        "role": "user",
        "timestamp": "2026-04-11T00:00:00Z",
        "text": "Build a CLI...",
        "preview": "Build a CLI..."
      },
      "thread_title": "Create CLI",
      "thread_updated_at": "2026-04-11T00:00:00Z"
    }
  ]
}

Notes

• This CLI is offline-only. It reads local session archives and does not require auth.
• By default, commands use --source all, which includes both Codex and Claude Code when those homes exist. Use --source codex or --source claude to narrow sync, list, resolve, read, search, context, events, and raw-session commands.
• The default homes are ~/.codex and ~/.claude. Override them with --codex-home <PATH> and --claude-home <PATH>.
• Claude Code thread IDs are indexed as claude:<session-id> to avoid collisions with Codex IDs. Commands that read or resolve threads also accept the bare Claude session UUID when --source claude or --source all is active.
• threads read returns a cleaned message view based on user and assistant messages.
• Claude Code cleaned reads skip tool calls, tool results, thinking blocks, slash-command scaffolding, local shell wrapper messages, hook/system records, and message-less probe sessions.
• events read and raw session expose the original JSONL records for deeper inspection.