Debug Anything · open source · MIT

Your AI agent can write the code.
Now it can see it run.

When your app is slow, stuck, crashing or eating memory, your AI agent used to read the code and guess. With DEA it looks inside the running app, measures what is actually happening, and shows you the proof. One command to install. No terminal skills needed.

$npx dea-agents setup

Works with Claude Code, Cursor, Codex, Gemini CLI and anything that speaks MCP · Python: pip install dea-agents

dea — real session, replayed
In plain English

You say what's wrong. Your agent goes and looks.

🗣️

1. You say it, however you say it

“It's slow after a while.” “It just freezes.” “Memory keeps going up.” “Port already in use.” “The container keeps dying.”

🔍

2. The agent looks inside the running app

Not the code on screen, the program actually running. DEA uses the same tools senior engineers use, drives them for the agent, and keeps it safe: it only watches, never changes anything.

🧾

3. You get the cause, with a receipt

“This list grows and is never emptied.” “This function uses 58% of the CPU.” “Two threads are waiting on each other.” Every sentence points at the measurement behind it, so it can't make things up.

Then it fixes the code the way it already can, measures again, and shows the before/after. That is the whole loop.

How it sees

The agent asks. DEA measures. Every claim points at proof.

The agent never touches a tool directly. DEA picks the right one, runs it inside hard limits, keeps the raw output as an artifact, and returns a short structured result.

Agent"it's slow" DEAattach · cap · parseredact · cite strace · syscalls py-spy · perf · CPU gdb · lldb · stacks lsof · tcpdump · net heap · docker Evidencee1 e2 e3 → artifactson disk, auditable Findingmust cite idsobserved / inferred+ limitations
⏱ 60 s cap per tool📦 50 MB raw cap📨 16 KB to the agent🔒 read-only, no sudo, no network
40 seconds

A memory leak, found and named.

Two snapshots, a diff, and the retainer: Array retains 50 MB via Context.retained, the module-level array in server.js. Real output, no edits.

Real-world situations

The 3 am incidents, with the session that solves each.

Numbers from our own reproductions are real; the rest show the shape of the evidence. Every finding carries its evidence ids.

Full write-ups with the fix and how to prove it: real-world.md · 10 copy-paste examples

The rule

No evidence, no claim.

A finding without evidence ids is rejected by the schema before it ever reaches the agent. Hover the chain.

Finding

HIGHlikely deadlock: 2 threads blocked acquiring locks, none running
[inferred; e14, e1]
→

Evidence

e14 lock_wait  worker-ab-20 at worker_ab (app.py:38) [with lock_b:]
e1  stack_summary  64 threads: 0 active
→

Artifact

~/.dea/sessions/…/artifacts/
  pyspy-dump.txt  (raw, 6.3 KB)
open it. same bytes the agent saw.
observed = read straight off the tool. inferred = a reasoning step, labeled as such. limitations = what it could not see ("sampled 10 s", "no root"). That is what makes an answer auditable instead of trusted.
Workflow

From one laptop to the whole team in a week.

One command per developer, one command per repo, evidence in pull requests, a gate in CI. Nothing to host.

0

You

Register with your agent. Ask it something about a running process.

npx dea-agents setup
1

Your repo

Commit three files; every teammate's agent gets DEA and the rule for when to use it.

dea init
2

Pull requests

Perf and bug fixes carry run ids. Reviewers open the artifact instead of asking "did you measure?"

dea diff profile_cpu#2 profile_cpu#3
3

CI

Smoke test under two snapshots; fail the job if RSS grows.

dea diff … --json | jq -e …
4

Containers

Linux hosts attach by container name. Kubernetes via an ephemeral debug container.

kubectl debug … -- dea why 1
5

On-call agent

A Python agent reacts to the alert, measures, posts findings with the report path.

pip install dea-agents

Day-by-day guide: workflows.md

Unprompted

You stop asking. The agent goes to look.

claude code
[DEA] The last command's output shows a runtime problem signal.
port_busy (“EADDRINUSE :::3000”): run dea port 3000; never kill it blindly.

The skill and the MCP instructions tell the agent to attach and measure on these signals. In Claude Code, a 40 ms hook spots them in command output and prompts, and nudges the model toward the right tool. Read-only observation needs no permission; packet capture always does.

EADDRINUSEECONNREFUSEDEMFILEexit 137OOMKilledSIGSEGVtest timeout"it hangs""it's slow""memory keeps growing"after a perf change

How it works, and the off switch

What you can observe

The tools SREs trust. Driven by the agent.

Sockets & files

Listening ports, connections by remote, CLOSE_WAIT pileups, fd growth, deleted-but-open files.

lsof · Linux, macOS · no root

Node.js heap

Heap snapshot, exact top retainers with the retaining path, JS main-thread stack.

inspector · built in

Python

CPU flamegraph, every thread's stack, lock / join / sleep / I/O classification from source lines, deadlocks.

py-spy

Linux syscalls

Top syscalls by time, slowest calls with paths and addresses, error counts, blocking share.

strace

Native · Go · Java

perf or sample flamegraphs; gdb / lldb thread dumps with mutex vs idle classification.

perf, gdb · sample, lldb

Network

Per-remote bytes, RSTs, unanswered SYNs, retransmits, DNS, .pcap. Filter scoped to the target.

tcpdump · consent

Docker

OOM kills, exit codes, restarts, limits vs usage, cgroup throttling, log tail.

docker

Captured it yourself?

Needs root? DEA prints the sudo command; you run it and dea import the file. strace, fs_usage, perf, py-spy, sample, gdb/lldb, lsof, tcpdump.

dea import · macOS trace via fs_usage

Before / after

Diff any two runs: what grew, appeared, disappeared. Proof for the PR.

diff_runs
Everywhere your agent is

One line, any agent.

MCP · Claude Code, Cursor, Codex, Gemini CLI

npx dea-agents setup

Your repo, your whole team

dea init   # commit .mcp.json, .cursor/mcp.json, AGENTS.md

No agent? One command

dea why 12345 --symptom slow

Agent skill

npx skills add shreyassaw5394/dea

Python · LangChain · LlamaIndex · CrewAI

pip install 'dea-agents[langchain]'
from dea_agents.langchain import dea_tools

Claude Code plugin · Gemini extension

/plugin marketplace add shreyassaw5394/dea
/plugin install dea@dea
gemini extensions install https://github.com/shreyassaw5394/dea

Any MCP client

{"command":"npx","args":["-y","dea-agents@latest","serve"]}
Safety

It only looks.

Read-onlyNever kills, signals, patches or sets breakpoints.
No sudo, everNeeds root? You get the exact command, not an escalation.
Hard caps60 s per tool, 50 MB raw, 16 KB to the agent.
ConsentPacket capture needs an explicit yes, every time.
RedactedTokens, keys, passwords scrubbed from what the agent sees.
Local onlyNo cloud, no telemetry, no update checks.

docs/safety.md · Only observe systems you are authorized to debug.

Community

Built in the open. Numbers live.

Top contributors

Land a pull request (an adapter, a fixture, a doc) and you appear here automatically.

loading from GitHub…