# Debug Runs

Find and read the agent chat runs behind a run id, a user's email, or an object id or...

- Repository: https://github.com/BuilderIO/agent-native (7579 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add BuilderIO/agent-native --skill debug-runs -g -a claude-code -y`
Codex: `npx skills add BuilderIO/agent-native --skill debug-runs -g -a codex -y`
Cursor: `npx skills add BuilderIO/agent-native --skill debug-runs -g -a cursor -y`
Gemini CLI: `npx skills add BuilderIO/agent-native --skill debug-runs -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add BuilderIO/agent-native`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

```bash
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 |
| Email | `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, and `runs[]` 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

```bash
pnpm exec tsx scripts/debug-runs.ts show <runId | threadId> [--app NAME]
```

The rest: https://github.com/BuilderIO/agent-native/blob/HEAD/.agents/skills/debug-runs/SKILL.md