Local evidence debugger

See what your agent did. Catch the wrong path in CI. Keep the evidence local.

AgentInspect turns TypeScript agent runs into readable execution trees, deterministic trajectory checks, and portable Evidence v2—without requiring an account, collector, or default upload.

Capture once. Debug, prevent, and share from the same local trace.

No account · no collector · no default upload · metadata-only by default

1. Capture one local run
2. Debug the execution tree
3. Prevent the wrong trajectory in CI
4. Share-checked Evidence v2
5. Optional: inspect the same facts over read-only MCP

npm install agent-inspect

Run the five-minute path Trajectory checks View on GitHub

v6.17.2TraceFactsEvidence v2MIT

Actively maintained · schema 1.0 · Node.js 20+ · MIT

List a local run, then inspect the execution tree.

Capture once. Debug, prevent, and share from the same local trace.

Zero open pilot findings at the 6.16.0 moderate + deep-swarm gates.
Hardening timeline 6.7.3 → 6.16.0; Evidence UX in 6.17.1; fixture-backed demos.

Three jobs

One local evidence loop

Capture once. Debug the tree, prevent the wrong trajectory, and share-checked Evidence v2. Optional read-only MCP stays below the fold.

Debug

Read nested steps, tools, model metadata, and the first causal failure from local JSONL.

Prevent

Deterministic check presets, TraceContract, suites, and CI gates — no LLM judge required.

Share-checked Evidence v2 with integrity verification. Not a compliance certification.

Five-minute path

One broken run → causal report → share-checked evidence

init scaffolds files; the demo writes the trace. Then report, check, bundle, verify-safe, and optionally mcp configure / bundle verify with real targets.

Deterministic starter path — no API keys required.

bash

npm install agent-inspect
npx agent-inspect init --yes
node examples/agent-inspect-demo.mjs
npx agent-inspect list --dir .agent-inspect
# copy <run-id> from list, then:
npx agent-inspect report <run-id> --dir .agent-inspect
npx agent-inspect check <run-id> --dir .agent-inspect
npx agent-inspect bundle <run-id> --dir .agent-inspect --profile share
npx agent-inspect verify-safe <run-id> --dir .agent-inspect
# Evidence v2 integrity (path from bundle output):
npx agent-inspect bundle verify .agent-inspect/bundles/<run-id>
# Optional coding-agent loop (dry-run by default):
npx agent-inspect mcp configure --client cursor

Code

Start from the path you already use

Real install lines and CLI targets—copy, run, then attach share-checked evidence. No collector account.

import { inspectRun, step } from "agent-inspect";

await inspectRun("support-agent", async () => {
  const intent = await step("classify intent", () =>
    classifyIntent(ticket)
  );

  const docs = await step.tool("search knowledge base", () =>
    searchKnowledgeBase(intent)
  );

  return step.llm("draft-model", () =>
    generateResponse(docs)
  );
});

Hero flow

From one broken run to share-checked evidence

The flagship loop is local evidence—not a hosted dashboard. Studio is optional Tier C, never the product story.

Capture one real run

Manual steps, adapters, logs, harness, or standards files → local JSONL under `.agent-inspect/`.

init → demo → list

Find the causal failure

Trees, reports, and a conservative first-causal-failure engine surface what failed first—not just the last error.

report <run-id>

Ask your coding agent

Read-only MCP Preview tools (`get_first_causal_failure`, trees, evidence) over local traces—stdio only.

mcp configure --client cursor

Lock the fix with a contract

Deterministic `check`, TraceContract (Beta), suites, cohorts, and CI gates so the bug stays fixed.

check <run-id>

Attach share-checked evidence

Redact → verify-safe → Evidence v2 bundle + `bundle verify`. Studio Beta stays optional (customer-owned).

bundle … --profile share

Proven mechanisms

Built for the TypeScript agent inner loop

First causal failure

Conservative ordered engine points at what failed first—not just the last stack frame.

Coding-agent MCP loop

Read-only Preview MCP tools over local traces (`mcp configure`, stdio server).

Share-checked Evidence v2

`bundle` + `bundle verify` produce offline share-profile artifacts you can attach to a PR.

Deterministic contracts & CI

`check`, TraceContract (Beta), suites/cohorts, and Vitest/Jest reporters for PR gates.

Local JSONL as source of truth

Own runs as files under `.agent-inspect/`. No account, no default upload.

Execution trees

Nested steps, tool/LLM types, durations, and status in a readable tree and timeline.

Metadata-only by default

Safe defaults keep prompts and outputs out of traces unless you opt in.

Redaction profiles

`local`, `share`, and `strict` before issues, PRs, or partner threads—then `verify-safe`.

Real needs

Where the local evidence loop wins

Debug a broken run with your coding agent

Configure MCP (dry-run), ask for get_first_causal_failure, fix in the app, re-inspect, then create share-checked evidence.

Debug a wrong tool call locally

See the tool step, siblings, and parent run without leaving your terminal or uploading traces.

Attach share-checked evidence to a PR

