Skip to content
Back to search

agent-inspect

Local evidence debugger and trajectory-test toolkit for TypeScript AI agents: inspect causal runs, catch wrong tool paths in CI, and share safe offline evidence.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/rajudandigam/agent-inspect with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/rajudandigam/agent-inspect'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rajudandigam--agent-inspect/badge.svg)](/listings/rajudandigam--agent-inspect)

HTML

<a href="/listings/rajudandigam--agent-inspect"><img src="/api/listings/rajudandigam--agent-inspect/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 232 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/agent-inspect-logo-mark.svg?sanitize=true" width="56" height="56" alt="AgentInspect">
  3. </p>
  4. <p align="center"><strong>agent-inspect</strong></p>
  5. <p align="center">Local-first evidence for TypeScript AI agents</p>
  6. <h1 align="center">
  7. See what your agent did.<br>
  8. Catch the wrong path in CI.<br>
  9. Keep the evidence local.
  10. </h1>
  11. <p align="center">
  12. AgentInspect turns TypeScript agent runs into readable execution trees,
  13. deterministic trajectory checks, and portable Evidence v2—without requiring
  14. an account, collector, or default upload.
  15. </p>
  16. <p align="center"><strong>Capture once. Debug, prevent, and share from the same local trace.</strong></p>
  17. <p align="center"><sub>No account · no collector · no default upload · metadata-only by default</sub></p>
  18. <p align="center">
  19. <a href="https://agentinspect.vercel.app/">Website</a> ·
  20. <a href="https://agentinspect.vercel.app/docs/">Docs</a> ·
  21. <a href="https://www.npmjs.com/package/agent-inspect">npm</a> ·
  22. <a href="https://github.com/rajudandigam/agent-inspect">GitHub</a>
  23. </p>
  24. <p align="center">
  25. <a href="https://www.npmjs.com/package/agent-inspect"><img src="https://img.shields.io/npm/v/agent-inspect.svg" alt="npm version"></a>
  26. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
  27. <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js 20 or newer"></a>
  28. </p>
  29. **Support level:** Stable — see [SUPPORT-LEVELS.md](docs/SUPPORT-LEVELS.md). Network behavior: [NETWORK-BEHAVIOR.md](docs/NETWORK-BEHAVIOR.md).
  30. ```bash
  31. npm install agent-inspect
  32. ```
  33. <p align="center">
  34. <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/showcase/gif/debug-tree.gif" alt="AgentInspect lists a local demo-good run, then you inspect the execution tree from the same JSONL" width="900">
  35. </p>
  36. Agent code rarely fails as one function call. It plans, retrieves, calls tools, invokes a model, retries, and produces side effects. Flat logs show fragments. AgentInspect keeps the run as local JSONL and gives you one evidence loop from the same trace.
  37. <p align="center">
  38. <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/readme-product-loop.svg?sanitize=true" alt="Capture one local trace, then debug, prevent, and share from the same evidence loop" width="900">
  39. </p>
  40. ## One trace. Three jobs.
  41. ### Debug — read the execution path
  42. See nested steps, tool calls, LLM calls, model and token metadata, durations, errors, and the first causal failure without sending the trace to an AgentInspect service.
  43. ```bash
  44. npx agent-inspect view <run-id> --dir .agent-inspect --summary
  45. npx agent-inspect report <run-id> --dir .agent-inspect
  46. npx agent-inspect explain <run-id> --dir .agent-inspect
  47. ```
  48. Use manual instrumentation, official adapters, supported standards files, or structured logs you already emit.
  49. ### Prevent — fail CI on the wrong trajectory
  50. <p align="center">
  51. <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/showcase/gif/check-pass-fail.gif" alt="The same deterministic AgentInspect check exits zero for demo-good and one for demo-regression" width="900">
  52. </p>
  53. Checks are deterministic and provider-free: the same trace and rules produce the same result. Start with a preset, then extend it with the expectations that matter to the workflow.
  54. ```bash
  55. npx agent-inspect check <run-id> --dir .agent-inspect \
  56. --preset trajectory \
  57. --required-tool retrieve_policy
  58. ```
  59. Use `--fail-on-observation failed` only when the run records explicit OUTCOME events (for example the [broken-agent-debugging starter](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/broken-agent-debugging)). Trajectory checks do not invent outcomes from tool/LLM/run success.
  60. A passing check exits `0`; a rule failure exits `1`. Invalid configuration and unreadable/unsupported inputs use separate documented exit codes. Use TraceContract, suites, cohorts, Vitest/Jest reporters, or `--evidence-on fail` when the workflow needs more than one CLI check.
  61. ### Share — create reviewable offline evidence
  62. <p align="center">
  63. <img src="https://raw.githubusercontent.com/rajudandigam/agent-inspect/main/docs/assets/showcase/gif/evidence-bundle.gif" alt="AgentInspect writes a share-checked Evidence v2 bundle to ./evidence and verifies the listed file hashes offline" width="900">
  64. </p>
  65. ```bash
  66. npx agent-inspect verify-safe <run-id> --dir .agent-inspect
  67. npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share --out ./evidence
  68. npx agent-inspect bundle verify ./evidence
  69. ```
  70. `verify-safe` is a best-effort local assessment and can report `SAFE`, `SAFE WITH WARNINGS`, `UNSAFE`, or `UNKNOWN`. `bundle` writes a redacted artifact and manifest; `bundle verify` rechecks the listed file hashes offline. “Share-checked” is not compliance certification—review the artifact before attaching it to a PR, incident, or support handoff.
  71. ## First local trace
  72. The generated demo is synthetic, keyless, and local. `npm install agent-inspect` does not copy repository examples; `init` writes them into the project.
  73. ```bash
  74. npm install agent-inspect
  75. npx agent-inspect init --yes
  76. node examples/agent-inspect-demo.mjs
  77. npx agent-inspect list --dir .agent-inspect
  78. ```
  79. Copy the printed run ID, then inspect it:
  80. ```bash
  81. npx agent-inspect view <run-id> --dir .agent-inspect --summary
  82. npx agent-inspect check <run-id> --dir .agent-inspect --preset trajectory
  83. npx agent-inspect verify-safe <run-id> --dir .agent-inspect
  84. ```
  85. For a fixed good/regression/PII walkthrough with stable run ids (`demo-good`, `demo-regression`, `demo-pii`), use the [canonical keyless showcase](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters/broken-agent-debugging). The richer [blessed starters](https://github.com/rajudandigam/agent-inspect/tree/main/examples/starters) cover framework-specific paths.
  86. ## Use it with your stack
  87. | Stack | Install / command | Start |
  88. | --- | --- | --- |
  89. | Custom functions or classes | `agent-inspect` | [Getting started](https://github.com/rajudandigam/agent-inspect/blob/main/docs/GETTING-STARTED.md) |
  90. | LangChain / LangGraph | `agent-inspect` + `@agent-inspect/langchain` | [LangGraph guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/LANGGRAPH.md) |
  91. | AI SDK | `agent-inspect` + `@agent-inspect/ai-sdk` | [AI SDK guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/AI-SDK-ADOPTION.md) |
  92. | OpenAI Agents JS | `agent-inspect` + `@agent-inspect/openai-agents` | [Local processor guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/OPENAI-AGENTS-LOCAL.md) |
  93. | Existing structured logs | `npx agent-inspect logs ...` | [Log-to-tree quickstart](https://github.com/rajudandigam/agent-inspect/blob/main/docs/LOG-TO-TREE-QUICKSTART.md) |
  94. | OpenInference / OTLP JSON | `npx agent-inspect open ...` | [Standards](https://github.com/rajudandigam/agent-inspect/blob/main/docs/STANDARDS.md) |
  95. | Vitest / Jest CI | `@agent-inspect/vitest` / `@agent-inspect/jest` | [CI artifacts](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CI-ARTIFACTS.md) |
  96. See [support levels](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SUPPORT-LEVELS.md) for Stable, Supported, Beta, Preview, and Experimental surfaces.
  97. ## Programmatic trajectory checks
  98. ```ts
  99. import { openTraceFile } from "agent-inspect/readers";
  100. import {
  101. defineTraceContract,
  102. evaluateTraceContractRead,
  103. } from "agent-inspect/checks";
  104. const read = await openTraceFile("./trace.jsonl");
  105. const contract = defineTraceContract({
  106. run: { requireCompleted: true },
  107. tools: { required: ["retrieve_policy"] },
  108. });
  109. const result = evaluateTraceContractRead(read, contract);
  110. if (result.status !== "pass") process.exitCode = 1;
  111. ```
  112. The full API also exposes TraceFacts for bounded, logical analysis of supported traces. See [programmatic trace analysis](https://github.com/rajudandigam/agent-inspect/blob/main/docs/PROGRAMMATIC-TRACE-ANALYSIS.md).
  113. ## Where AgentInspect fits
  114. AgentInspect owns the laptop-to-PR evidence loop. It complements hosted observability, production trace retention, and broad eval platforms rather than replacing them.
  115. | Need | Best fit |
  116. | --- | --- |
  117. | Inspect one local TypeScript agent run immediately | AgentInspect |
  118. | Enforce deterministic tool/order/completion expectations in CI | AgentInspect |
  119. | Attach a redacted, hash-verifiable offline artifact | AgentInspect |
  120. | Monitor a production fleet with hosted dashboards and retention | Hosted observability / APM |
  121. | Manage prompts, datasets, and online LLM-judge experiments | Eval / prompt platforms |
  122. See the factual [comparison guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/COMPARE.md).
  123. ## Safety and network behavior
  124. - Traces are local JSONL under `.agent-inspect/` or `AGENT_INSPECT_TRACE_DIR`.
  125. - Capture is metadata-only by default; raw prompts and outputs require opt-in.
  126. - Write-time redaction is enabled by default. The `redact` command creates a separate redacted copy and does not mutate its source.
  127. - Core capture and inspection do not require an AgentInspect account, collector, or default upload.
  128. - Redaction and `verify-safe` are best-effort controls, not privacy, security, or compliance certification.
  129. - Optional MCP, standards export, and customer-owned Studio surfaces are explicit and have their own network boundaries.
  130. - AgentInspect is not a chain-of-thought recorder.
  131. Read [network behavior](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NETWORK-BEHAVIOR.md), [no-egress policy](https://github.com/rajudandigam/agent-inspect/blob/main/docs/NO-EGRESS-POLICY.md), and [safe trace sharing](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SAFE-TRACE-SHARING.md).
  132. ## Optional coding-agent loop
  133. `@agent-inspect/mcp-server` exposes configured local evidence to an MCP client through bounded, read-only tools. It is optional and currently Preview; the core debug/check/evidence loop does not require it.
  134. ```bash
  135. npx agent-inspect mcp configure --client cursor
  136. ```
  137. Review the generated dry-run configuration and the [coding-agent loop guide](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CODING-AGENT-LOOP.md) before enabling it.
  138. <details>
  139. <summary><strong>Package family (18-package fixed release group)</strong></summary>
  140. | Group | Packages |
  141. | --- | --- |
  142. | Core product | `agent-inspect`, `@agent-inspect/redact` |
  143. | Framework integrations | `@agent-inspect/ai-sdk`, `@agent-inspect/openai-agents`, `@agent-inspect/langchain` |
  144. | Testing and evaluation | `@agent-inspect/harness`, `@agent-inspect/eval`, `@agent-inspect/vitest`, `@agent-inspect/jest` |
  145. | Safety analysis | `@agent-inspect/guardrails`, `@agent-inspect/circuit` |
  146. | Developer surfaces | `@agent-inspect/viewer`, `@agent-inspect/tui`, `@agent-inspect/mcp`, `@agent-inspect/mcp-server` |
  147. | Local/team optional surfaces | `@agent-inspect/index-sqlite`, `@agent-inspect/studio` |
  148. | Extension SDK | `@agent-inspect/adapter-sdk` |
  149. The root package is enough for custom capture, the CLI, checks, and Evidence workflows. Install optional packages only for the integration or surface you use. `agent-inspect-vscode` is currently in the repository and is not presented as a published Marketplace extension.
  150. </details>
  151. ## What it is not
  152. - A maintainer-hosted SaaS or production APM replacement
  153. - Hosted trace retention, a team dashboard service, or a prompt registry
  154. - An LLM-as-judge or dataset platform by default
  155. - A replay engine, automatic remediation system, or compliance certification
  156. ## Status and documentation
  157. **Current published baseline:** **6.31.37** · persisted schema `1.0` · Node.js `>=20` · MIT.
  158. Legacy v0.1 and v0.2 traces remain readable. Check the npm badge and [changelog](CHANGELOG.md) for the current published version.
  159. - [First trace in five minutes](https://github.com/rajudandigam/agent-inspect/blob/main/docs/FIRST-TRACE-IN-5-MINUTES.md)
  160. - [CLI reference](https://github.com/rajudandigam/agent-inspect/blob/main/docs/CLI.md)
  161. - [Trace contracts](https://github.com/rajudandigam/agent-inspect/blob/main/docs/TRACE-CONTRACTS.md)
  162. - [Evidence format](https://github.com/rajudandigam/agent-inspect/blob/main/docs/EVIDENCE-FORMAT.md)
  163. - [Use cases](https://github.com/rajudandigam/agent-inspect/blob/main/docs/USE-CASES.md)
  164. - [Demos and screenshots](https://github.com/rajudandigam/agent-inspect/blob/main/docs/SCREENSHOTS.md)
  165. - [Full documentation index](https://github.com/rajudandigam/agent-inspect/blob/main/docs/README.md)
  166. ## Contributing
  167. See [CONTRIBUTING.md](CONTRIBUTING.md), [good first issues](GOOD-FIRST-ISSUES.md), and [GitHub Discussions](https://github.com/rajudandigam/agent-inspect/discussions).
  168. **Redact and review traces before posting them in issues or pull requests.**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.