@archships/wit-cli

wit-cli — Black box flight recorder for AI-assisted development

Track every coding session across Claude Code, Gemini CLI, Cursor, OpenCode, and Codex. Store structured artifacts locally, then replay, checkpoint, or review the work later.

Why wit-cli

We did not build wit-cli because developers needed another CLI.

We built it because AI changed the shape of software work faster than teams changed the way they remember that work.

A coding session used to be easier to reconstruct. You had commits, maybe a ticket, maybe a few notes. Now a meaningful part of the work happens between the human and the machine: prompts, retries, tool calls, hook events, checkpoints, partial decisions, interrupted runs. That is where much of the real story lives.

Most teams lose it.

They keep the output, but not the session. They keep the diff, but not the path. They keep the final result, but not the operational memory needed to trust it, review it, or resume it later.

wit-cli is our response to that shift. It treats human-AI coding as a first-class session: something that should be tracked, revisited, and understood over time. The faster teams move with AI, the easier it becomes to lose context. wit-cli gives that context a durable place to live.

Supported Agents

Agent	Hook Mechanism	What's Captured
Claude Code	.claude/settings.json	Prompt, response, tools, tokens
Gemini CLI	.gemini/settings.json	Prompt, response, tools, tokens
Cursor	.cursor/hooks.json	Prompt, response, tools
OpenCode	.opencode/plugins/wit.ts	Prompt, response, tools, tokens
Codex	~/.codex/config.toml	Prompt, response, tools, session metadata
DimCode	.dimcode/hooks.json	Prompt, response, tools, tokens

Install

npm install -g @archships/wit-cli

npx @archships/wit-cli <command>

Requires Node >= 18.

Setup

cd your-project
wit enable                        # Interactive multi-select agent picker
wit enable --all                  # Enable for all agents
wit enable codex                  # Enable for specific agent

wit enable without arguments opens an interactive picker — toggle agents on/off, previously enabled agents are pre-selected. Use your AI agent as usual after setup, sessions are captured automatically.

Disable:

wit disable                       # Remove project hooks
wit disable --global              # Also remove global config
wit disable --clean               # Remove all data

Commands

Session Tracking

wit status                        # Current session info
wit list                          # List all sessions
wit view <id>                     # Session details
wit view <id> --json              # JSON output
wit search --recent=5              # Recent sessions
wit search --file=src/auth.ts      # Sessions that touched a file

Replay & Dashboard

wit replay                        # Open session replay in browser
wit dashboard                     # Open analytics dashboard
wit share                         # Enable/disable replay sharing

Checkpoints

Git-backed per-turn snapshots. Every turn creates a shadow branch with a full working tree snapshot — restorable anytime.

wit rewind <checkpoint>           # Rollback to checkpoint
wit rewind <checkpoint> --branch fix  # Branch from checkpoint
wit drop --force                 # Delete checkpoint for current HEAD

Maintenance

wit doctor                        # Diagnose issues
wit doctor --fix                  # Auto-fix stuck sessions
wit clean --days=7 --dry-run      # Preview cleanup
wit clean --days=7                # Clean old sessions
wit cost status                # Show pricing config
wit cost sync                  # Sync LiteLLM pricing cache

Session Sync

Multi-machine session sync via a git orphan branch (wit-sync). No extra infrastructure — data travels with your git push.

wit sync status                   # Sync state
wit sync push                     # Force push (normally automatic)
wit sync pull                     # Force pull (normally automatic)
wit sync off                      # Disable sync

wit enable configures sync automatically:

• Creates wit-sync orphan branch
• Generates machine ID
• Installs pre-push and post-merge git hooks

After setup, sync is fully automatic — git push pushes sessions, git pull pulls them.

How It Works

Hook event (JSON from any agent)
  │
  ├─► events.jsonl           Append-only event log
  ├─► state.json             Session state (turns, tools, tokens, files)
  ├─► Shadow branch          Full working tree snapshot per turn
  └─► Blackbox branch        Persistent metadata on orphan branch

Every event is enriched with _ts (timestamp), _hook (lifecycle type), and _turn (boundary marker) — enabling faithful session replay with real-time pacing.

Storage Layout

.wit/
  index.json
  config.json
  <session-id>/
    events.jsonl
    state.json

.git/wit-sessions/          # V2 state (source of truth)
  <session-id>.json

wit/<commit>                # Shadow branch: working tree snapshot
wit/blackbox/v1             # Blackbox branch: checkpoint metadata
wit-sync                    # Orphan branch: multi-machine sync