TUI “box” for managing coding-agent sessions (Codex, Claude, Gemini, OpenCode): browse local session logs now, and later reconstruct exactly what the agent did (files, tools, tokens).

• Features
• Key features (what it’s for)
  • Skill spans (and loop detection)
  • Timeline analysis (TUI + CLI)
  • Fork/resume sessions (Codex)
  • ccbox-insights skill (code-insights)
• Install
• Screenshots
  • Projects
  • Menu bar
  • Session Detail (timeline)
  • Session actions (fork/resume)
  • Session stats
  • Tasks
  • Processes
• Roadmap
• Run
• Skill (skills.sh)
• Keybindings (prototype)
• License

• Full-screen Projects → Sessions → Session Detail timeline
• Multi-engine support (Codex, Claude, Gemini, OpenCode) with TUI + CLI filters
• Type-to-filter + highlight, multi-select, and batch delete (with confirmation)
• “Online” dot (●) for recently modified projects/sessions
• Skill span tracing (colored gutter + loop detection) and a Skills overlay (S)
• Fork/resume Codex from a selected timeline item (f)
• Statistics windows for projects/sessions (F3)
• Tasks screen + editor (including clipboard image paste)
• New Session prompt editor (n) that spawns agents in Pipes or TTY mode
• Processes screen (P) for stdout/stderr/log viewing + killing spawned agents; attach/detach TTY (a, Ctrl-])
• Auto-rescans when session sources change (file watcher for Codex/Claude/Gemini/OpenCode)
• Update notifications and self-update (ccbox update)

When an agent session activates a skill (for example a commit helper, design-doc generator, or an install workflow), ccbox detects the skill boundaries and overlays that context on the timeline:

• Visual overlay (TUI): colored gutter markers show which timeline items happened “inside” which skill span; nested skills get their own span depth.
• Loop detection: repeated consecutive invocations of the same top-level skill are flagged so you can spot “skill recursion” quickly.
• CLI export: ccbox skills prints a per-skill summary (or --json) so other automation can reason over skill usage.

Use cases:

• “Why did this session burn tokens?”: see which skill dominated time/tool calls.
• “Which skill caused the failures?”: attribute tool failures to the active skill context.
• “Is a skill looping?”: catch repeated skill invocations early and adjust instructions/skills.

How to use:

• TUI: open a session → press S for the Skills overlay.
• CLI: ccbox skills [log|project] [session-id] --json (use --id if you prefer flags).

The Session Detail timeline is the evidence trail of what happened: user requests, assistant output, tool calls, tool outputs, and token/stat markers (when available).

Use cases:

• Root-cause a failed run by replaying tool calls and their outputs.
• Write a precise “what happened” report for teammates or incident notes.
• Confirm what was actually executed (commands, files touched) without guessing.

How to use:

• TUI: open a session → Tab changes focus between timeline/details → Enter jumps Tool → ToolOut.
• CLI: ccbox history [log|project] [session-id] --full for a complete, copy/paste-friendly timeline.

For Codex sessions, ccbox can fork/resume from a selected point in the timeline to create a new run with the same context up to that moment.

Use cases:

• “Try a different fix” from the same starting point without re-reading the whole session.
• Continue after a bad turn or failed tool call with a clean branch.
• Break a long session into smaller, more focused follow-up runs.

How to use:

• TUI: open a Codex session → select a Turn/User/Out/ToolOut item → press f (or use the Session menu).

ccbox-insights is an installable agent skill that reads session history via ccbox (including optional skill-span context) and produces:

• A “lessons learned” memo backed by evidence
• A list of recurring failure patterns (invalid tool use vs runtime failures)
• Copy-ready, additive instruction snippets for project AGENTS.md (and optional global rules)

Use cases:

• After a week of work, turn noisy session logs into better standing instructions.
• Reduce repeated tool-call errors and avoid “clarify/correct” churn.
• Save time and tokens by standardizing the workflows that actually worked.

How to use:

• Install: npx skills add diskd-ai/ccbox --skill ccbox-insights --global --yes
• Prompt: “Use the ccbox-insights skill to analyze the latest N sessions for this project and propose AGENTS.md additions.”

Quick install from GitHub Releases (macOS/Linux):

curl -fsSL -H 'Cache-Control: no-cache' -o - https://raw.githubusercontent.com/diskd-ai/ccbox/main/scripts/install.sh | /bin/bash

Homebrew (recommended):

brew tap diskd-ai/ccbox
brew install ccbox

Developer build (from source): see AGENTS.md.

What’s happening / features:

• Browse projects discovered from your local Codex/Claude/Gemini session logs and OpenCode sessions.
• Type to filter (matching text is highlighted); Esc clears.
• Shift+Arrows multi-select; Del deletes selected (with confirmation).
• Project table includes path, session count, and last modified time; ● indicates a recently modified (“online”) project.

What’s happening / features:

• F2 opens the menu; arrows/Enter (and mouse) navigate.
• The Engine menu (Projects/Sessions) filters by agent engine: All/Codex/Claude/Gemini/OpenCode.
• The Window menu provides shortcuts to every screen.

What’s happening / features:

