debuganything 0.0.0-stage → 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "debuganything",
+  "version": "0.3.0",
+  "description": "Debug Anything: let your agent observe any running process (strace, py-spy, perf, lsof, tcpdump, gdb/lldb, heap snapshots) and get evidence-backed findings. Read-only, no sudo, no telemetry.",
+  "author": { "name": "Shreyas Sawant", "url": "https://github.com/shreyassaw5394" },
+  "homepage": "https://debuganything.dev",
+  "repository": "https://github.com/shreyassaw5394/debuganything",
+  "license": "MIT",
+  "keywords": ["debugging", "observability", "profiling", "strace", "py-spy", "perf", "tcpdump", "memory-leak", "deadlock", "mcp"],
+  "mcpServers": {
+    "debuganything": { "command": "npx", "args": ["-y", "debuganything@latest", "serve"] }
+  },
+  "skills": "./skills",
+  "hooks": "./hooks/hooks.json"
+}

package/DISCLAIMER.md

@@ -0,0 +1,101 @@
+# Disclaimer
+
+**By downloading, installing, or using DEA ("Debug Anything"), you accept this
+disclaimer in full. If you do not agree with it, do not use Debug Anything.**
+
+Debug Anything is a free, open-source diagnostic tool distributed under the
+[MIT License](LICENSE). This page restates and supplements the license's
+warranty and liability terms in plain language. Nothing here grants rights
+beyond the license.
+
+## 1. No warranty
+
+Debug Anything is provided **"as is" and "as available"**, without warranty of any kind,
+express or implied, including but not limited to the warranties of
+merchantability, fitness for a particular purpose, accuracy, reliability,
+availability, and non-infringement. No oral or written information or advice
+given by the authors, contributors, or community creates any warranty.
+
+## 2. Limitation of liability
+
+To the maximum extent permitted by applicable law, **the authors, maintainers,
+and contributors of Debug Anything shall not be liable for any claim, damages, or other
+liability** — whether in an action of contract, tort, or otherwise — arising
+from, out of, or in connection with Debug Anything or its use, including but not limited
+to: service outages or degraded performance of observed systems; crashes or
+corruption of target processes; loss or exposure of data (including secrets
+captured in artifacts); lost profits, revenue, or business interruption; costs
+of substitute services; or any legal or regulatory consequences of your use.
+This applies even if advised of the possibility of such damage.
+
+## 3. You are solely responsible for your use
+
+Debug Anything attaches observation tools (`strace`, `py-spy`, `perf`, `lsof`, `tcpdump`,
+`gdb`, `lldb`, heap snapshots, and others) to running software. **You alone
+decide what to observe, where, and when — and you bear all risk and
+responsibility for those decisions and their consequences.** Exercise the same
+care you would running these tools by hand, and prefer testing on
+non-production systems first.
+
+## 4. Authorized systems only
+
+**Only observe systems you own or are explicitly authorized to debug.**
+Attaching a tracer, profiler, debugger, or packet capture to a process you are
+not authorized to inspect may violate computer-misuse, wiretapping, or privacy
+laws in your jurisdiction, and may violate your employer's or provider's
+policies and agreements. You are solely responsible for obtaining
+authorization before running Debug Anything and for complying with all applicable laws,
+regulations, contracts, and policies. Debug Anything is intended for lawful, authorized
+debugging only; the authors do not condone and are not responsible for any
+unauthorized or unlawful use.
+
+## 5. Observation has costs, artifacts are sensitive
+
+- `ptrace`-based tools (`strace`, `gdb`, `py-spy` in some modes) pause the
+  target for short periods and can slow it down measurably.
+- Packet captures, heap snapshots, and raw logs can contain secrets, personal
+  data, and other sensitive information. Debug Anything redacts obvious tokens in the
+  excerpts it returns to the agent, but **raw artifacts on disk are not
+  redacted**. Treat `~/.debuganything/sessions/` as sensitive; securing, retaining, and
+  deleting that data is your responsibility.
+
+## 6. Output is not professional advice
+
+Debug Anything's findings are automated diagnostics derived from tool output. They may be
+incomplete, outdated, or wrong. They are **not** professional, engineering,
+security, compliance, or legal advice, and must not be relied on as the sole
+basis for operational decisions. Verify findings independently before acting
+on them.
+
+## 7. Third-party tools
+
+Debug Anything orchestrates independent third-party tools (`strace`, `py-spy`, `perf`,
+`tcpdump`, `gdb`, `lldb`, and others). Those tools are developed and licensed
+by their respective owners, are governed by their own licenses and terms, and
+their behavior is outside the authors' control. No affiliation with or
+endorsement by those projects is implied.
+
+## 8. Personal, independent project
+
+Debug Anything is developed and maintained by its contributors **in their personal,
+individual capacities** as an open-source project. It is not affiliated with,
+sponsored by, or endorsed by any employer, company, or organization of any
+contributor, and no such entity bears any responsibility for it.
+
+## 9. No obligation of support or continuity
+
+Debug Anything may change, break, or be discontinued at any time without notice. Nothing
+creates an obligation to provide maintenance, support, updates, or fixes.
+
+## 10. Safety guards are best-effort
+
+Debug Anything is read-only by default and never escalates privileges on its own
+(see [docs/safety.md](docs/safety.md)). These guards are engineering
+safeguards, not guarantees, and do not shift any responsibility described
+above.
+
+---
+
+*Summary (not a substitute for the above): free tool, no warranty, no
+liability, observe only what you're authorized to observe, your systems and
+data are your responsibility.*