Redact with the share profile, verify-safe, bundle, then bundle verify before you attach the artifact.

Catch stalled agent runs in CI

Use deterministic checks for completion and stalls on fixture traces—no LLM judge required.

Compare before/after agent behavior

Diff two local runs when a prompt, tool, or model change lands.

Review traces without a hosted dashboard

CLI, TUI, localhost viewer, or the in-repo VS Code extension—files stay on disk.

The problem

console.log was not built for agents

Agent runs are nested, parallel, tool-heavy, and privacy-sensitive. Flat logs tell you something happened. They rarely show what happened in order, where it branched, or what is safe to share.

Flat logs hide nested decisions

You see a tool name, not the parent run, siblings, or where the branch went wrong.

Parallel tool calls get interleaved

Concurrent work collapses into a stream of lines without step boundaries.

You cannot ask a coding agent what failed first

Without a causal tree and read-only tools, chat agents guess from logs instead of inspecting the run.

Raw traces can leak customer data

Without redaction, verify-safe, and share-checked Evidence v2, PR attachments can expose more than you intended.

Boundaries

Local-first by design. Not a hidden platform.

Not a hosted SaaS dashboard
Not a production APM replacement
Not an eval dataset platform
Not a prompt registry
Not a hidden uploader
Not a chain-of-thought recorder
Not a replay engine

Compare

Complementary, not a replacement

Use AgentInspect for the local developer loop. Use hosted platforms or OpenTelemetry for production observability. They can complement each other.

Capability	agent-inspect	console.log	Hosted observability	Raw OpenTelemetry
Local-first	Yes — traces on disk	Yes	Usually account + ingestion	Depends on collector/backend
Account required	No	No	Usually yes	No for SDK; yes for many backends
Upload required	No by default	No	Usually yes	Exporter/collector dependent
Execution tree	Built-in	Flat stream	Often yes	Spans/traces with setup
CI checks	Deterministic CLI checks	Manual	Platform-specific	Custom pipelines
Safe redaction flow	Profiles + verify-safe + Evidence v2 bundle verify	Manual	Varies	Custom
Coding-agent inspect	Read-only MCP Preview (stdio, local traces)	No	Usually chat-only or remote tools	Custom tooling
Team dashboard	No maintainer-hosted dashboard; optional customer-owned Studio Beta	No	Yes	Via backend/viewer
Production monitoring	Not the goal	No	Yes	Yes, with platform setup
Best for	Local debugging, deterministic trajectory regression, safe evidence, customer-owned review	Tiny scripts	Production fleets and hosted collaboration	Platform observability foundation

Open source trust

Transparent defaults you can audit

AgentInspect is MIT-licensed, dependency-light at the root, and explicit about network behavior: no upload by default.

MIT license Local JSONL files Metadata-only default Redaction profiles verify-safe before sharing GitHub issues and discussions npm package Technical guide Safe trace sharing docs

FAQ

Straight answers

Does AgentInspect upload traces?+

No default upload and no hidden telemetry. Traces stay on disk unless you explicitly share a file, enable customer-owned Studio ingest, or configure a standards export.

What can explicitly use the network?+

Optional Studio GitHub/HTTP ingest (off by default), MCP clients talking to your servers, MCP server exposing local evidence to a connected client, and any standards/collector path you configure. See Network behavior docs.

Is Studio hosted by AgentInspect?+

No. Studio Beta is customer-owned and binds to localhost by default. There is no AgentInspect-hosted cloud dashboard.

Is this production APM?+

No. Use hosted platforms or OpenTelemetry for production fleets. AgentInspect is for local debugging, deterministic trajectory regression, and safe evidence.

What is Stable / Beta / Preview?+

Support levels describe maturity. Core schema/checks/redaction are Stable; TraceContract/suites/index/Studio are Beta; MCP server and some ingest paths are Preview. See SUPPORT-LEVELS.md on GitHub.

Does it record prompts, outputs, or chain-of-thought?+

Capture is metadata-only by default. It does not record chain-of-thought. Opt into content capture only when you intentionally need it.

How do contracts differ from evals?+

TraceContract and checks are deterministic trajectory expectations. Eval helpers are local heuristics. Neither is an LLM judge by default.

What is the coding-agent loop?+

Use `agent-inspect mcp configure --client cursor` (dry-run by default) and `@agent-inspect/mcp-server` over a local trace dir. Flagship read-only tools include get_trace_facts, get_first_causal_failure, and create_share_checked_evidence. Preview maturity—see CODING-AGENT-LOOP.md.

Do Vitest/Jest TraceContract matchers exist?+

Yes, as Experimental exports: toPassTraceContract and toHaveRequiredTool via agentInspectVitestMatchers / agentInspectJestMatchers. Reporters remain the primary CI artifact path.

Where are the full docs?+

This site summarizes the product. Canonical deep reference lives on GitHub under docs/.

Get your first local trace in five minutes

Install AgentInspect, run the deterministic demo, and keep traces on your machine.

npm install agent-inspect

Read the docs Star on GitHub