{"_id":"@agentopssec/agent-flight-recorder","name":"@agentopssec/agent-flight-recorder","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@agentopssec/agent-flight-recorder","version":"1.0.0","description":"Local flight recorder for AI agent runs.","type":"module","homepage":"https://AgentOpsSec.com/projects/agent-flight-recorder","repository":{"type":"git","url":"git+https://github.com/AgentOpsSec/agent-flight-recorder.git"},"bugs":{"url":"https://github.com/AgentOpsSec/agent-flight-recorder/issues"},"bin":{"agent-flight":"bin/agent-flight.js"},"scripts":{"test":"node --test","check":"node --check bin/agent-flight.js && node --test"},"keywords":["agent","observability","flight-recorder","audit","cli"],"license":"MIT","engines":{"node":">=20"},"publishConfig":{"access":"public"},"author":{"name":"Aunt Gladys Nephew","url":"https://auntgladysnephew.com"},"gitHead":"2c90f19763d0f310c190225effd3ecdffd85e454","_id":"@agentopssec/agent-flight-recorder@1.0.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-vkAElDVVrVZqhJTcJv347yde3AZaFZMp9368lxeq1tyeJchRseLwMDDj/IjJIM8ylRaaRu7cqbQVl/izRUEpgQ==","shasum":"167189ef39126e2c82756de558a49a9ddd8595fa","tarball":"https://registry.npmjs.org/@agentopssec/agent-flight-recorder/-/agent-flight-recorder-1.0.0.tgz","fileCount":14,"unpackedSize":39743,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAzZVPdy23gIXcFNFwj6lus8it9SqV9DKZUKWld7HXXRAiBfZEAQZNhEG5Lrm7IEQ42ez94wgqSKOTzon6N1jLKMEw=="}]},"_npmUser":{"name":"agentopssec","email":"agentopssecurity@gmail.com"},"directories":{},"maintainers":[{"name":"agentopssec","email":"agentopssecurity@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-flight-recorder_1.0.0_1777236573009_0.8407846623849127"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T20:49:32.926Z","1.0.0":"2026-04-26T20:49:33.145Z","modified":"2026-04-26T20:49:33.346Z"},"maintainers":[{"name":"agentopssec","email":"agentopssecurity@gmail.com"}],"description":"Local flight recorder for AI agent runs.","homepage":"https://AgentOpsSec.com/projects/agent-flight-recorder","keywords":["agent","observability","flight-recorder","audit","cli"],"repository":{"type":"git","url":"git+https://github.com/AgentOpsSec/agent-flight-recorder.git"},"author":{"name":"Aunt Gladys Nephew","url":"https://auntgladysnephew.com"},"bugs":{"url":"https://github.com/AgentOpsSec/agent-flight-recorder/issues"},"license":"MIT","readme":"# Agent Flight Recorder\n\n**Debug, replay, and audit every AI agent run.**\n\nAgent Flight Recorder is a local observability tool for AI coding agents and\nMCP-powered workflows. It records what the agent was asked to do, what tools it\ncalled, what files changed, what commands ran, what errors happened, and what\nthe final result looked like.\n\nThink of it as:\n\n```txt\nChrome DevTools for AI agents\n```\n\n## Why This Exists\n\nAI coding agents can make useful changes quickly, but the path they take is\noften hard to inspect after the fact.\n\nDevelopers need answers to questions like:\n\n- What prompt started this run?\n- Which agent and model were used?\n- What files did the agent read or edit?\n- What commands did it run?\n- Did tests fail before they passed?\n- Did the agent retry or loop?\n- What did the final diff contain?\n- How long did the run take?\n- What did the run cost?\n\nAgent Flight Recorder turns an agent session into a local timeline.\n\n## Install\n\n```bash\nnpm install -g @agentopssec/agent-flight-recorder\n```\n\nOr run it without installing:\n\n```bash\nnpx -y @agentopssec/agent-flight-recorder list\n```\n\n## Update\n\n```bash\nagent-flight update          # check the registry, prompt before installing\nagent-flight update --yes    # update without prompting\n```\n\n## Primary Workflow\n\nAgent Flight Recorder starts by wrapping an agent command:\n\n```bash\nagent-flight run -- codex \"fix the failing tests\"\n```\n\nThe workflow should do three things well:\n\n1. Record the agent command and timeline.\n2. Capture files, commands, errors, and diffs.\n3. Produce a local report that can be inspected later.\n\n## CLI\n\n```bash\nagent-flight run \"codex fix the failing tests\"\nagent-flight run -- codex \"fix the failing tests\"\nagent-flight run -- gemini \"refactor this component\"\nagent-flight inspect latest\nagent-flight inspect run_001\nagent-flight replay run_001\nagent-flight export run_001 --html\nagent-flight list\nagent-flight diff run_001\nagent-flight update [--yes]\n```\n\n## Standalone and Stack Use\n\nAgent Flight Recorder runs on its own as a command wrapper:\n\n```bash\nagent-flight run -- codex \"fix the failing tests\"\nagent-flight inspect latest\n```\n\nWhen used with the full AgentOpsSec stack, its local run logs can feed Agent\nReview and Agent Cost Lens without either tool importing Agent Flight Recorder\ncode:\n\n```bash\nagent-review --from-agent-flight latest\nagent-cost month\n```\n\n## What Agent Flight Recorder Captures\n\nAgent Flight Recorder captures a timeline of an agent run, including:\n\n- User prompt\n- Agent command\n- Model and provider metadata when available\n- Token usage when available\n- Estimated cost\n- Latency\n- Tool calls observed in agent output or provided through structured metadata\n- MCP server calls observed in agent output or provided through structured metadata\n- Shell commands\n- File reads\n- File writes\n- Git diffs\n- Test runs\n- Errors\n- Retries\n- Final response\n- Final code diff\n\nAgent Flight Recorder includes lightweight adapters for common CLI names such as\nCodex, Claude, Gemini, and OpenCode. Exact tool-call and token capture depends\non what the wrapped CLI prints or provides through environment metadata.\n\n## Example Timeline\n\n```txt\nAgent Flight Recorder Run by github.com/AgentOpsSec\n\nRun: fix-failing-tests-0425\n\n1. Prompt received\n2. Model call: 12.8s, 18,400 tokens\n3. Tool call: filesystem.read package.json\n4. Tool call: shell.exec npm test\n5. Error detected: TypeScript compile failure\n6. File edit: src/lib/parser.ts\n7. File edit: package.json\n8. Tool call: shell.exec npm install\n9. Tool call: shell.exec npm test\n10. Tests passed\n11. Final diff: 6 files changed\n12. Estimated cost: $0.42\n```\n\n## Run Log Shape\n\n```json\n{\n  \"tool\": {\n    \"name\": \"Agent Flight Recorder\",\n    \"by\": \"github.com/AgentOpsSec\",\n    \"repository\": \"github.com/AgentOpsSec/agent-flight-recorder\"\n  },\n  \"runId\": \"run_001\",\n  \"startedAt\": \"2026-04-25T10:00:00Z\",\n  \"endedAt\": \"2026-04-25T10:04:12Z\",\n  \"agent\": \"codex\",\n  \"model\": \"unknown\",\n  \"prompt\": \"fix the failing tests\",\n  \"events\": [\n    {\n      \"type\": \"shell.exec\",\n      \"command\": \"npm test\",\n      \"exitCode\": 1,\n      \"durationMs\": 12944\n    },\n    {\n      \"type\": \"file.change\",\n      \"path\": \"src/lib/parser.ts\",\n      \"changeType\": \"modified\"\n    }\n  ],\n  \"gitDiffSummary\": {\n    \"filesChanged\": 3,\n    \"insertions\": 44,\n    \"deletions\": 18\n  },\n  \"estimatedCost\": 0.18\n}\n```\n\n## Local Reports\n\nReports are designed for both terminal inspection and automation:\n\n- Local JSON run logs\n- Terminal run summaries\n- Final diff summaries\n- HTML exports\n- Run list and latest-run inspection\n- Cost and latency summaries where available\n\n## Design Principles\n\n- Local-first\n- Open-source\n- No telemetry by default\n- Complete local run history\n- Useful terminal summaries\n- Exportable reports\n- Replayable context\n- Practical cost visibility\n\n## Initial Release Scope\n\nThe initial release includes command wrapping, run timeline capture, git diff\ncapture, local reports, HTML export, and cost estimation.\n\n### 1.0: Command Wrapper\n\n- Wrap local agent commands\n- Capture the requested prompt and command\n- Record start and end timestamps\n- Detect the current repository\n- Store each run under a local run ID\n- Print a clear terminal summary when the run finishes\n\n### 1.0: Timeline and Diff Capture\n\n- Capture shell commands when available\n- Capture file changes before and after the run\n- Capture git diff summaries\n- Record errors and non-zero exits\n- Track test command execution\n- Store structured JSON run logs\n\n### 1.0: Inspection and Export\n\n- Inspect the latest run\n- List previous runs\n- View final diffs for a run\n- Export a run as HTML\n- Estimate token and provider cost where possible\n- Compare basic run metadata across sessions\n\n\n## Output\n\nReports use plain-language status words rather than raw exit codes:\n\n- `ok` — the step ran successfully (green).\n- `failed (exit N)` — the step exited non-zero (red); the original code is preserved.\n- `skipped (reason)` — the step was not applicable (dim).\n\nSeverity colors follow the AgentOpsSec palette (safe = green, warning = amber, risk = red). The palette honors `NO_COLOR` and `FORCE_COLOR`, and JSON / CSV output stays plain.\n\n\n- Repo: https://github.com/AgentOpsSec/agent-flight-recorder\n- npm: https://www.npmjs.com/package/@agentopssec/agent-flight-recorder\n- AgentOpsSec stack: https://github.com/AgentOpsSec/stack\n- Website: https://AgentOpsSec.com\n\n## Author\n\nCreated and developed by **Aunt Gladys Nephew**.\n\n- Website: https://auntgladysnephew.com\n- GitHub: https://github.com/auntgladysnephew\n- X: https://x.com/AGNonX\n","readmeFilename":"README.md","_rev":"1-2bbd2b087deec58bfa1a60904b59cd8b"}