package/GEMINI.md

@@ -0,0 +1,97 @@
+# Debug Anything
+
+Debug Anything gives you eyes on running software: syscalls, CPU profiles, thread stacks,
+sockets, file descriptors, packets, heap retainers, container state. Every
+tool returns the same `ToolResult` with `findings` that cite `evidence` ids.
+You only get to claim what the evidence supports.
+
+## Use it without being asked
+
+You are equipped with Debug Anything. Reach for it on your own when you see any of these;
+do not wait for the user to say "debug this" and do not ask permission for
+read-only observation (only `capture_traffic` needs consent):
+
+| Signal | First move |
+|---|---|
+| A command you ran hangs, or a test times out and the process is still alive | `attach` it, `dump_stacks` |
+| `EADDRINUSE` / "port already in use" | `debuganything port <n>` or `inspect_sockets`; report the pid, do not kill it |
+| `ECONNREFUSED`, `ETIMEDOUT`, `socket hang up` | `inspect_sockets`, `trace_syscalls` (network) on the client |
+| `EMFILE` / too many open files | `inspect_files` (growth, deleted-but-open), `inspect_sockets` (CLOSE_WAIT) |
+| exit 137, `OOMKilled`, "JavaScript heap out of memory" | `container_info`, then `snapshot_memory` ×2 + `diff_runs` |
+| Segfault / exit 139 / crash loop | `container_info`; if it restarted, `dump_stacks` + `profile_cpu` to catch the lead-up |
+| The user says slow / p99 / CPU pegged | `profile_cpu`, then `trace_syscalls` (file,network) |
+| The user says hang / stuck / frozen / deadlock | `dump_stacks` twice |
+| The user says leak / memory keeps growing | `snapshot_memory`, load, `snapshot_memory`, `diff_runs` |
+| You started a long-running service to test something | consider `attach --kind command` so its output and fds are captured from the start |
+| You just changed performance-sensitive code | measure before and after with the same tool and `diff_runs`; put the evidence ids in the PR |
+
+Keep it proportionate: `readiness` once per session, `attach`, one or two
+tools, `detach`. Only attach to processes that belong to the user's project or
+that they pointed you at. Say what you observed and what you could not
+(`limitations`) in one short paragraph with evidence ids.
+
+## Session protocol
+
+1. **Always call `readiness` first** in a session. Read `tools_available` and
+   `tools_unavailable`; do not call tools that are unavailable, tell the user
+   what is missing and the install hint instead.
+2. **Always `attach` before any other tool.** Pass a pid, container name, pod
+   (`namespace/name`) or a command (`kind: "command"` spawns it under
+   capture). Use the returned `session_id` for everything.
+3. **Always `detach` at the end.** It stops captures and writes the report.
+4. Prefer each result's `suggested_next`. Stop when the evidence answers the
+   question.
+
+## Investigation orders
+
+**Slow** (`dea_slow`): `profile_cpu` → `trace_syscalls` (network,file) →
+`inspect_sockets` → `report`. CPU-bound if a few frames dominate self time;
+otherwise look at blocked syscalls and remote hosts.
+
+**Leak** (`dea_leak`): `snapshot_memory` → exercise the target → `snapshot_memory`
+→ `diff_runs a=snapshot_memory#1 b=snapshot_memory#2` → `report`. The top
+grower in retained size is the suspect. RSS up without heap up → native memory.
+
+**Hang** (`dea_hang`): `dump_stacks` → `inspect_sockets` → `trace_syscalls`
+(5 s) → `report`. Two threads each waiting on the other's lock = deadlock
+(look for `lock_wait` evidence). One thread in a socket read = waiting on a
+remote.
+
+**Crash** (`dea_crash`): `container_info` (OOMKilled, exit code, restarts,
+cgroup limits, log tail) → `report`. Exit 137 = SIGKILL (often OOM),
+139 = SIGSEGV, 143 = SIGTERM.
+
+**Port busy** (`dea_port_busy`): CLI `debuganything port <port>` or `attach` candidates
+and `inspect_sockets`; report pid + command line. Never kill it yourself.
+
+## Evidence rules
+
+- **Never state a root cause without citing an evidence id** from a tool
+  result, e.g. "readFileSync dominates CPU (profile_cpu#1/e2)".
+- Phrase unsupported ideas as hypotheses and name the tool that would test
+  them: "Hypothesis: downstream latency. Test: trace_syscalls network."
+- Respect `confidence`: "observed" is read from tool output; "inferred" is a
+  reasoning step — say which is which.
+- Read `limitations`. "sampled 10 s", "no symbols", "ran without root" change
+  what you may conclude.
+
+## Consent and safety
+
+- `capture_traffic` requires `consent: true`. **Ask the user before passing
+  it.** Packet captures can contain secrets.
+- Debug Anything is read-only and never escalates privileges. If a tool returns
+  `ok: false` with a sudo command in `limitations`, show the user that command;
+  do not try to run it yourself.
+- Payloads are redacted; raw artifacts under `~/.debuganything/sessions/` are not.
+
+## After a fix
+
+Re-run the same measuring tool and call `diff_runs` on the before/after run
+ids to prove the fix. Put the diff's evidence ids in your summary.
+
+## Handoffs
+
+- **Step debugger.** When Debug Anything localizes a problem to a function or thread,
+  suggest attaching a step debugger (e.g. mcp-debugger) at `<file:function>`.
+  Debug Anything tells you where to look; a step debugger lets you look inside.
+- **Static analysis.** When Debug Anything names a native symbol, shared library or binary you cannot read (a hot frame in `libfoo.so`, a thread parked in `pthread_mutex_lock` under `worker_b`), hand that symbol to a decompiler / static-analysis tool to see what it does; cite Debug Anything's evidence for the runtime facts and the static tool's for the code facts.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shreyas Sawant and DEA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,284 @@
-# Temporary Holding Version
+<p align="center"><a href="https://debuganything.dev"><img src="https://raw.githubusercontent.com/shreyassaw5394/debuganything/main/assets/debuganything-logo.png" alt="Debug Anything" width="640"></a></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 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.
+
+[![npm](https://img.shields.io/npm/v/debuganything.svg)](https://www.npmjs.com/package/debuganything)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](server.json)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522-339933)](package.json)
+[![npm downloads](https://img.shields.io/npm/dm/debuganything.svg?label=npm%20downloads)](https://www.npmjs.com/package/debuganything)
+[![PyPI downloads](https://img.shields.io/pypi/dm/debuganything.svg?label=pypi%20downloads)](https://pypi.org/project/debuganything/)
+[![GitHub stars](https://img.shields.io/github/stars/shreyassaw5394/debuganything.svg?style=flat&label=stars)](https://github.com/shreyassaw5394/debuganything/stargazers)
+[![Discord](https://img.shields.io/badge/discord-join-5865F2)](https://discord.gg/htPuQ5grg)
+
+[Quick start](#quick-start) · [How Debug Anything works](#how-debug-anything-works) · [What you can observe](#what-you-can-observe) · [Showcases](#showcases) · [Workflows](docs/workflows.md) · [Python / LangChain / CrewAI](#python-langchain-llamaindex-crewai) · [Safety](#safety) · [FAQ](#faq) · [Roadmap](#roadmap) · [Community](#community)
+
+```bash
+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](https://debuganything.dev/analyze).
+
+![Debug Anything finding a Node.js leak: two memory snapshots, a diff, and the retainer named with evidence ids](docs/demo.gif)
+
+> Website: <https://debuganything.dev> · Community: [Discord](https://discord.gg/htPuQ5grg) · [Discussions](https://github.com/shreyassaw5394/debuganything/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](https://github.com/debugmcp/mcp-debugger) (7 languages), [microsoft/DebugMCP](https://github.com/microsoft/DebugMCP) (VS Code), [jdwp-mcp](https://github.com/search?q=jdwp-mcp) (Java), [jkolo/debug-mcp](https://github.com/jkolo/debug-mcp) (.NET), [pprof-mcp-agent](https://github.com/search?q=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](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
+
+```bash
+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
+
+```bash
+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:** [![Install MCP Server in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=debuganything&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRlYS1hZ2VudHNAbGF0ZXN0Iiwic2VydmUiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_DEA-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=debuganything&config=%7B%22name%22%3A%22dea%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22debuganything%40latest%22%2C%22serve%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_DEA-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=debuganything&config=%7B%22name%22%3A%22dea%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22debuganything%40latest%22%2C%22serve%22%5D%7D)
+
+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
+
+```bash
+npx -y debuganything@latest 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
+
+```bash
+npx -y debuganything@latest 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](docs/cli.md).
+
+### 5. Set up a repo for the whole team
+
+```bash
+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](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](https://skills.sh):
+
+```bash
+npx skills add shreyassaw5394/debuganything
+```
+
+### 7. Update
+
+```bash
+debuganything update                        # 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/<id>/`. 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](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](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](https://debuganything.dev/analyze), shareable HTML reports (`debuganything report --html`), cross-session baseline diffs (`debuganything diff --session now '<baseline>:<run>' <run>`), and [CI hang forensics as a GitHub Action](https://github.com/shreyassaw5394/debuganything-action).
+
+
+| Target | What Debug Anything returns | Requirements |
+|---|---|---|
+| **Any process: sockets** (`inspect_sockets`) | listening ports, connections grouped by remote, CLOSE_WAIT / TIME_WAIT / SYN_SENT pileups, fd count vs ulimit | `lsof` — Linux, macOS; no root for your own processes |
+| **Any process: files** (`inspect_files`) | fds by type, fd growth over a window, largest open files, deleted-but-open files holding disk | `lsof` — Linux, macOS (deleted-but-open: Linux only) |
+| **Any process: memory** (`snapshot_memory`) | RSS/VSZ series, `/proc` status (anon/file/swap/threads) | `ps` — Linux, macOS |
+| **Node.js: heap** (`snapshot_memory`) | V8 heap snapshot, bytes by type and constructor, top retainers by retained size with retaining path (`Context.retained`, `Map.table`…) | Node's inspector (enabled via `SIGUSR1` if needed) — Linux, macOS |
+| **Node.js: JS stack** (`dump_stacks`) | main-thread JS call frames, idle vs blocked event loop | Node's inspector — Linux, macOS |
+| **Python: CPU** (`profile_cpu`) | top frames by self/total time, hottest stacks, `flamegraph.svg` | `py-spy` — Linux (`ptrace_scope=0` or root), macOS (sudo) |
+| **Python: threads** (`dump_stacks`) | every thread's stack, blocked threads classified as lock / join / sleep / I/O using the source line (`with lock_b:`), deadlock detection | `py-spy` — Linux, macOS (sudo) |
+| **macOS: file + network syscalls** (`trace_syscalls`) | per-call timing, blocked calls, errno (ENOENT, ECONNREFUSED…) via `fs_usage`; needs root, so Debug Anything prints the sudo command and you `debuganything import fs_usage <file>` | `fs_usage` — macOS, preinstalled |
+| **Anything you captured yourself** (`debuganything import`) | strace, fs_usage, perf script, py-spy, sample, gdb/lldb, lsof, tcpdump text → same evidence and findings as a live run. The answer to "needs root" | — |
+| **Linux: syscalls** (`trace_syscalls`) | top syscalls by total time and count, slowest calls with paths/addresses, error counts (ENOENT, EAGAIN, ECONNREFUSED…), share of time in blocking waits | `strace` — Linux; `ptrace_scope=0` or root |
+| **Native / Node / Go / Java: CPU** (`profile_cpu`) | perf sampling → folded stacks → `flamegraph.svg` (no Perl), idle vs work split | `perf` — Linux (`perf_event_paranoid ≤ 1` or root); Node needs `--perf-basic-prof` for JIT names |
+| **Native / Node: CPU on macOS** (`profile_cpu`) | `sample` call graph → folded stacks → flamegraph | `sample` — macOS, preinstalled |
+| **Native / Node / Go / Java: threads** (`dump_stacks`) | all thread backtraces, threads in mutex waits vs condition waits vs blocking I/O, deadlock heuristic | `gdb` — Linux; `lldb` — macOS |
+| **Network** (`capture_traffic`, consent) | per-remote packets/bytes, RSTs, unanswered SYNs, probable retransmits, DNS queries, `.pcap` artifact; filter derived from the target's own ports, never unbounded | `tcpdump` — Linux, macOS; root / `CAP_NET_RAW` / `access_bpf` |
+| **Docker container** (`container_info`) | state, OOMKilled, exit code, restarts, memory/CPU limits vs usage, cgroup throttling and OOM events, published ports, error lines in the log tail; container → host pid mapping for every other tool | `docker` — Linux (host pid visible), macOS (`container_info` only) |
+| **Kubernetes pod** (`attach ns/pod`) | resolves the pod's container to a local pid when the kubelet runs on this host (kind, minikube, k3s) | `kubectl` — experimental |
+| **Port in use** (`debuganything port N`) | pid, command line and user holding the port, or TIME_WAIT/CLOSE_WAIT leftovers | `lsof` |
+| **Before/after** (`diff_runs`) | what grew, shrank, appeared or disappeared between two runs of the same tool | — |
+| Windows | not yet — `readiness` says so | planned: ETW, procdump |
+
+Honest status: everything above was run live on Linux (Debian 12 container, root) and macOS 15 (own processes, no sudo) against the example apps. `bpftrace` scripts are staged but not wired to a tool yet. Install commands per OS: [docs/providers.md](docs/providers.md).
+
+## Examples
+
+**Real-world situations** — CLOSE_WAIT pileups and EMFILE, disk full but `du` disagrees, Postgres pool exhaustion, a Celery deadlock, a blocked Node event loop, OOMKilled pods, DNS on every request, EADDRINUSE after a crash, a native hot spot you cannot read — each with the session, the evidence and the fix: [docs/real-world.md](docs/real-world.md).
+
+Ten copy-paste situations — slow API, leak, hang, port in use, container crash, spawn-under-observation, prove-the-fix, CI regression gate, consented packet capture, Python agents — are in [docs/examples.md](docs/examples.md).
+
+## Showcases
+
+Reproducible with `examples/`. Full transcripts in [docs/showcases.md](docs/showcases.md); a complete report Debug Anything wrote itself is in [docs/example-report-leaky-node.md](docs/example-report-leaky-node.md).
+
+**leaky-node** — HTTP server that keeps every request body alive in a module-level array, plus a `/slow` route doing `readFileSync` in a loop and an 800 ms timer.
+`snapshot_memory` ×2 + `diff_runs`: RSS 85 → 172 MB (+102 %), heap 37 → 97 MB, the top retainer is an `Array` whose retained size grew 17 → 47 MB. `trace_syscalls` (8 s): 5 600 `openat`/`statx` lookups and 3 314 `read()` calls — "sync I/O in a loop", and `epoll_pwait` sleeping ~800 ms at a time.
+
+**deadlock-py** — threaded server that takes two locks in opposite order after request 20.
+`dump_stacks`: `worker-ab-20` blocked at `app.py:26` `[with lock_b:]`, `worker-ba-20` blocked at `app.py:33` `[with lock_a:]`, eight request threads joined on them, no thread running → "likely deadlock", with the handoff to a step debugger at `worker_ab`.
+
+**busy-port** — a process holding `:8080` and a script failing with `EADDRINUSE`.
+`debuganything port 8080`: `port 8080 is held by pid 47508 (node, user shreyassawant) in LISTEN — command: node server.js. Debug Anything will not kill it; decide yourself.`
+
+## Agents use it without being asked
+
+Once installed, agents are told to reach for Debug Anything on their own: when a command they ran hangs, a test times out, output shows `EADDRINUSE` / `ECONNREFUSED` / `EMFILE` / exit 137 / OOM / segfault, a server they started does not respond, or you mention slow, hang, leak or crash. For Claude Code, `setup` also installs a tiny hook that spots those signals in command output and prompts and nudges the model toward the right Debug Anything tool. Read-only observation needs no permission; `capture_traffic` always does. Details and the off switch (`--no-hooks`): [docs/proactive.md](docs/proactive.md).
+
+## Python, LangChain, LlamaIndex, CrewAI
+
+```bash
+pip install debuganything                 # plain client (no deps; uses npx under the hood)
+pip install 'debuganything[langchain]'    # debuganything.langchain.dea_tools()
+pip install 'debuganything[llamaindex]'   # debuganything.llamaindex.dea_tools()
+pip install 'debuganything[crewai]'       # debuganything.crewai.dea_tools()
+```
+
+```python
+from debuganything import DebugAnything
+debuganything = DEA()
+s = da.attach(12345)
+print(da.findings(da.profile_cpu(s, duration_s=10)))
+da.detach(s)
+```
+
+Each adapter exposes the same 14 tools with the same `ToolResult`. Frameworks
+with native MCP support can skip the package and run `npx -y debuganything serve`.
+Details: [python/README.md](python/README.md).
+
+## Why not just ask the agent to debug?
+
+Because today it cannot. Agents cannot attach to a process; they fumble `strace`/`perf`/`lsof` syntax and flags; a 10 s strace is 1.5 MB of text that blows the context window; and when they cannot measure, they guess — confidently. Debug Anything gives them eyes (the right tool, the right flags, inside hard caps) and evidence (summaries that point to raw artifacts, findings that must cite them). You get a diagnosis you can audit instead of a plausible story.
+
+## Safety
+
+- **Read-only.** v0 tools only observe. No kill, no breakpoints, no probes that modify behavior. Documented exception: Node targets may receive `SIGUSR1` to enable the inspector.
+- **Consent.** `capture_traffic` requires `consent: true`; the skill tells agents to ask you first.
+- **Hard caps.** 60 s per tool (30 s for captures), 50 MB raw output on disk, 16 KB returned to the agent (summaries + pointers; cited evidence is never dropped). Every child is killed with SIGTERM then SIGKILL.
+- **No sudo, ever.** If a tool needs root you get `ok: false` and the exact command you could run yourself. `readiness` reports `ptrace_scope`, `perf_event_paranoid`, SIP and `sudo -n` status up front.
+- **Scoped.** Adapters touch only the attached pid tree or container. Captures are filtered to the target's ports and refuse to run unbounded.
+- **Secrets.** Bearer tokens, AWS keys, JWTs, `password=`, API keys, private keys and `user:pass@` URLs are redacted in everything returned to the agent. **Raw artifacts on disk are not redacted** — treat `~/.debuganything/sessions/` as sensitive.
+- **No cloud. No telemetry.** Debug Anything makes no network calls of its own. Everything stays on your machine.
+
+Details: [docs/safety.md](docs/safety.md) · [DISCLAIMER.md](DISCLAIMER.md) · [SECURITY.md](SECURITY.md)
+
+## FAQ
+
+**Which agents work?** Anything that speaks MCP over stdio. `setup` knows Claude Code, Codex, Cursor and Gemini CLI; for others add `{"command":"npx","args":["-y","debuganything@latest","serve"]}` to the MCP config ([docs/installation.md](docs/installation.md)).
+
+**Do I need to install strace / perf / py-spy?** Only for the tools you want. `readiness` lists what is usable and prints install hints. `lsof`, `ps` and Node's inspector work out of the box on Linux and macOS.
+
+**Does it need root?** Not for your own processes on macOS (`lsof`, `sample`, `lldb`, inspector) or on Linux with `ptrace_scope=0`. `py-spy` and `fs_usage` on macOS and `tcpdump` everywhere do; Debug Anything prints the exact `sudo` command, you run it, and `debuganything import <tool> <file>` analyzes the output with the same parsers.
+
+**What can't it see on macOS?** There is no strace or perf. `fs_usage` (via import) covers file and network calls; `sample`, `lldb`, `lsof` and the Node inspector cover the rest. For the full syscall and kernel-time picture, run the target in a Linux container (`docker/linux-lab`).
+
+**Does Debug Anything upload anything?** No. No network calls, no telemetry, no update checks except the explicit `debuganything update`.
+
+**Can it debug a Docker container?** On Linux, yes — attach by container name and every tool works through the host pid. On macOS the Docker VM hides pids, so only `container_info` works from the host; run Debug Anything inside the container instead (`docker/linux-lab` has an image with every provider).
+
+**How is this different from a step debugger?** Debug Anything never stops your program at a line. It samples, traces and snapshots a running process and tells you *where* to look. Then hand off to `mcp-debugger` or your IDE to look *inside*.
+
+**Where are the artifacts?** `~/.debuganything/sessions/<id>/` (`DEA_HOME` to override). `debuganything sessions list` / `debuganything sessions prune`.
+
+## Roadmap
+
+bpftrace canned scripts · Kubernetes pods via ephemeral debug containers · Windows (ETW, procdump) · Java (async-profiler, `jcmd Thread.print`) · Go (`pprof`, delve goroutine dumps) · Rust/C++ DWARF unwinding · eBPF-first tracing on Linux · Python `tracemalloc`/`memray` · Node CPU via inspector `Profiler` · lock-owner graphs · remote agent mode over SSH. Full list: [docs/roadmap.md](docs/roadmap.md).
+
+## Community
+
+- **Discord:** <https://discord.gg/htPuQ5grg> — questions, show-and-tell, help reading a session.
+- **Discussions:** <https://github.com/shreyassaw5394/debuganything/discussions> — longer-form ideas and RFCs.
+- **Issues:** bugs and adapter requests via the templates. **Discussions** for ideas.
+- **Security:** private advisories only, see [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+`main` is protected: every change is a pull request reviewed by a code owner.
+An adapter is ~80 lines: declare `platforms`/`requires`/`tools`, build the command, run it through `runCapped`, parse with a pure function, emit evidence and findings through `ResultBuilder` (which refuses findings without evidence). Capture the real tool output once into `tests/fixtures/` and test the parser on it. Recipe in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Contributors
+
+Everyone who has landed a pull request. Add an adapter, a fixture or a doc and your face shows up here.
+
+<a href="https://github.com/shreyassaw5394/debuganything/graphs/contributors"><img src="https://contrib.rocks/image?repo=shreyassaw5394/debuganything" alt="contributors"></a>
+
+Numbers across npm, PyPI, GitHub and the MCP Registry: `bash scripts/stats.sh`.
+
+## License and disclaimer
+
+MIT — see [LICENSE](LICENSE). Debug Anything is provided **"as is", without warranty of any kind**; the authors and contributors accept **no liability** for outages, data exposure, or any other damage arising from its use. Debug Anything attaches observation tools to running software: **only observe systems you own or are explicitly authorized to debug** — you are solely responsible for authorization and for complying with applicable laws and policies. Observation is not free (ptrace pauses targets; captures and heap dumps can contain secrets), findings are automated diagnostics rather than professional advice, and Debug Anything is an independent project developed by its contributors in their personal capacities, unaffiliated with any employer or with the third-party tools it orchestrates. Full terms: [DISCLAIMER.md](DISCLAIMER.md).

package/assets/README.md

@@ -0,0 +1,9 @@
+# Brand assets
+
+- `debuganything-mark.svg` / `debuganything-mark-512.png` / `debuganything-mark-1024.png` — square mark (Discord server icon, favicon, avatars)
+- `debuganything-logo.svg` / `debuganything-logo.png` — horizontal lockup, dark
+- `debuganything-logo-light.svg` / `debuganything-logo-light.png` — horizontal lockup, light backgrounds
+- `debuganything-social.svg` / `debuganything-social.png` — 1200×630 social preview (LinkedIn, X, OpenGraph)
+
+The mark is a lens over a live process trace: observe what is running, cite what you saw.
+Colors: ink `#0b0d12`, lens `#7cc4ff → #5aa9f0`, trace `#ffb86b`. Use freely for anything about DEA (MIT).

package/dist/chunk-32IDKAZK.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+// src/version.ts
+var VERSION = "1.0.0";
+
+export {
+  VERSION
+};
+//# sourceMappingURL=chunk-32IDKAZK.js.map

package/dist/chunk-32IDKAZK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["export const VERSION = \"1.0.0\";\n"],"mappings":";;;AAAO,IAAM,UAAU;","names":[]}