Historical extraction
Read existing Claude Code or Codex transcripts without a live hook, then optionally import the normalized records.
On this page
Extraction lets you inspect supported agent history from before Beam was installed. It reads local transcript files rather than retroactively recreating hooks. Supported agents are claude-code and codex; other IDs fail explicitly.
Preview locally
beam agent extract claude-code --limit 20
beam agent extract codex --limit 20
Preview mode normalizes and redacts records on the machine and does not contact the collector. The default preview limit is 200 events. The command prints event JSON followed by a human-readable summary, so the entire stdout stream should not be treated as one JSON document.
Read a small preview first to confirm the expected source and content before importing into an enrolled collector.
Understand the sources
| Agent | Files read | Entries extracted |
|---|---|---|
| Claude Code | ~/.claude/projects/**/*.jsonl | Assistant tool_use blocks |
| Codex | ~/.codex/sessions/**/*.jsonl and archived_sessions | function_call and custom_tool_call response items |
Extracted events carry source: "extract" and phase: "observed", keeping them distinct from proposed live hook activity. A transcript entry can show an attempted action without proving its external effect.
Save to the collector
beam agent extract claude-code --save
beam agent extract codex --save
The collector must be running. Import uses the normal ingestion pipeline in batches of up to 2,000 records and deduplicates by event ID. Review accepted, duplicate, and skipped counts. An enrolled collector may forward imported records to the workspace, so --save is not the same privacy boundary as offline preview.
Work within the bounds
Each transcript file is limited to 50 MB and 20,000 parsed lines; each run walks at most 2,000 files. Unsupported entries and records that cannot normalize may be skipped. The preview limit caps displayed events; it is not an instruction to read every possible historical file without bounds.
Keep the original transcript and its provenance under your retention policy when investigating an incident. Beam extraction is a normalized view and should not be the only retained evidence of the original run.