agentfdr

KO | EN

gitlite — search

#windows #nextjs #mysql #php #generative-ai #web #go #open-source #security #claude

(★ 9)

Flight data recorder for local coding agents — dissect why Claude Code looped, drifted, or burned tokens. Zero instrumentation, local-first.

파일 탐색기

ZIP 다운로드

- - test.yml
- logo.png
- screenshot-board-dark.png
- screenshot-board-light.png
- screenshot-dark.png
- screenshot-light.png
- screenshot-usage-dark.png
- screenshot-usage-light.png
- agentfdr.js
- - logo.png
  - screenshot-board-dark.png
  - screenshot-board-light.png
  - screenshot-dark.png
  - screenshot-light.png
  - screenshot-usage-dark.png
  - screenshot-usage-light.png
  - social-preview.png
- index.html
- demo-board-fixture.mjs
- assert.js
- board.html
- board.js
- cli.js
- codex.js
- config.js
- cost.js
- detect.js
- diff.js
- discover.js
- i18n.js
- parser.js
- report.js
- search.js
- server.js
- subagents.js
- tap.js
- ui.html
- usage.js
- assert.test.js
- board.test.js
- cli.test.js
- codex.test.js
- config.test.js
- cost.test.js
- detect.test.js
- diff.test.js
- parser.test.js
- search.test.js
- subagents.test.js
- usage.test.js
.gitignore
CONTRIBUTING.md
LICENSE
package.json
README.ja.md
README.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1>agentfdr</h1>

<p><strong>Flight data recorder for local coding agents.</strong><br>
  When Claude Code or Codex CLI loops, drifts off-goal, or quietly burns two million tokens,<br><code>agentfdr</code> shows you <em>why</em> — turn by turn, after the fact.</p>

<p><a href="https://kamihork.github.io/agentfdr/">Website</a> | English | <a href="README.ja.md">日本語</a></p>
</div>

## Quick start

```sh
npx agentfdr
```

That's the whole setup. Your sessions are already recorded — Claude Code writes a full transcript of every session to `~/.claude/projects/`, and OpenAI's Codex CLI records rollouts to `~/.codex/sessions/`. `agentfdr` auto-discovers both and turns them into something a human can investigate.

**Zero instrumentation. Zero cloud. Zero config.** Nothing is sent anywhere; the viewer binds to `127.0.0.1` and reads files you already have.

> If agentfdr showed you something you didn't know about your sessions, a ⭐ on this repo helps other agent users find it.

## Features

- 🛫 **Timeline viewer** — one screen for the whole session: every turn's tool calls, context-window composition, and output tokens, with prompt and compaction markers
- 🤝 **Two agents, one cockpit** — Claude Code and OpenAI Codex CLI sessions, auto-discovered and investigated with the same timeline, detectors, search, and diff
- 🔎 **Full-text search** — `agentfdr search` (and the **Search** tab) finds any prompt, assistant reply, tool call or result across every session, and jumps to the exact turn
- 🔍 **Turn dissection** — resizable side panel with usage breakdown, assistant text, and every tool call's duration, result size, and snippet; step with ←/→
- 🚨 **Anomaly detection** — tool loops, error streaks, context bloat, token spikes, cache thrash, file churn, intent drift, and refusals, flagged automatically
- ⧉ **Subagent tree** — work delegated to subagents lands in transcripts of its own and never shows up in the session totals; the **Subagents** tab reattaches every agent to the turn that spawned it (nested agents included) with its turns, tool calls, billed tokens, and anomalies
- 📡 **Live watch mode** — `agentfdr watch` follows a session that's still running
- 🗂 **Live session board** — `agentfdr board` puts every running Claude Code session on one kanban: **needs you** (permission prompt / question) · **working** · **idle**, with the current task, what the agent is doing right now, cost so far, and a warning when two sessions are editing the same repository or file. CLI and Desktop-app sessions side by side; type instructions, approve, deny or interrupt a tmux-hosted session from the page
- 📊 **Plan usage** — 5-hour window / daily / weekly burn across all projects, a 12-month activity heatmap, plan-tier auto-detection, and calibratable budgets with warning bars
- 💸 **Cost estimation** — estimated USD per session and per model, from list prices
- 🚦 **CI gate** — `agentfdr assert --no-loops --max-tokens 2M` exits 1 on violation
- 📋 **Markdown autopsy** — `agentfdr blame` renders the analysis ready to paste into an issue
- 📤 **Shareable session card** — one click exports a PNG summary (cost, tokens, cache hit rate, anomalies, the context curve) sized for X/socials
- ⚖️ **Session diff** — `agentfdr diff` (and the **Compare** tab) puts a failed attempt next to the successful retry: stats, anomalies, tool mix, and which files each one touched
- 🌗 **Dark/light**, 🌏 **English/Japanese**, in both the viewer and the CLI
- 🔒 **Local-only** — no telemetry, no account, no runtime dependencies (Node ≥18 stdlib)

