Debug Agent
https://github.com/millionco/debug-agent- Category
- AI Agents
- Rank
- No. 1069Tools index
- Pricing
- Open Source
- Type
- AGENT
- Builder
- millionco
- GitHub
- 303 stars
- Date
About
Drop-in debugging skill for AI coding agents — adds systematic investigation, root-cause analysis, and verification.
What it does
Debug Agent turns a bug report into an evidence loop. The agent forms hypotheses, adds lightweight NDJSON logging, asks you to reproduce the failure, and uses the resulting runtime trace to accept or reject each explanation. It then applies a supported fix and checks the result.
Why it's ranked here
The workflow is unusually concrete for an agent skill. It requires observable evidence before changing code, supports local and remote log collection, and works across several coding agents. The browser package broadens its reach to UI failures. Security and privacy choices around log ingestion deserve attention.
What's good
Installation detects compatible agents and creates a shared skill with links or copies for each target. Session-specific logs keep investigations separated. Duplicate identifiers prevent repeated entries from polluting a trace. The local server can reuse a healthy existing process, while browser helpers support snapshots, diffs, multiple engines, cookies, and Chrome discovery.
Tradeoffs
The method depends on reproducing the bug after instrumentation, so intermittent failures may still stall progress. Local ingestion allows requests from any origin and exposes no authentication in the supplied server implementation. The command line silently contacts a hosted version endpoint at startup. Log deletion is immediate, and duplicate tracking resets after its fixed capacity is reached.
How to use it well
Use it when an AI coding agent faces a reproducible runtime failure and ordinary source inspection leaves several plausible causes. Let it instrument narrowly, reproduce the exact symptom, inspect the trace, then verify the correction. It fits Claude Code, Codex, Cursor, and other detected skill agents. It does not replace production monitoring, alerting, or investigation of failures you cannot reproduce.
Technical notes+
packages/debug-agent/src/cli.ts exposes serve, init, and remote commands and sends a best-effort version request on startup. packages/debug-agent/src/init.ts uses agent-install to detect targets and install the canonical skill by symlink or copy. packages/debug-agent/src/server.ts creates a Node HTTP ingest server bound to 127.0.0.1 by default, writes per-session NDJSON files synchronously, supports GET, POST, DELETE, and OPTIONS, reuses a live server lock, and deduplicates up to MAX_DEDUP_ENTRIES. packages/debug-agent-remote/src/index.ts implements remote sessions with a Cloudflare Durable Object binding and a streaming route. packages/debug-agent-browser/src/index.ts exports Playwright-oriented browser control, Chrome discovery and launch helpers, snapshots, typed errors, and diffSnapshots; packages/debug-agent-browser/src/diff.ts implements a line-based Myers diff. packages/debug-agent/vite.config.ts builds ESM and declarations for Node 18, while packages/debug-agent-browser/vite.config.ts targets Node 22.
Observed
- License
- MIT
- Primary language
- TypeScript
- Install surface
- Installed through npx debug-agent@latest init; detected agent skills can use symlinks or copies.
- Interfaces
- Command-line tool, ESM library exports, local HTTP ingest server, and remote HTTP worker.
- Agent support
- README names Claude Code, Codex, and Cursor; installation also detects compatible skill agents.
- Runtime and packaging
- Private pnpm monorepo using ESM and Vite Plus; root engines require Node 22 or newer and pnpm 10 or newer.
- Browser support
- Browser library uses Playwright types and declares Chromium, WebKit, and Firefox engines.
Read from README.md, package.json, packages/debug-agent/vite.config.ts, packages/debug-agent-browser/vite.config.ts, packages/debug-agent/src/cli.ts, packages/debug-agent/src/init.ts, packages/debug-agent/src/index.ts, packages/debug-agent/src/server.ts, packages/debug-agent/src/agents.ts, packages/debug-agent/src/constants.ts, packages/debug-agent-remote/src/index.ts, packages/debug-agent-browser/src/diff.ts, packages/debug-agent-remote/src/env.d.ts, packages/debug-agent-browser/src/index.ts, packages/debug-agent-browser/src/types.ts.
What it can do
Perform systematic investigation of code issues
Buggy code or error reports → Structured investigation findings
Conduct root-cause analysis of software bugs
Code with identified issues → Root cause identification and explanation
Verify bug fixes and code changes
Modified code and proposed fixes → Verification results and validation status
Integrate debugging capabilities into AI coding agents
AI coding agent system → Enhanced agent with debugging skills
Generate debugging strategies and methodologies
Problem description and code context → Step-by-step debugging approach
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.