# Historical extraction

> Read existing Claude Code or Codex transcripts without a live hook, then optionally import the normalized records.

Source: https://docs.agentbeam.com/agent-cli/extraction

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

```sh
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

```sh
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.