## Why

Autonomous agent failures are hard to debug because the evidence is gone by the time you notice:

- *The loop* — edit → test fails → same edit, for 40 minutes
- *The drift* — you asked for a bugfix, it refactored the router
- *The burn* — a huge tool result crowds the context, cache stops hitting, every turn re-reads 200k tokens
- *The bad landing* — "Done!" with failing tests, or no stop at all

Existing LLM observability tools (LangSmith, Langfuse, AgentOps) assume **you instrument your own app with their SDK and send traces to their cloud**. A prebuilt local agent like Claude Code offers no instrumentation point — but it doesn't need one. The data is already on disk. What's missing is the crash investigator's toolkit. This is that toolkit.

Zooming out: working with coding agents is becoming **loop engineering**. You no longer just prompt a model — you design and operate an agent loop, and the **harness** (Claude Code and friends) decides what enters the context, which tools fire, and when to stop. Improving that loop takes feedback, and you can't engineer a loop you can't see. agentfdr is the instrument panel: it turns every looping, drifting, token-burning run into a lesson instead of a mystery.

## Commands

```
agentfdr                    # open the newest session's timeline in your browser
agentfdr list               # all recorded sessions across all projects
agentfdr open 35cb18        # open a session by id prefix (or path to a .jsonl)
agentfdr watch              # same, but live: the timeline follows the running session
agentfdr board              # live kanban of every running session; steer tmux sessions, start new ones
agentfdr statusline-tap     # status-line pass-through recording 5h/7d plan usage per account (board)
agentfdr blame 35cb18       # markdown autopsy — paste it into an issue
agentfdr diff 35cb18 9af7ec # compare two sessions: failed attempt vs retry
agentfdr search "login bug" # full-text search across every session
agentfdr stats              # token totals + estimated cost per project
agentfdr usage              # plan usage: 5h window / daily / weekly burn
agentfdr assert --no-loops --max-tokens 2M   # CI gate: exit 1 on violation
```

Options: `--port <n>` (auto-falls-back if taken), `--no-browser`, `--json`, `--lang en|ja` (auto-detected from `LANG`).

`assert` checks (any combination; exit code 1 if one fails): `--no-loops`, `--no-critical`, `--max-errors <n>`, `--max-turns <n>`, `--max-tokens <n>` (fresh input + cache write + output; accepts `500k` / `2M`), `--max-cost <usd>`.

## The viewer

The **dissection panel** lives on the right (always visible on wide screens; slides in on narrow ones) — click a turn and it fills in, and the timeline stays visible so you can step through turns (**←/→**, **Esc** deselects) without losing your place. Drag the panel's left edge to resize it; the width persists. While no turn is selected, the panel shows a **session overview**: the tools that did the work and the most-edited files.

Tabs switch the main view: **Timeline / Turns / Prompts / Subagents / Usage / Compare / Search** (Subagents appears only when the session spawned any); clicking a prompt, an anomaly chip, a subagent's spawn turn, or a search hit jumps back to the timeline at that turn. The filter box in the header narrows the session dropdown across all projects. Click a tool color in the legend to filter the tools lane. **Copy report** puts the blame markdown on your clipboard; **📤 Card** exports the session as a shareable PNG summary card; **● LIVE** re-fetches while the session is still running (on automatically via `agentfdr watch`); **🗂 Board** jumps to the live session board, and every board card links back here. The timeline title and the tab title carry the session's calendar date. Language and theme toggles are in the header; everything persists, and any view is deep-linkable (`?theme=dark&tab=usage&sel=95`).

