ccx

# ccx - Session Viewer for Agent CLIs Supports Claude Code (~/.claude), OpenAI Codex (~/.codex), and Grok Build (~/.grok) sessions. ``` ccx ├── projects # List all projects ├── sessions [project] # List sessions │ └── --provider cc|cx|gx # Filter by provider │ └── --search QUERY # Search summaries │ └── --after DATE # After date (YYYY-MM-DD) │ └── --sort time|messages|prompts # Sort order (prompts = human-turn count) │ └── --goal SLUG # Filter by launch-receipt goal (deva --goal) ├── view [session] # View session in terminal │ └── --brief # Conversation only │ └── --at MSG_ID [--context N] # Walk from a citation (search --hits / trace message_id) to its context ├── export [session] # Export session │ └── --format html|md|org|exec │ └── --shape full|brief|trace|exchange|human │ └── --brief # (deprecated: use --shape brief) ├── search [query] # Search across sessions │ └── --provider cc|cx|gx # Filter by provider │ └── --after / --before DATE # Date range │ └── --model MODEL # Filter by model ├── trace [session] # What the agent did: turn/step outline │ └── --json # Outline as JSON (ccx.outline.v1) │ └── --turn N # Full evidence for one turn (ccx.turn.v1) │ └── --full # Complete trace bundle (ccx.trace.v2, large; includes related) ├── related [session] # Which sessions connect to this one, and how │ └── --json # Every relation with evidence (ccx.related.v1) ├── log [project] # Slice raw session logs by time scope │ └── --scope today|yesterday|week|month|quarter|year │ └── --since / --until TIME # RFC3339 or YYYY-MM-DD │ └── --tz ZONE # IANA timezone, UTC, local, or offset like +8 │ └── --json --raw # Evidence bundle, optional raw JSONL │ └── --kind K1,K2 # Only these record kinds (user_prompt, assistant_message, tool_call, ...) │ └── --match PHRASE [-w] # Only records whose raw line contains the phrase ├── insight [project] # Digest of every session in a window (ccx.insight.v1) │ └── --scope --tz --since --until --all │ └── --json # sessions[] with prompts/final answer/edits/commits/cost + workspaces[]/days[]/models[] │ └── --records [-n N] # Add the raw log records (ccx log's payload) │ └── -o FILE # HTML evidence cockpit (default: $XDG_DATA_HOME/ccx/insights/, browsable at /insights) ├── web # Start web UI │ └── --port --host --no-open │ └── --project [path] --session ID --latest # Deep-link into a view ├── fork <session-id> # Fork session to current project │ └── --to /path # Fork to specific directory ├── run <skill> [task] # Run a bundled skill via an agent CLI │ └── --agent claude|codex|grok # Which installed CLI executes it │ └── --dry-run # Show command + payload + permissions, no exec ├── skills # Manage bundled agent skills │ └── install --scope user|project # Install skills matching this binary ├── config # Show / init config └── doctor # Check setup ``` ## Quick Start ```bash ccx projects # List all projects ccx sessions # List recent sessions ccx sessions -p cx # Codex sessions only ccx sessions -p gx # Grok sessions only ccx view abc123 # View by session ID (prefix match) ccx export -f html # Export to HTML ccx sessions --scope yesterday --tz +8 --all --json # Session containers by end time ccx log --scope yesterday --tz +8 --all --json ccx log --scope today --all --kind user_prompt # The humans in the loop: every prompt today, all sessions, in order ccx log --scope today --all --kind interrupt,tool_denied # Where humans stopped or refused the agent ccx log --scope month --all --match deadman -w # When a term came up inside a window (raw-line match) ccx insight --scope week --all --json # What was worked on, everywhere: per-session prompts, answers, edits, cost ccx insight --scope month --all # Same digest as an HTML cockpit in the insights dir ccx trace # Outline of the latest workspace session ccx trace abc123 --turn 5 # Full evidence for one turn ccx related abc123 # Sessions connected to this one: fork, handoff, mentions, shared files ccx web # Start web UI at localhost:8080 ``` ## Trace: what the agent did `ccx trace` prints a terminal-readable outline: every turn (user intent) broken into steps (the agent's own narration), with tool, edit, error, interrupt/denial (human interventions), active-time, and cost rollups. Read the outline whole, then drill: `--turn N` for one turn's full evidence, `--full` for the complete bundle. JSON kinds and field semantics are documented in `docs/schema.md`; header times are local (stated as `times UTC+X`), JSON times are UTC. Session IDs resolve across all projects automatically; `ccx trace <id>` works from any directory. ## Related: connections between sessions `ccx related [session]` joins the islands: which other sessions of the workspace connect to this one and how — `forked_from`/`fork_of` (shared message ids), `mentions`/`mentioned_by` (a session id named in text), `handoff_from`/`handoff_to` (a baton file such as HANDOFF.md, handoffs/, devlog written by one and read by the other later), `builds_on`/`built_on_by` (a file edited by one, then touched by the other), `overlaps` (concurrent), `previous`/`next`. Strength is a band (strong/medium/weak). `--json` carries the evidence per relation (session, message id, time, path, quote) — cite from that when a claim spans sessions. Also present as `related` in `ccx trace --full`. ## Insight: what was worked on, across every workspace `ccx insight --scope <today|yesterday|week|month> --all --json` is the evidence for "what did we do this week" — all workspaces, all providers, one bounded document (`ccx.insight.v1`). Read it whole: - `metrics`: sessions, workspaces, prompts, edits, commits, interventions, tokens, cost, and `cost_coverage` (share of tokens a pricing row covers — quote the cost with its coverage, never alone). - `workspaces[]`: where the work went, sorted by activity, each with `session_ids[]`. - `sessions[]`: per session, the human's `prompts[]` (intent, cited by line), the agent's `final_answer` (its claim, not proof), `edits` + `edited_paths[]`, `commits`, `interrupts`/`denials`, `cost_usd` with `cost_status`, `relation` (started before / ended after the window). Drill with `ccx trace <id>` only where it matters. - `models[]`, `days[]`, `providers[]`: tempo and spend by axis. Never rebuild these from `ccx log` records; `log` is for "when did X come up" (`--match`) and "every human prompt today" (`--kind`), not for reconstructing sessions. Without `--json` the same digest is rendered as a self-contained HTML cockpit (facts only; the judgment layer is the ccx-recap skill). ## Multi-Provider ```bash ccx sessions --provider=cc # Claude Code only ccx sessions --provider=cx # Codex only ccx sessions --provider=gx # Grok only ccx search --provider=cx "query" # Search codex sessions ``` Override provider homes: ```bash ccx --claude-home /path view ccx --codex-home /path view ccx --grok-home /path view ``` Grok sessions never display cost: token counts are parsed but pricing is unverified — trust the counts, not a guessed dollar figure. ## Export ```bash ccx export -f html # Rich HTML ccx export -f md # Markdown ccx export -f org # Org-mode ccx export -f exec # Executive summary ccx export --shape brief # Conversation only (no tool details) ccx export --shape human # Only the human's turns, verbatim, # numbered, citable by #<uuid8> ``` `--shape` picks the content (full, brief, trace, exchange, human); `--format` picks the encoding. `--shape human` is markdown-only and defaults `--format md`; use it when distilling what the human actually said (replay duplicates from compaction are deduplicated). For machine-readable JSON evidence use `ccx trace --json`, not export. ## Web UI ```bash ccx web # localhost:8080 ccx web -p 3000 # Custom port ccx web --no-open # Don't open browser ``` Features: - Project/session browser with multi-provider merge - Provider filter dropdown (All / Claude Code / Codex / Grok) - Memory file inspector (per-project, expandable with fmt/raw/copy) - Collapsible thinking/tool blocks - In-session search with filter chips - Brief export (conversation-only) - Dark/light theme toggle - Keyboard navigation (j/k, /, gg/G, d for theme) - Global search (sessions + memory files) - Session stats (tokens, messages, tools) - Settings page (provider status, config inspection) ## Search ```bash ccx search "error handling" # All providers ccx search --provider=cc "auth bug" # Claude Code only ccx search --after=2026-03-01 "deploy" # Date filtered ccx search --content "deploy" # Also scan conversation text (user + assistant) ccx search --content -w --sort first X # Whole word only, earliest mention first (FIRST column) ccx search --content -w --hits X # Every mention as a citation: time, session, role, message id, quote ccx search --raw "deploy" # Grep parity over raw transcript lines ``` `-w` matters when the term prefixes a common word ("semantica" vs "semantically"); `--json` carries `matches`, `previews`, `first_hit`. `--content` also scans prompt history (`~/.claude/history.jsonl`, `~/.codex/history.jsonl`): type `prompt` rows are prompts whose session file is gone — the only evidence past session cleanup, so "when did we first say X" reaches back further than the sessions do. Cite from `--hits --json` (`message_id`, `time`, `quote`) rather than from a session-level count when a claim needs evidence; walk to the context with `ccx view <session> --at <message_id>` (web: `/session/<project>/<id>#msg-<message_id>`). Web search supports provider prefixes: `cc: auth bug`, `cx: codex query`, `gx: grok query` ## Fork Session Resume any session from any project directory: ```bash ccx fork abc12345 # Fork to current directory ccx fork abc12345 --to /new/path # Fork to specific directory # Then: claude --resume <new-uuid> ``` Rewrites sessionId and CWD, drops file-history snapshots, clears worktree state. Original session is never modified. ## Memory Inspection Web UI shows memory files on the project page: - Global instructions (CLAUDE.md, AGENTS.md, instructions.md) - Per-project memory (MEMORY.md + topic files) - Expandable with formatted/raw view + copy Cross-project memory overview at `/memory` page. ## Configuration ```yaml # ~/.config/ccx/config.yaml theme: dark show_thinking: collapsed default_format: html port: 8080 providers: claude-code: enabled: true accent_color: "#da7756" codex: enabled: true accent_color: "#3b82f6" grok: enabled: true accent_color: "#8b5cf6" ``` Data locations: - Claude Code: `~/.claude/projects/` (read-only) - Codex: `~/.codex/sessions/` (read-only) - Grok: `~/.grok/sessions/` (read-only) - Config: `~/.config/ccx/config.yaml` - Data: `~/.local/share/ccx/` (stars) ## Install ```bash curl -fsSL https://raw.githubusercontent.com/thevibeworks/ccx/main/install.sh | bash ``` Or via Go: ```bash go install github.com/thevibeworks/ccx/cmd/ccx@latest ``` Then install the agent skills that match the binary (this file and ccx-recap/ccx-retro are embedded in the binary, so installed skills never describe flags the binary doesn't have): ```bash ccx skills install # -> ~/.claude/skills/ ccx skills install --scope project # -> ./.claude/skills/ ``` ## Runner bridge ```bash ccx run ccx-recap --agent claude # recap this workspace via claude ccx run ccx-retro --agent codex "last session" ccx run ccx-recap --agent grok --dry-run # inspect before running ``` `ccx run` launches the INSTALLED agent CLI headlessly with a bundled skill as the prompt. The agent CLI owns permissions and sandboxing — ccx passes no permission flags. The run's session is written by the provider and readable with `ccx trace`; a receipt linking run to session lands in `~/.local/share/ccx/runs/`. ccx treats all agent session data as read-only. It never modifies session files.