Debug Runs
Find and read the agent chat runs behind a run id, a user's email, or an object id or...
Install
npx skills add BuilderIO/agent-native --skill debug-runs -g -a claude-code -y- Repository
- BuilderIO/agent-native7.6k
- Category
- Design
- Updated
- 3d ago
- License
- MIT
- Context cost
- Lightabout 1,042 tokens
- Runs scripts
- No, instructions only
What it does
Find and read the agent chat runs behind a run id, a user's email, or an object id or link (deck, design, dashboard, document, plan, recording, …) in any app, then work out what failed or why the object looks the way it does. Use when someone reports a broken chat, a failed run, or a bad result and gives you any of those instead of a thread.
Debug Runs
scripts/debug-runs.ts reads production app databases (read-only, one
transaction per query) and turns a run id, email, or object id into the chats
and runs that touched it, with the full conversation.
It needs <APP>_DATABASE_URL entries in the repo-root .env or
DATABASE_URL in templates/<app>/.env. A worktree without its own .env
falls back to the main checkout's. An app whose credentials fail shows up as an error
entry; it was not searched, which is not the same as "nothing found".
1. Find the runs
pnpm exec tsx scripts/debug-runs.ts find <input> [--app NAME] [--days 30] [--limit 20]
| Input | Example | How it is matched |
|---|---|---|
| Run id | run-1700000000000-example | live agent_runs/traces, else the thread active at the timestamp inside the id |
user@example.com | threads they own, plus their MCP/A2A calls | |
| Object link | https://slides.agent-native.com/deck/EXAMPLE_deck1 | app from the host, id from the path |
| Bare object id | EXAMPLE_design1 | every app: thread scope, owner lookup, owner's threads, audit inputs |
Prefer the link over a bare id: it searches one app and also scans that app's
audit log even when the object was deleted. --app does the same for a bare
id.
Each results[] entry is one app:
owners: the table the object lives in and its owner.threads[]:matchedBy, title, owner, scope, andruns[]with status, error, model, and timing.externalAgentSessions: calls from Claude Code, Codex, ChatGPT, and other MCP/A2A clients, grouped by client with 30-minute gaps. Their conversation lives in that client; only the calls reached us.uiSessions: audited UI edits to the object outside any chat.auditError: the audit scan timed out; rerun with a smaller--days.
2. Read a thread
pnpm exec tsx scripts/debug-runs.ts show <runId | threadId> [--app NAME]
