CLI for querying AI SDK DevTools generations.json files so your coding agent can inspect Vercel AI SDK requests, responses, tool calls, and usage without flooding context.
aisdk-dtis an independent package and is not affiliated with, endorsed by, or maintained by Vercel.
- 🔎 List, filter, and inspect AI SDK DevTools runs
- ✂️ Extract bounded prompt messages, outputs, tool calls, and token usage
- 🧭 Query raw request, response, chunk, and provider payloads with previews and JSON paths
- ⏱️ Summarize timing for multi-step and nested generations
- 🛡️ Provide an agent skill for safe
generations.jsoninspection workflows
Install the aisdk-dt binary globally:
With pnpm:
pnpm add -g aisdk-dtWith npm:
npm install -g aisdk-dtOr run it without installing:
With pnpm:
pnpx aisdk-dt runs --file .devtools/generations.jsonWith npm:
npx aisdk-dt runs --file .devtools/generations.jsonOr install it locally as a dev dependency:
With pnpm:
pnpm add -D aisdk-dtWith npm:
npm install -D aisdk-dtThis package requires Node.js 20 or newer.
aisdk-dt reads the DevTools generations.json file produced by the Vercel AI SDK.
If you have not enabled DevTools yet, follow the official setup guide first:
After setup, run your app once and confirm a .devtools/generations.json file exists in your project (or note the custom output path you configured).
For most workflows, start with the skill and your preferred coding LLM agent instead of running raw CLI commands yourself.
This repo includes an agent skill in .agents/skills/aisdk-dt-inspector/ for safe inspection of large AI SDK DevTools generation logs without pulling full prompts, raw provider payloads, or streamed chunks into context.
Install the aisdk-dt-inspector skill:
npx skills add taugr/aisdk-dt --skill aisdk-dt-inspectorPoint your agent at the generations.json file and ask it to inspect or summarize a run:
Use $aisdk-dt-inspector to inspect .devtools/generations.json and summarize failed runs from today.
If you installed aisdk-dt globally, update it with the same package manager:
With pnpm:
pnpm add -g aisdk-dt@latestWith npm:
npm install -g aisdk-dt@latestIf you installed it locally in a project:
With pnpm:
pnpm update aisdk-dtWith npm:
npm update aisdk-dtIf you use npx or pnpx, you usually do not need to update anything manually; they resolve the package when run.
Use direct CLI commands when you need manual or scripted inspection.
Point the CLI at a DevTools database:
aisdk-dt runs --file .devtools/generations.json --limit 10Inspect a run:
aisdk-dt run <runId> --file .devtools/generations.json --prettyList its steps:
aisdk-dt steps <runId> --file .devtools/generations.json --textExtract bounded messages and output:
aisdk-dt messages <runId> --file .devtools/generations.json --limit 6 --max-chars 500
aisdk-dt output <stepId> --file .devtools/generations.json --text --max-chars 800Check tool calls and token usage:
aisdk-dt tools <runOrStepId> --file .devtools/generations.json
aisdk-dt usage <runOrStepId> --file .devtools/generations.jsonIf you run commands from the project that produced the file, --file defaults to .devtools/generations.json.
Want a concrete, end-to-end demo? Start with this first example:
examples/simple-chatbot: a Next.js chatbot with AI SDK tool calls, AI SDK DevTools capture, andaisdk-dtinspection commands.
Global options:
--file <path>: path togenerations.json; defaults to.devtools/generations.json--max-file-bytes <number>: refuse unexpectedly large database files; defaults to 100 MiB--max-output-chars <number>: bound total output; minimum 256 and default 32,000 characters unless a command uses--full--pretty: pretty-print JSON output--text: render compact human-readable output where supported--version: report the installed package version
List recent runs:
aisdk-dt runsSelect the newest run ID for a script:
RUN_ID=$(aisdk-dt runs --limit 1 --json-path 'runs[0].id' --text)Useful runs filters:
--limit <number>and--offset <number>--allto include child runs--childrento include child run IDs--errorsfor failed runs--in-progressfor unfinished runs--model <model>,--provider <provider>, and--function <functionId>--since <iso>and--until <iso>--json-path <path>to select a field from the result
Show compact run detail:
aisdk-dt run <runId>Use --include-children for nested runs and --timeline for trace spans.
Inspect steps:
aisdk-dt steps <runId>
aisdk-dt step <stepId>step supports --section input, output, config, usage, raw, or all. Use --field <field> and --json-path <path> when you need a narrow raw field.
Extract prompt messages and model output:
aisdk-dt messages <runId> --limit 6 --max-chars 500
aisdk-dt output <stepId> --text --max-chars 800messages reconstructs a deterministic transcript from cumulative prompts and
can filter by --role and --parts. Supported parts include attachments and
unknown, so newer AI SDK content remains inspectable without exposing binary
payloads. output can include --text, --reasoning, and --tools.
Query tools and usage:
aisdk-dt tools <runOrStepId>
aisdk-dt usage <runOrStepId>tools includes terminal unpaired calls when a model step finishes with
tool-calls and no later tool result is present.
Query raw payloads only when the semantic commands do not answer the question:
aisdk-dt raw <stepId> --request --json-path 'model'
aisdk-dt raw <stepId> --response --json-path 'content[0]' --max-chars 800Raw selectors:
--request--response--chunks--provider--ai-sdk
Emit timeline spans:
aisdk-dt timeline <runId>Timeline content is omitted by default. Add --include-content --max-chars 500
for bounded text/reasoning or use --full only for deliberate local access.
Default JSON is structurally bounded: long strings become
{"preview":"...","truncated":true,"chars":1234}, long arrays include omitted
item counts, and total output is capped by --max-output-chars. A --full
option bypasses the total cap only on commands that explicitly offer it.
runs, steps, usage, and the default timeline avoid full prompt or raw
payload content. messages, output, tools, events, raw,
timeline --include-content, and any --full option can expose sensitive local
data. Treat generated output as private unless it has been reviewed.
Start with bounded semantic commands:
aisdk-dt runs --limit 10 --file <path>
aisdk-dt messages <runId> --limit 6 --max-chars 500 --file <path>
aisdk-dt steps <runId> --file <path>
aisdk-dt output <stepId> --max-chars 800 --file <path>Use raw data deliberately:
- Prefer
messages,steps,output,tools, andusagebeforeraw - Use
--max-charswhenever output may include prompts, reasoning, tool arguments, tool results, raw requests, raw responses, or raw chunks - Use
raw --json-pathbeforeraw --full - When working outside the project that produced the file, pass
--file /absolute/path/to/generations.json - Do not copy sensitive prompt, request, response, or provider payload content into reports unles 6A02 s the user explicitly asks for it
pnpm install
pnpm run test
pnpm run build
pnpm run test:packageSee the full documentation for compatibility, troubleshooting, and development benchmarks.
Upgrading from 0.1? Review the 0.2 migration guide.