Debuganything

Debug Anything

Observe any running process. No breakpoints, no restarts, no instrumentation.

One MCP server and CLI that gives any coding agent — Claude Code, Codex, Cursor, Gemini CLI — eyes on running software: syscalls, CPU flamegraphs, thread stacks, sockets and file descriptors, packets, heap retainers, container state. Battle-tested local tools (strace, py-spy, perf, lsof, tcpdump, gdb/lldb, Node's inspector) do the observing; Debug Anything turns their output into structured evidence an agent can reason about and a human can audit.

Quick start · How Debug Anything works · What you can observe · Showcases · Workflows · Python / LangChain / CrewAI · Safety · FAQ · Roadmap · Community

npx debuganything why <pid>       # or: why api-container --symptom leak

One command against any pid, container or pod: attach → the right tools for the symptom (slow / leak / hang / crash / triage) → ranked findings, every one citing evidence ids → detach. Hooking it to your agent instead: npx debuganything setup. No install at all? Paste tool output in the browser.

Website: https://debuganything.dev · Community: Discord · Discussions · Only ever download Debug Anything from this repo, the debuganything npm/PyPI packages, or that site.

Where Debug Anything sits

Step-through debuggers over MCP already exist and are good: debugmcp/mcp-debugger (7 languages), microsoft/DebugMCP (VS Code), jdwp-mcp (Java), jkolo/debug-mcp (.NET), pprof-mcp-agent (Go). They need a debug adapter, a debug port, or an instrumented/restarted target, and they assume you already know where to put the breakpoint.

Debug Anything is the layer before that: black-box observation of any pid, container or pod with zero instrumentation, turned into evidence.

mcp-debugger is for when you know where to put the breakpoint. Debug Anything is for when you don't.

They are complementary. When Debug Anything localizes a problem to a function or thread, its suggested_next includes the handoff: *"attach a step debugger (e.g. mcp-debugger) at file:function"* — and, for native symbols, *"decompile parse_frame in libfoo.so with your static-analysis tool"*. More situations: docs/examples.md.

Why this exists

Software is written once and runs forever, and most engineering pain is in the running part. Agents just got very good at the writing part. They are still blind to the running part — an agent can read every line of your code and still cannot tell you why the process in front of it is eating 4 GB. Observability vendors solved this for humans with dashboards. Nobody has solved it for agents.

Debug Anything is a sensory layer for software agents. The plan:

1. Local — one MCP, one laptop, one process. Evidence over guesses. *(this release)*
2. Anywhere — containers, pods, remote hosts over SSH, fleets. Same tools, same contracts.
3. Always-on — agents that watch production, notice the regression at 3 am, attach, diagnose, and open the PR with the flamegraph attached, paging a human only with proof.
4. The standard — the evidence contract (findings must cite evidence) becomes how any tool reports to any agent, so a human can audit an agent's claim in one click.

Every interface is designed so step-1 code survives to step 4: targets are abstract (pid today, container and pod now, host next), adapters are pluggable, and every result has the same evidence schema. Nothing assumes localhost.

Quick start

0. The one-liner

npx debuganything why <pid|container|pod>     # symptom flags: --symptom slow|leak|hang|crash

why is the whole product in one command: it runs readiness, attaches, picks the right observation battery for the symptom, and prints ranked findings with the evidence ids to back them. Everything below is that same engine, wired into your agent.

1. Set up your agent

npx debuganything setup

Detects Claude Code, Codex, Cursor and Gemini CLI, shows the exact config entry it will add, backs up the file, writes it, and installs the debug-anything skill where the agent supports skills. Then restart your agent.

One-click installs:

Claude Code plugin: /plugin marketplace add shreyassaw5394/debuganything then /plugin install debuganything@debuganything · Gemini CLI: gemini extensions install https://github.com/shreyassaw5394/debuganything · Skill: npx skills add shreyassaw5394/debuganything

2. Ask your agent

*My API gets slow after a few minutes — attach to it and tell me why, with evidence.*

*Something is holding port 8080. Who?*

*This Python worker hangs after ~20 requests. Find out what it is waiting on.*

The agent calls readiness, attach, then the right tools, and answers with findings that cite evidence ids — or tells you what it could not observe and why.

3. No agent? One command

npx -y debuganything@1.1.0 why 12345 --symptom leak     # or: slow | hang | crash | triage

debuganything why my-container --symptom crash debuganything why -- node server.js # spawn it under observation

why attaches, runs the right tools for the symptom, prints each result, and ends with a ranked summary and the report path. Skips tools readiness says you cannot run instead of failing.

4. Or step by step

npx -y debuganything@1.1.0 readiness

debuganything ps --filter node S=$(debuganything attach 12345 --json | jq -r .session_id) debuganything profile --session $S --duration 10 debuganything sockets --session $S debuganything report --session $S --md report.md debuganything detach --session $S debuganything port 8080 # who holds a port — no session needed

Every command takes --json and prints the exact ToolResult. See docs/cli.md.

5. Set up a repo for the whole team

cd my-project && debuganything init     # .mcp.json + .cursor/mcp.json + a rule in AGENTS.md/CLAUDE.md — commit them

Every teammate's Claude Code and Cursor now gets Debug Anything from the repo, with the rule telling agents when to use it. Adoption flow day by day: docs/workflows.md.

6. Install as an agent skill

The debug-anything skill (investigation orders, evidence rules, consent etiquette) is installed by setup for Claude Code, Codex and Gemini CLI, and is also available through skills.sh:

A second skill, inspect-product, is for auditing a whole product rather than chasing one bug: the agent walks your running app as a brand-new user, observes the runtime underneath it with these tools, and returns ranked findings that each carry a reproduction and proof. Ask it to "review the product and tell me what to fix before launch". Both skills install with npx debuganything setup.

npx skills add shreyassaw5394/debuganything

7. Update

debuganything update                        # re-pins agent configs; or: npx debuganything@latest setup

How Debug Anything works

agent ──MCP──▶ Debug Anything server ──▶ dispatcher ──▶ adapter (strace | py-spy | perf | lsof | tcpdump | gdb/lldb | inspector | docker)

│ │ build command → run with caps → write raw artifact → parse → aggregate ▼ ▼ ToolResult { findings[] ──cite──▶ evidence[] ──point──▶ artifacts[] } + limitations + suggested_next

• Sessions. attach resolves a target (pid, container, pod, or a command spawned under capture) into ~/.debuganything/sessions/ /. Every tool result is saved as a run (profile_cpu#2), so diff_runs can compare before/after and report can assemble the whole investigation.
• Evidence contract. A Finding without evidence_ids is rejected by the schema. confidence: "inferred" is allowed but must be stated. Agents only get to claim what the evidence supports. Full schemas: docs/mcp-contracts.md.
• Adapters. Each declares platforms, required binaries and the tools it serves; readiness computes what works on this machine. Parsers are pure functions tested on real captured output. Adding one takes ~80 lines: CONTRIBUTING.md.
• Prompts. dea_slow, dea_leak, dea_hang, dea_crash, dea_port_busy are guided investigations: the order of tools, what to look for, and the rule to never state a cause without an evidence id.

What you can observe

New in 0.4: Java thread dumps (jstack, live or imported), Go goroutine dumps, a paste-in browser analyzer, shareable HTML reports (debuganything report --html), cross-session baseline diffs (debuganything diff --session now ' : ' ), and CI hang forensics as a GitHub Action.

| Any process: files (inspect_files) | fds by type, fd growth ove