agent-inspect CLI
A local debugger for TypeScript agents: run step trees, CI trajectory checks and portable evidence bundles, with no account.
- 212 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Writes local traces of agent runs; if raw prompt and output capture is enabled, your data may end up in them.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/agent-inspectDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Writes local traces of agent runs; if raw prompt and output capture is enabled, your data may end up in them.
This is third-party code. Review the repository files before installing.
What it does
`agent-inspect` records a TypeScript agent run to a local JSONL file and shows it as a tree: nested steps, tool and model calls, durations, errors and the first causal failure. Data stays on the machine: there is no account, collector or default upload, and raw prompts and outputs are saved only when explicitly enabled. Three groups of commands cover three jobs. `view`, `report` and `explain` dissect a past run. `check` verifies the trajectory deterministically with no judge model, for example that the agent called `retrieve_policy`; a violation exits with code 1, so the check belongs in CI. `bundle` builds a redacted Evidence v2 archive with a manifest and hashes, and `verify-safe` assesses whether it is safe to share. Adapters exist for LangChain and LangGraph, AI SDK and OpenAI Agents, and `@agent-inspect/mcp-server` gives a coding agent read-only access to traces.
Who it is for. Developers of TypeScript agents who need to understand why an agent picked the wrong tool and to ban that path in CI.
Good fit when
- An agent circles in loops and flat logs show only fragments of calls.
- A behavioural regression has to be caught in a pull request: a test fails if a mandatory tool is skipped.
- A trace must be attached to an issue or incident report without leaking secrets.
- Runs are built on LangGraph, AI SDK or OpenAI Agents and you need one trace format.
- Cursor or Claude Code should read traces itself through MCP rather than asking you to paste logs.
Not a fit when
- The agent is not written in TypeScript: the package does not cover other languages.
- You need trace hosting, team dashboards and production monitoring: this is not a cloud APM.
- You want model-judged answer scoring and datasets: the package is not that kind of platform by default.
Example request
Show the tree of the latest run in `.agent-inspect`, find the first step after which the agent went wrong and run `check` with the trajectory preset.Limitations
The package targets TypeScript and Node.js 20 or newer; individual adapters and the MCP server carry Supported, Beta or Preview status. `verify-safe` and redaction (`redact`) are best-effort and do not replace a compliance review, so inspect a bundle before publishing it. Only metadata is saved by default, and raw prompts and outputs are enabled separately. The VS Code extension lives in the repository but is not published to the marketplace.
How to disable. Run `npm uninstall agent-inspect`, delete the `.agent-inspect/` folder with traces and, if you connected MCP, remove the `agent-inspect` entry from the client configuration.
FAQ
How do I install agent-inspect and get a first trace?
Run `npm install agent-inspect`, then `npx agent-inspect init --yes` and `node examples/agent-inspect-demo.mjs`. `npx agent-inspect list --dir .agent-inspect` shows the run ID for `view` and `check`.
How do I catch a wrong agent path in CI?
Run `npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory --required-tool retrieve_policy`. Success exits 0 and a rule failure exits 1, so CI stops the build itself.
Do traces leave the machine?
No, capture and inspection run locally by default, without an account or collector. Network appears only in optional parts such as standards export, each with its own boundaries.
How do I connect MCP for a coding agent?
`npx agent-inspect mcp configure --client cursor` prints a dry-run configuration. Review it and the coding-agent loop guide before enabling; the MCP server is read-only and still in Preview.
What is inside an Evidence bundle?
Redacted trace data and a manifest with file hashes. `bundle verify ./evidence` rechecks the hashes offline, and `verify-safe` first assesses whether sharing is safe.
Discussion
No questions or reviews yet.
Related
CLI toolsVercel CLI for testing coding agents on your framework: runs Claude Code, Codex and others and measures the success rate
CLI, MCP server and typed Node.js API so an agent can verify its changes in a live mobile app on iOS, Android and more
agentevals scores AI agent behavior from OpenTelemetry traces and ships MCP tools plus the /eval and /inspect skills.
A static linter for agent instructions: finds ambiguous tool descriptions and schema gaps before a run, with no model or network
A Playwright and TypeScript project template with rules and 17 skills so Claude Code, Codex and Cursor write tests to a standard
An MCP server that checks whether the agent is really done: drives the real app and returns pass, fail or couldn't tell with the file and line
README in short
The README builds its story around one trace and three jobs: debug, prevent and share. After that come a framework compatibility table, a programmatic check example, a network behaviour section and the list of family packages.