[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81451":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":45,"readmeContent":46,"aiSummary":47,"trendingCount":16,"starSnapshotCount":16,"syncStatus":48,"lastSyncTime":49,"discoverSource":50},81451,"agent-inspect","rajudandigam\u002Fagent-inspect","rajudandigam","Local execution trees for TypeScript AI agents.  agent-inspect helps you understand what happened inside an AI agent run — locally. It turns manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into readable execution trees you can inspect from the terminal.  It is built for TypeScript\u002FNode.js developers..","https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fagent-inspect",null,"TypeScript",95,81,72,17,0,60,63,180,5.74,"MIT License",false,"main",true,[26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44],"agent-observability","agentic-ai","ai","ai-agent","ai-debugging","ai-logging-library","ai-observability","ai-systems","braintrust","langfuse","langsmith","local-logging","logging","multi-agent","no-cloud","no-cost","observability","opentelemetry","typescript","2026-06-12 02:04:15","# agent-inspect\n\n**Local execution trees for TypeScript AI agents.**\n\nagent-inspect helps you understand what happened inside an AI agent run — **locally**. It turns manual steps, tool calls, LLM calls, structured logs, failures, durations, and run metadata into **readable execution trees** you can inspect from the terminal.\n\nIt is built for TypeScript\u002FNode.js developers and teams shipping real agentic products — not just toy demos. Use it **before** a hosted observability platform, **alongside** one, or as the **local debugging layer** underneath enterprise observability.\n\nThe tool starts with **manual traces** and **existing structured logs**, and extends into **optional framework callbacks** and **standards-aligned local export** — without turning the core into a SaaS or a vendor pipeline.\n\n**No account. No cloud upload. No dashboard required.**\n\n## Why agent-inspect exists\n\nAI agents are no longer single function calls. They plan, call tools, invoke LLMs, branch, retry, fail, and run work in parallel. **Console logs are flat**; reconstructing causality from a wall of lines is slow and error-prone.\n\n**Hosted observability** is valuable in production, but it can be heavy for the **inner loop**: local runs, fast iteration, and debugging before anything reaches a collector or dashboard.\n\nagent-inspect gives those runs **structure**: an **execution tree** you can read and diff on disk, with a **CLI-first** workflow and **no vendor lock-in**.\n\n## Install\n\n```bash\nnpm install agent-inspect\n```\n\n```bash\npnpm add agent-inspect\n```\n\nVerify the CLI is available:\n\n```bash\nnpx agent-inspect --help\n```\n\n## 60-second quickstart\n\nCreate `demo.mjs`:\n\n```js\nimport { inspectRun, step } from \"agent-inspect\";\n\nconst delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));\n\nawait inspectRun(\n  \"support-agent\",\n  async () => {\n    const plan = await step(\"plan\", async () => {\n      await delay(40);\n      return { intent: \"refund-policy\", needsPolicy: true };\n    });\n\n    const policy = await step.tool(\"retrieve-policy\", async () => {\n      await delay(60);\n      return { text: \"Refunds are available within 30 days of purchase.\" };\n    });\n\n    return step.llm(\"generate-answer\", async () => {\n      await delay(80);\n      return `Policy: ${policy.text} (intent: ${plan.intent})`;\n    });\n  },\n  { traceDir: \".\u002F.agent-inspect\" }\n);\n```\n\nRun it, then inspect the trace:\n\n```bash\nnode demo.mjs\nnpx agent-inspect list --dir .\u002F.agent-inspect\nnpx agent-inspect view \u003Crun-id> --dir .\u002F.agent-inspect\nnpx agent-inspect view \u003Crun-id> --dir .\u002F.agent-inspect --summary\n```\n\nFull flow:\n\n```bash\nnpm install agent-inspect\nnode demo.mjs\nnpx agent-inspect list --dir .\u002F.agent-inspect\n```\n\n**Simplified example output** (actual CLI formatting may differ slightly):\n\n```text\nsupport-agent\n✔ plan\n✔ tool:retrieve-policy\n✔ llm:generate-answer\n```\n\nA runnable copy lives in [examples\u002F00-quickstart-demo](examples\u002F00-quickstart-demo\u002FREADME.md).\n\n## What the trace shows\n\nEach run produces a **JSONL** trace: `run_started` \u002F `run_completed`, `step_started` \u002F `step_completed`, with **nested steps**, **tool\u002FLLM** types where you use `step.tool` \u002F `step.llm`, and **durations** on completed steps. Failures are recorded on `step_completed` with `status: \"error\"` (there is no separate `step_failed` event). See [docs\u002FSCHEMA.md](docs\u002FSCHEMA.md).\n\n## Works with structured logs you already have\n\nMany production systems already emit **line-delimited JSON** or text logs with embedded JSON (e.g. via **pino**, **winston**, **log4js**, **NestJS** loggers, job runners, or custom event streams). agent-inspect can turn those into **local grouped timelines\u002Ftrees** without wrapping every function.\n\n```bash\nnpx agent-inspect logs .\u002Fagent.log \\\n  --format json \\\n  --run-id-key requestId \\\n  --event-key event \\\n  --timestamp-key timestamp\n```\n\nWith a reusable ingest config:\n\n```bash\nnpx agent-inspect logs .\u002Fagent.log --config agent-inspect.logs.json\n```\n\n- **JSON logs** are first-class.\n- **log4js-style** lines are **best-effort** when a recoverable JSON payload is present.\n- **No `eval`**, no JavaScript object-literal parsing as a log interchange format.\n- **Flat timeline by default**; nesting when parent relationships are explicit or configured.\n- **Confidence labels** (`explicit`, `correlated`, `heuristic`, `unknown`) describe how attribution was inferred.\n\nMore detail: [docs\u002FLOGS.md](docs\u002FLOGS.md) · [docs\u002FLOG-TO-TREE-QUICKSTART.md](docs\u002FLOG-TO-TREE-QUICKSTART.md).\n\n## CLI at a glance\n\n| Command | Use it for |\n| -------- | ---------- |\n| `list` | Find recent runs |\n| `view` | Inspect one run as a tree |\n| `clean` | Safely remove old trace files |\n| `logs` | Turn existing structured logs into a local tree\u002Ftimeline |\n| `tail` | Watch structured logs while the app runs |\n| `export` | Write Markdown \u002F HTML \u002F OpenInference-compatible JSON \u002F OTLP JSON **locally** |\n| `diff` | Compare two local runs (read-only) |\n\nFull flags and behavior: [docs\u002FCLI.md](docs\u002FCLI.md).\n\n## Real-world workflows\n\n- Debug a **failed tool call** or thrown error in a support or ops agent.\n- See **which step dominated latency** in a multi-step planner or RAG pipeline.\n- **Diff two runs** after a prompt, model, or routing change.\n- Point **`logs`** \u002F **`tail`** at existing job or service logs to get a **local execution view** without shipping data upstream.\n- **Export** a run to Markdown for a PR, postmortem, or internal thread — then review before sharing.\n- Keep traces **on disk** while still using enterprise observability elsewhere.\n\n## What v1.0 stabilizes\n\n**agent-inspect 1.0** stabilizes the **local debugging foundation**:\n\n- Instrument a run with `inspectRun` and `step`\n- Write **local JSONL traces** (`schemaVersion: \"0.1\"` — compatibility retained)\n- Inspect runs with **`list`** and **`view`**\n- Safely remove old trace files with **`clean`**\n\n**Stable APIs:** `inspectRun()`, `step()`, `step.llm()`, `step.tool()`, `observe()`.\n\n**Stable CLI workflows:** `agent-inspect list`, `agent-inspect view`, `agent-inspect clean`.\n\n**Also included in 1.0** as local-first extensions:\n\n- Structured log inspection: **`logs`**\n- Live log tailing: **`tail`**\n- Local exports: **`export`** (Markdown, HTML, OpenInference-compatible JSON, OTLP JSON — files only)\n- Local run comparison: **`diff`**\n- Optional **`@agent-inspect\u002Flangchain`** callback adapter\n- Optional **`@agent-inspect\u002Ftui`** terminal viewer\n- **Fixtures** and **recipes** for deterministic checks and adoption patterns\n\n**Honest boundaries:** programmatic log parsing, export, and diff APIs; LangChain and TUI programmatic surfaces; and OpenInference\u002FOTLP JSON exports are **experimental or compatibility-oriented**. Nothing performs **vendor upload** by default.\n\n## Optional packages\n\n### LangChain callback adapter (`@agent-inspect\u002Flangchain`)\n\nOptional package: official **LangChain.js callbacks** (`BaseCallbackHandler`), **metadata-oriented by default**, **no monkey-patching**, **no vendor sink**. The LangChain adapter is available in 1.0, but its programmatic API remains experimental and may evolve independently of the stable core tracing API.\n\n```bash\npnpm add agent-inspect @agent-inspect\u002Flangchain @langchain\u002Fcore\n```\n\n```ts\nimport { AgentInspectCallback } from \"@agent-inspect\u002Flangchain\";\n\nconst callback = new AgentInspectCallback({\n  runName: \"my-run\",\n  capture: \"metadata-only\",\n});\n\nawait agent.invoke(input, { callbacks: [callback] });\nconst events = callback.getEvents();\n```\n\nSee [examples\u002F08-langchain-adapter](examples\u002F08-langchain-adapter\u002FREADME.md) and [docs\u002FADAPTERS.md](docs\u002FADAPTERS.md).\n\n### TUI viewer (`@agent-inspect\u002Ftui`)\n\nOptional **Ink\u002FReact** package, installed separately. Use with an interactive terminal:\n\n```bash\npnpm add agent-inspect @agent-inspect\u002Ftui\nnpx agent-inspect view \u003Crun-id> --tui\n```\n\nThe TUI is available as a separate optional package; its programmatic API is experimental, while the CLI integration (`view --tui`) is the intended usage. Details: [docs\u002FADAPTERS.md](docs\u002FADAPTERS.md).\n\n## Examples and recipes\n\n| Example | Shows |\n| ------- | ----- |\n| [examples\u002F00-quickstart-demo](examples\u002F00-quickstart-demo\u002FREADME.md) | Fast install-and-try trace |\n| [examples\u002F01-basic](examples\u002F01-basic) | `inspectRun` + `step` |\n| [examples\u002F02-nested-steps](examples\u002F02-nested-steps) | Nested tree |\n| [examples\u002F03-parallel-steps](examples\u002F03-parallel-steps) | Parallel siblings |\n| [examples\u002F04-error-handling](examples\u002F04-error-handling) | Failed steps |\n| [examples\u002F05-observe-wrapper](examples\u002F05-observe-wrapper) | `observe()` |\n| [examples\u002F06-log-to-tree](examples\u002F06-log-to-tree) | `logs` \u002F `tail` |\n| [examples\u002F08-langchain-adapter](examples\u002F08-langchain-adapter\u002FREADME.md) | LangChain callbacks |\n| [examples\u002Frecipes\u002Frag-pipeline](examples\u002Frecipes\u002Frag-pipeline) | RAG-shaped flow |\n| [examples\u002Frecipes\u002Ftool-failure-retry](examples\u002Frecipes\u002Ftool-failure-retry) | Tool failure + retry |\n| [examples\u002Frecipes\u002Fmulti-agent-handoff](examples\u002Frecipes\u002Fmulti-agent-handoff) | Handoff |\n| [examples\u002Frecipes\u002Fproactive-agent-logs](examples\u002Frecipes\u002Fproactive-agent-logs) | Structured logs |\n| [examples\u002Frecipes\u002Fretry-fallback](examples\u002Frecipes\u002Fretry-fallback) | Fallback pattern |\n| [examples\u002Frecipes\u002Fparallel-tools](examples\u002Frecipes\u002Fparallel-tools) | Parallel tools |\n\n**Recipes** are deterministic and require **no external services** by default. Index: [examples\u002FREADME.md](examples\u002FREADME.md), [examples\u002Frecipes\u002FREADME.md](examples\u002Frecipes\u002FREADME.md).\n\n## Security and privacy posture\n\n- **Local files by default** — no upload, no vendor sinks in core workflows.\n- **No API keys** required for core tracing and CLI inspection.\n- **Manual metadata** is user-controlled; traces and exports can contain sensitive data if you put it there.\n- **Review exports** before sharing (especially with richer attribute flags).\n\nSee [SECURITY.md](SECURITY.md).\n\n## agent-inspect comparison\n\nIt can **complement** LangSmith, Langfuse, Braintrust, Phoenix\u002FOpenInference, OpenTelemetry, New Relic, Datadog, and similar platforms — but it does **not** replace their production or eval workflows.\n\nFor a detailed comparison, see [Compare with other tools](docs\u002FCOMPARE.md).\n\n## Documentation\n\n- [Getting started](docs\u002FGETTING-STARTED.md)\n- [API stability & experimental surfaces](docs\u002FAPI.md)\n- [CLI reference](docs\u002FCLI.md)\n- [Schema (`schemaVersion: \"0.1\"`)](docs\u002FSCHEMA.md)\n- [Architecture (links to deeper design notes)](docs\u002FARCHITECTURE.md)\n- [Logs & tail](docs\u002FLOGS.md)\n- [Log-to-tree quickstart](docs\u002FLOG-TO-TREE-QUICKSTART.md)\n- [Exports](docs\u002FEXPORTS.md)\n- [Diff](docs\u002FDIFF.md)\n- [Adapters](docs\u002FADAPTERS.md)\n- [Compare with other tools](docs\u002FCOMPARE.md)\n- [Security](SECURITY.md)\n- [Changelog](CHANGELOG.md)\n- [Known issues](docs\u002FKNOWN-ISSUES.md)\n- [Limitations](docs\u002FLIMITATIONS.md)\n- [Screenshot checklist (planned assets)](docs\u002FSCREENSHOTS.md)\n\n## Development\n\nFrom a clone of this repo:\n\n```bash\npnpm install\npnpm build\npnpm test\npnpm test:all\n```\n\nTo run the CLI from source after a build: `node packages\u002Fcli\u002Fdist\u002Findex.cjs --help`.\n","agent-inspect 是一个用于 TypeScript AI 代理的本地执行树工具。它能够将手动步骤、工具调用、大语言模型调用、结构化日志、失败信息、持续时间和运行元数据转换为可从终端查看的易读执行树，帮助开发者理解 AI 代理在本地运行时的行为。该工具专为 TypeScript\u002FNode.js 开发者设计，适用于需要在本地调试或快速迭代 AI 代理产品的场景，且无需云端上传或第三方服务接入。此外，agent-inspect 支持与现有结构化日志集成，并提供标准对齐的本地导出选项，确保了开发流程中的灵活性和独立性。",2,"2026-06-11 04:05:06","CREATED_QUERY"]