🛩️ agent-session-recorder

The code is the result. The session is the artifact.

A local-first flight recorder for AI coding agents. Every prompt, tool call, and decision, on one redacted timeline.

• What: it records Claude Code, Codex CLI, and any MCP host into one normalized JSONL timeline. You can export it as Markdown or HTML, or watch it live.

• Why: a diff shows you what changed. The session shows you how the agent got there: the prompts, the tool calls, the dead ends. That part is usually lost.

• How: everything stays on your machine. Secrets are redacted before anything touches disk. Reasoning is stored only when the provider exposes it, and it's labelled honestly.

Status: v0.2. The adapters are built against documented formats and tested on synthetic fixtures. Real-world transcripts are wanted (#10).

⚡ 30-second quickstart

npm install --global agent-session-recorder
agent-session-recorder init           # dry-run: detects claude/codex, prints the config it would add
agent-session-recorder init --write   # Claude hooks (+ .bak) and Codex MCP config
agent-session-recorder view           # live timeline at http://127.0.0.1:4318

No agent handy? Open examples/claude-fixture-1.html to see a recorded session.

More commands: import-claude <file>, codex import|tail [--latest], mcp, export <id> --format md,html,jsonl, list, redact. Flags: --research (shrinks large or repeated tool output), --no-redact (you probably don't want this one).

Related MCP server: sagaz-mcp

🎥 What gets captured

The MCP server (start_session, log_event, end_session, export) only knows what the host tells it. SKILL.md asks agents to report their plan, decisions, and outcome. Schema details are in docs/event-schema.md.

🔒 Privacy

• Local only. Data is written to ~/.agent-session-recorder/ with 0600 file permissions. No network calls, no telemetry, no cloud.

• Redaction always runs before a write. Keys, tokens, emails, phone numbers, IPs, Luhn-valid cards, and home-dir usernames become placeholders like [API_KEY_1]. Only a salted hash → placeholder map is kept.

• It's regex, so it's best-effort. Review exports before you share them. Found a leak? That's a security issue. More in docs/redaction.md.

🔏 Sealed sessions

Events are hash-chained as they are written. seal <id> --timestamp adds a Merkle batch with an RFC 3161 timestamp, and verify <id> reports OK or the exact tampered lines. See docs/sealed-sessions.md.

To ship a proof-carrying PR, run bundle <sessionId> --intent <YYYYMMDD-slug> [--timestamp | --tsa url]. It records a sealed proof.link event tying that intent to the current git HEAD, refuses to write a bundle if verify fails, and writes .proof/<intent>.json by default. Reviewers can then run the independent proof-check flow against that JSON bundle instead of trusting the local CLI output alone.

🧭 Architecture

flowchart LR
  A[Claude Code hooks/transcripts] --> R
  B[Codex rollout files] --> R
  C[MCP host] --> R
  R[Recorder<br/>redact → research-shrink] --> S[(JSONL per session)]
  S --> E[Export: md / html / jsonl]
  S --> V[Live viewer :4318]

More detail in docs/architecture.md and docs/adapters.md.

🛠️ Contribute in 10 minutes

1. Pick a good first issue. Each one points to the files you'll need.

2. npm ci && npm run build && npm test: green in well under a minute.

3. Read CONTRIBUTING.md (it's short). Using an AI agent? Point it at AGENTS.md.

Have questions or ideas? Head to Discussions.

🗺️ Roadmap

API proxy #1 · Grok CLI adapter #2 · xAI reasoning #3 · NER redaction #4 · Session diff #5 · Cost charts #6 · Dataset export #7 · OTel #8 · Cloud sync #9 · Real-session validation #10

📚 The series behind it

1. Part 1 · 2. Part 2 · 3. Part 3

License

MIT. Record freely.