• Timeline shows session events in order; details are always expanded.
• Tab switches focus (focused pane uses a double border); scrollbars indicate overflow.
• Enter jumps Tool → ToolOut; o previews the last Out; F3 opens statistics.

What’s happening / features:

• Fork/resume Codex from a selected Turn/User/Out/ToolOut record.
• Toggle Visible Context for the current turn.

What’s happening / features:

• Time spent, token usage, tool-call breakdown (success/error/unknown), and apply_patch changes.

What’s happening / features:

• Type to filter; n creates; Ctrl+Enter spawns; Shift+Tab switches engine.

What’s happening / features:

• View output (s/e/l), kill (k), attach (a), and open the related session.

See ROADMAP.md.

ccbox

CLI mode (no TUI):

ccbox projects
ccbox sessions                     # defaults to current folder (or a parent folder) project
ccbox sessions "/path/to/project"
ccbox history                      # defaults to latest session in current folder project
ccbox history "/path/to/session.jsonl"
ccbox history "/path/to/session.jsonl" --full
ccbox skills                       # defaults to latest session in current folder project
ccbox skills "/path/to/project"    # latest session in that project
ccbox skills "/path/to/project" "SESSION_ID"
ccbox skills --id "SESSION_ID" --json
ccbox sessions --limit 50 --offset 0 --size
ccbox history --limit 200 --offset 0 --full --size
ccbox update

CLI details:

• Auto-selects the project for the current folder (or nearest parent) when project-path is omitted.
• Pagination: sessions and history default to --limit 10; use --limit N and --offset N.
• projects output: project_name<TAB>project_path<TAB>session_count
• sessions output: started_at_rfc3339<TAB>session_id<TAB>title<TAB>log_path (newest-first; --size adds file_size_bytes before log_path)
• history accepts a session .jsonl path or a project directory; if a directory is provided it selects that project’s latest session.
• history prints a readable timeline; --full includes long details (tool calls/outputs, full messages); --size prints stats to stderr.
• skills accepts a session .jsonl path or a project directory, plus an optional session-id (positional or --id); --json prints structured spans/loops.
• Pipe-friendly output (handles broken pipes like ccbox history | head).
• Parse warnings and “truncated” notices are printed to stderr.
• On TUI start, ccbox checks for a newer GitHub Release in the background and shows a hint if one is available.

Optional overrides:

• CODEX_SESSIONS_DIR (defaults to ~/.codex/sessions; Windows: %USERPROFILE%\\.codex\\sessions)
• CLAUDE_PROJECTS_DIR (defaults to ~/.claude/projects)
• CCBOX_GEMINI_DIR (defaults to ~/.gemini; sessions are discovered from tmp/<project-hash>/chats/session-*.json)
• CCBOX_OPENCODE_DB_PATH (defaults to XDG_DATA_HOME/opencode/opencode.db, else ~/.local/share/opencode/opencode.db)

Notes:

• Spawning sessions requires codex on your $PATH (and claude if you switch engines).

This repo ships agent skills:

• ccbox: inspect local session logs using the ccbox CLI (projects, sessions, history)
• ccbox-insights: analyze tool-call failures in session logs and propose additive instructions (project AGENTS.md + global)

Install the code-insights skill (ccbox-insights):

npx skills add diskd-ai/ccbox --skill ccbox-insights --global --yes

Analyzes unsuccessful tool calls and suggests additive fixes in AGENTS.md (project-level).

Helps save time and tokens.

Install one or both:

npx skills add diskd-ai/ccbox --skill ccbox --global --yes
npx skills add diskd-ai/ccbox --skill ccbox-insights --global --yes

No additional setup is required after npx skills add ... --global.

Requirements: ccbox on your $PATH and access to your sessions directory (CODEX_SESSIONS_DIR if needed).

Example prompts:

• Codex: codex "Use the ccbox skill to summarize the latest session for this repo."
• Claude: claude "Use the ccbox skill to summarize the latest session for this repo."
• Gemini: gemini "Use the ccbox skill to summarize the latest session for this repo."
• Insights (project): Use the ccbox-insights skill to analyze tool-call failures in the latest 20 sessions for "/path/to/project".
• Insights (global for codex): Use the ccbox-insights skill to analyze **codex** tool-call failures across my top 5 projects (by session count) and propose global instruction updates.

• Global: Ctrl+R rescan · F2 system menu · P processes · F1/? help · Ctrl+Q/Ctrl+C quit
• Mouse: wheel scrolls lists/outputs/details · left click selects/focuses
• Lists: arrow keys move selection · PgUp/PgDn page
• Projects: type to filter · Esc clears filter · Enter opens · Space result (newest session) · Del delete (confirm)
• Sessions: Enter opens · Space result (last Out) · n new session · Del/Backspace delete (confirm) · Esc back
• New Session: edit/paste · Ctrl+Enter/Cmd+Enter send · Shift+Tab switch engine · F4 switch Pipes/TTY · Esc cancel
• Session Detail: Enter ToolOut (Tool call) · f fork/resume (Codex) · o result (last Out) · c visible context window · Esc/Backspace back
• Processes: a attach (TTY) · Ctrl-] detach · s stdout · e stderr · l log · k kill · Enter opens session (Codex only)

MIT. See LICENSE.