**Session readout** — the header line lists every model that produced a turn (with per-model turn counts when the session switched models), the number of fast-mode turns, and the effort level. A caveat on effort: it is not a structured field in the transcript, so it's recovered from `/effort` command output and only appears when the level was set during the session.

**Cost estimate** — each session (and `stats`/`blame`) shows an estimated USD cost computed from list prices per model, with cache reads at ≈0.1× and cache writes at ≈1.25× the input price. It's an estimate: discounts, batch tiers, and price changes aren't visible in the transcript. Unknown models are excluded and flagged.

![Plan usage panel: 5-hour window, daily history, weekly totals and per-model breakdown](https://raw.githubusercontent.com/kamihork/agentfdr/main/assets/screenshot-usage-dark.png)

**Plan usage** — `agentfdr usage` (and the **Usage** panel in the viewer) aggregates every project's transcripts into the same shape your subscription is metered in: the current 5-hour rolling window, per-day history, and the rolling week, plus a per-model breakdown. Your plan tier (e.g. `claude_max · default_claude_max_5x`) is read from Claude Code's local config. Anthropic doesn't publish exact token limits, so you set your own budgets (`--budget-5h` / `--budget-week`, env `AGENTFDR_BUDGET_5H` / `AGENTFDR_BUDGET_WEEK`, or inputs in the viewer) and calibrate them against Claude Code's `/usage` screen — agentfdr then shows % consumed with warning colors.

## The board

`agentfdr board` is the other half of the cockpit: not one session after the fact, but **every session that is running right now**. Claude Code registers each live process under `~/.claude/sessions/` — its working directory, whether it is busy, idle or waiting on a dialog, and (for the CLI) the tmux pane it runs in. The board joins that registry with the tail of each transcript and refreshes every few seconds:

- **Columns by state** — 🔴 *Needs you* (permission prompt, question, plan approval), 🟢 *Working*, 🟡 *Idle* (finished, waiting for your next prompt), plus *Recently ended*. Group by project or account instead with one click.
- **Manual lanes** — switch the grouping to *manual lanes* and the board becomes yours to triage: name your own columns (defaults: Now / Later / Watching / Hold), drag cards between them and reorder within one, rename or delete lanes inline. New sessions land in *Unsorted*. Lanes and placement are saved in the browser and keyed by session id, so a restarted session keeps its lane; the state chip keeps telling you what the session is actually doing.
- **Each card** — the task you typed, what the agent is doing this second (or the last thing it said), turns / tool calls / errors / context size / estimated cost since that prompt, files it edited, and any anomaly flags on the current task.
- **Two accounts, one screen** — sessions are badged **CLI** or **Desktop** (Claude Code inside the Claude desktop app), the header names the account each app is signed in to, and the filter narrows to either. Desktop sessions come with the titles the app shows, and the sessions the app lists but has *parked* (no process until your next message) appear as idle cards marked *parked* — so the board and the app's sidebar agree on what is open. A Desktop session from an account other than the CLI's is marked *other account*.
- **Cross-session influence** — sessions on the same repository (worktrees resolve to their parent) are grouped, and a banner names the files that more than one live session is editing.
- **Steering** — for sessions running in tmux (any `tmux new-session … claude` launcher), the card offers *send…*, *approve*, *deny* and *stop*. Text is typed into the pane and submitted exactly as if you were at the keyboard (multi-line goes in as one paste); approve/deny press Enter/Esc on a permission prompt (other dialogs — questions, plan approval — get explicit *Enter* / *Esc* buttons instead, since their defaults differ); stop interrupts the turn. Approve/deny/stop are two-click, never modal, and the server refuses a key press when the session's state has changed since the card was drawn — a click meant for one dialog never answers the next. A `claude -p` or SDK process started from a session shares its pane and is shown read-only. Desktop-app and background (`--bg`) sessions have no pane to reach and are read-only.
- **Start a session** — *+ new session* opens a launcher: pick a directory (suggestions come from where you have run Claude Code before), an optional first prompt, model, and whether to continue that directory's last conversation. The board creates a detached tmux session named `claude-<dir>-<cksum>` — the same convention as a `tmux new-session … claude` shell wrapper keyed on the path, so `cc`-style launchers attach to it — runs `claude` there, and the new card appears as soon as it registers (a second session in the same directory gets a `-2` suffix). Sessions started this way are steerable like any tmux session.
- **Plan limits per account** — the 5-hour and 7-day usage bars Claude Code shows in its status line, per account, at the top of the board. Nothing on disk carries those numbers, so agentfdr ships a status-line pass-through that records them: put `agentfdr statusline-tap |` in front of your status-line command in `~/.claude/settings.json` (or use `agentfdr statusline-tap --line` on its own for a compact `[model] dir · 5h 26% · 7d 9%`). Readings land in `~/.agentfdr/rate-limits.json` keyed by account, with reset times; a second account in its own `CLAUDE_CONFIG_DIR` records under its own key. Until the tap is wired in, the strip says so once and stays out of the way.

```json
  "statusLine": { "type": "command", "command": "agentfdr statusline-tap | ~/.claude/statusline-command.sh" }
  ```
- **Cheap by design** — live transcripts grow past 100 MB; the board reads only the last 2 MB of each (`AGENTFDR_BOARD_TAIL_MB` to change), so a poll costs milliseconds. Stats prefixed with `≥` mean the current task started before that window.

The steering and launch endpoints only answer same-origin `POST`s from the board page itself, and the server stays on `127.0.0.1` — a page that can type into your agents must not be reachable by any other tab. `agentfdr board --json` prints the same board once, for scripts.

## Anomaly flags

Heuristics that answer "where do I look first?":

| Flag | Meaning |
|---|---|
| `loop` | The same tool-call sequence repeated 3+ times consecutively |
| ↳ convergence hint | A flagged loop also carries a hint read off the tool *results*: still changing (may be converging) vs. identical every pass (looks stuck). It is a hint, never an all-clear — the loop is flagged either way, and ties break toward "looks stuck" |
| `error-streak` | 3+ consecutive tool calls failed |
| `context-bloat` | A single tool result ≥50k chars landed in context |
| `token-spike` | Context jumped >60% (+50k) in one turn |
| `cache-thrash` | Consecutive turns paying full price, zero cache hits |
| `file-churn` | The same file edited 6+ times |
| `intent-drift` | The edits walked away from what the prompt asked for — and never came back before the next prompt. Only judged when the prompt named something the session actually opened; with no stated target there is no intent to measure drift against, so it stays quiet |
| `refusal` | A turn ended with `stop_reason: refusal` (safety decline) |
| `stalled-call` | A tool call never returned a result while the session moved on |
| `api-error` | A failing tool result carried an upstream API error (rate limit, overloaded, quota) |
| `custom` | Your own regex rules from `.agentfdr.json` (see below) |

### Configuration

All detectors are tunable via `.agentfdr.json` (looked up as `--config <path>` → `./.agentfdr.json` → `~/.agentfdr.json`). JSON rather than YAML keeps the zero-dependency promise. A malformed config is a hard error — a CI gate must never run with half its rules silently dropped.

```json
{
  "thresholds": { "loopRepeats": 5, "contextBloatChars": 100000 },
  "disable": ["cache-thrash"],
  "suppressLoops": ["Bash:npm test", "Edit:*"],
  "custom": [
    { "name": "quota-masked", "match": "quota exceeded|monthly limit",
      "in": "tool-results", "severity": "critical" }
  ]
}
```

- `thresholds` — override any detector threshold (`loopRepeats`, `loopMinCalls`, `loopRetryRepeats`, `errorStreak`, `contextBloatChars`, `tokenSpikeTokens`, `tokenSpikeRatio`, `cacheThrashTurns`, `fileChurnEdits`, `driftAnchorTurns`, `driftEditTurns`). `loopRetryRepeats` (default 6) is the bar for loops shaped like ordinary iteration — edit↔verify alternation, or a test/build/lint idiom repeating — vs. `loopRepeats` (default 3) for everything else. `driftEditTurns` (default 3) is how many consecutive off-target editing turns intent-drift needs; raise it if your changes are routinely cross-cutting
- `suppressLoops` — tool signatures whose repetition is legitimate (retrying a test, polling a build); exact match or `prefix*`
- `disable` — turn whole detectors off
- `custom` — your own regex rules over tool results and/or assistant text (`in`: `tool-results` | `assistant-text` | `both`), surfaced as first-class flags in the viewer, blame report, and `assert`

## How it works

Claude Code appends every event of a session — user prompts, assistant messages with full token usage, tool calls, tool results, compaction, mode changes — to a JSONL transcript under `~/.claude/projects/<project>/<session-id>.jsonl`. Codex CLI does the same with rollout files under `~/.codex/sessions/YYYY/MM/DD/`. `agentfdr` sniffs the format per file, parses both into one normalized turn model, and runs the same detectors over it. That's it: no daemon, no database, no runtime dependencies (Node ≥18 standard library only).

Subagents get transcripts of their own — `<session-id>/subagents/**/agent-*.jsonl`, with a sibling `.meta.json` naming the tool call that spawned them — so they are parsed lazily, only when you open the Subagents tab or run `blame`. Older Claude Code versions wrote sidechain turns inline in the main file instead; both shapes produce the same tree.

Neither transcript format is a published API, so the parsers are written to survive them: unknown line types become meta events, malformed lines are counted and skipped, and each format's quirks are contained in its own adapter module. Data locations can be overridden with `AGENTFDR_CLAUDE_DIR` / `AGENTFDR_CODEX_DIR`. (Plan usage tracks your Claude subscription and stays Claude-only.)

The board adds three more local sources, all Claude-only: the live-process registry `~/.claude/sessions/<pid>.json` (status and tmux pane, written by Claude Code itself; entries whose process is gone are ignored), `~/.claude/history.jsonl` for the full text of the prompt that started the current task, and the Claude desktop app's own session index (`~/Library/Application Support/Claude/claude-code-sessions/<account>/<org>/local_*.json` on macOS; `AGENTFDR_DESKTOP_DIR` to relocate) for Desktop session titles, parked sessions and account attribution. Steering shells out to `tmux send-keys` / `paste-buffer` against the registered pane — no private protocol, nothing injected into Claude Code.

## Privacy

Transcripts contain your code, your prompts, and your file paths. Therefore:

- everything runs locally; the server binds to `127.0.0.1` only
- there is no telemetry, no phone-home, no account
- `blame` output goes to stdout — you decide what leaves the machine

## Roadmap

- [x] Watch mode (`agentfdr watch`) with live timeline
- [x] CI gate — `agentfdr assert --no-loops --max-tokens 2M`
- [x] Cost estimation from per-model list prices
- [x] Session diff — compare the failed attempt with the successful retry
- [x] Pluggable detector rules — thresholds, suppressions and custom regex rules via `.agentfdr.json`
- [x] Codex CLI adapter — rollouts under `~/.codex/sessions` are auto-discovered
- [x] Loop-detector precision: interleaved edit↔verify cycles and test/build/lint idioms need more repeats before flagging — noise reduction, not exemption, so a session still stuck past that point is still caught
- [x] Convergence annotation on loops (worded as a hint, never an all-clear) — after the false-positive rate is boring
- [x] Intent-drift detection — flag the turn where the tool/file footprint diverges from what the prompt asked for
- [x] Subagent/sidechain tree rendering
- [x] Live session board (`agentfdr board`) — every running session on one kanban, with steering for tmux sessions

## Development

```sh
git clone https://github.com/kamihork/agentfdr.git && cd agentfdr
npm test                 # run tests
node bin/agentfdr.js     # run the CLI from source
```

`src/ui.html` is served fresh on every request — edit it and reload the browser, no restart needed.

Contributions welcome — especially new detector heuristics and viewer improvements. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

agentfdr

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README