{"_id":"@adamancyzhang/agent-go-debugger","_rev":"2-ae41a07897928e57c0d4ab0e8dc70e15","name":"@adamancyzhang/agent-go-debugger","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@adamancyzhang/agent-go-debugger","version":"0.1.0","keywords":["go","golang","dlv","delve","debugger","breakpoint","remote-debugging","cli","agent"],"license":"MIT","_id":"@adamancyzhang/agent-go-debugger@0.1.0","maintainers":[{"name":"adamancyzhang","email":"adamancyzhang@163.com"}],"homepage":"https://github.com/adamancyzhang/agent-go-debugger#readme","bugs":{"url":"https://github.com/adamancyzhang/agent-go-debugger/issues"},"bin":{"agent-go-debugger":"bin/agent-go-debugger.mjs"},"dist":{"shasum":"28584033dd7977598cb1645f7156feacb25eb316","tarball":"https://registry.npmjs.org/@adamancyzhang/agent-go-debugger/-/agent-go-debugger-0.1.0.tgz","fileCount":5,"integrity":"sha512-1z6e/sZCFbQgV6xx4HTeFtMXqbiWglV4vTYFe7tpWctctpwd3JeXu3HM4XtIw275o2le7dIsTTDnSjLsSvvUCg==","signatures":[{"sig":"MEUCIHGsTmwLsY6HLDATrzatAM4oRC0Z/c0i5bLxfk5nRBKqAiEA+1DByRCkgMTrcr+VOxDgmQmXjY5ScuZcCJyOy6QvGqY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19136},"type":"module","engines":{"node":">=14"},"gitHead":"33605ccc5a63f61ce337c91abb6186705fe7037b","scripts":{"test":"bash tests/e2e_sample.sh","build":"node scripts/build.js","deploy":"bash scripts/publish.sh","check-skill":"bash scripts/check-skill.sh"},"_npmUser":{"name":"adamancyzhang","email":"adamancyzhang@163.com"},"repository":{"url":"git+https://github.com/adamancyzhang/agent-go-debugger.git","type":"git"},"_npmVersion":"11.19.0","description":"Remote debugging CLI for Go targets via Delve headless — breakpoints, stepping, goroutines, stack/locals/eval for AI agents. Self-contained binaries per platform; no Go toolchain needed.","directories":{},"_nodeVersion":"22.21.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"optionalDependencies":{"@adamancyzhang/agent-go-debugger-linux-x64":"0.1.0","@adamancyzhang/agent-go-debugger-win32-x64":"0.1.0","@adamancyzhang/agent-go-debugger-darwin-x64":"0.1.0","@adamancyzhang/agent-go-debugger-linux-arm64":"0.1.0","@adamancyzhang/agent-go-debugger-darwin-arm64":"0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-go-debugger_0.1.0_1788846304907_0.6763184038235306","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@adamancyzhang/agent-go-debugger","version":"0.1.1","description":"Remote debugging CLI for Go targets via Delve headless — breakpoints, stepping, goroutines, stack/locals/eval for AI agents. Self-contained binaries per platform; no Go toolchain needed.","bin":{"agent-go-debugger":"bin/agent-go-debugger.mjs"},"engines":{"node":">=14"},"repository":{"type":"git","url":"git+https://github.com/adamancyzhang/agent-go-debugger.git"},"license":"MIT","keywords":["go","golang","dlv","delve","debugger","breakpoint","remote-debugging","cli","agent"],"optionalDependencies":{"@adamancyzhang/agent-go-debugger-darwin-arm64":"0.1.1","@adamancyzhang/agent-go-debugger-darwin-x64":"0.1.1","@adamancyzhang/agent-go-debugger-linux-arm64":"0.1.1","@adamancyzhang/agent-go-debugger-linux-x64":"0.1.1","@adamancyzhang/agent-go-debugger-win32-x64":"0.1.1"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"build":"node scripts/build.js","check-skill":"bash scripts/check-skill.sh","test":"bash tests/e2e_sample.sh","deploy":"bash scripts/publish.sh"},"type":"module","gitHead":"e41765b2214b376d0fc3c77865e297a7c22f1549","_id":"@adamancyzhang/agent-go-debugger@0.1.1","bugs":{"url":"https://github.com/adamancyzhang/agent-go-debugger/issues"},"homepage":"https://github.com/adamancyzhang/agent-go-debugger#readme","_nodeVersion":"22.21.1","_npmVersion":"11.19.0","dist":{"integrity":"sha512-tlUyjsgJUv6aZPgpoV0gFrr68L9/uUXPOwwvn+Jk7Mpk4wjcwIbdDALy57PhU8LC/Sio7iownWFN4MJngWP4mw==","shasum":"e40c189539c2e9effec3d50e38369153ff48f5e9","tarball":"https://registry.npmjs.org/@adamancyzhang/agent-go-debugger/-/agent-go-debugger-0.1.1.tgz","fileCount":5,"unpackedSize":19055,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDmKJb8FopdPdKo+Sx2HXZD486xetGK22nu0+joWkL1swIhAKnLJeJtQgeoDGNCL7nsXey//VBALO6/a4i4gZWExAgU"}]},"_npmUser":{"name":"adamancyzhang","email":"adamancyzhang@163.com"},"directories":{},"maintainers":[{"name":"adamancyzhang","email":"adamancyzhang@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-go-debugger_0.1.1_1788854888745_0.2524925923467296"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-08T05:45:04.686Z","modified":"2026-09-08T08:08:09.331Z","0.1.0":"2026-09-08T05:45:05.064Z","0.1.1":"2026-09-08T08:08:08.889Z"},"bugs":{"url":"https://github.com/adamancyzhang/agent-go-debugger/issues"},"license":"MIT","homepage":"https://github.com/adamancyzhang/agent-go-debugger#readme","keywords":["go","golang","dlv","delve","debugger","breakpoint","remote-debugging","cli","agent"],"repository":{"type":"git","url":"git+https://github.com/adamancyzhang/agent-go-debugger.git"},"description":"Remote debugging CLI for Go targets via Delve headless — breakpoints, stepping, goroutines, stack/locals/eval for AI agents. Self-contained binaries per platform; no Go toolchain needed.","maintainers":[{"name":"adamancyzhang","email":"adamancyzhang@163.com"}],"readme":"# agent-go-debugger\n\nRemote debugging CLI for **Go** processes, for AI agents and terminals.\nThe sibling of [agent-py-debugger](../agent-py-debugger) and\n[agent-java-debugger](../agent-java-debugger): attach to a Go target over a\nTCP debug port and drive it — breakpoints, stepping, goroutines, stack,\nlocals, expression evaluation — emitting machine-readable JSON events\n(`--json`) for agents.\n\nThe CLI **never manages the target process**. It connects over JSON-RPC to a\nDelve headless server (`dlv --headless`) that runs next to the target —\nexactly like agent-java-debugger attaches to a JDWP port.\n\n```\n[target machine]\n  dlv exec ./app --headless --listen=:2345 --api-version=2 --accept-multiclient --continue -- <args...>\n        │ TCP JSON-RPC (:2345)\n[anywhere — your machine / CI / agent]\n  agent-go-debugger attach --host <target> --port 2345\n```\n\n## Install\n\nThe CLI ships as an npm package with per-platform prebuilt binaries\n(no Go toolchain, no runtime dependencies — the binary for your machine is\ninstalled automatically as an optional dependency):\n\n```bash\nnpm i -g @adamancyzhang/agent-go-debugger\nagent-go-debugger version\n```\n\nSupported: darwin arm64/x64, linux arm64/x64, win32 x64 (Delve has no\nnative backend for windows/arm64; Windows-on-ARM runs the x64 build via\nemulation).\n\nBuild from source:\n\n```bash\ngo build -o dist/agent-go-debugger .\n```\n\n## Starting the target side (the only \"setup\" on the target)\n\n```bash\n# launch the Go service under the debugger and let it serve immediately\ndlv exec ./your-app --headless --listen=:2345 --api-version=2 \\\n  --accept-multiclient --continue -- <app args...>\n\n# or attach the debugger to an already running process\ndlv attach --headless --listen=:2345 --api-version=2 --accept-multiclient <PID>\n```\n\nNotes:\n\n- `--continue` lets the target serve **without any debugger client\n  connected** — attach later and it only stops when a breakpoint is hit.\n  Without it the target stays paused at its entry point until the first\n  client continues it (like `suspend=y`).\n- `--accept-multiclient` keeps the server alive between clients.\n- macOS needs Developer Mode once: `sudo DevToolsSecurity -enable`\n  (revoke afterwards with `-disable`). Linux/Windows: nothing.\n- This CLI talks to Delve v1.27+ (`--api-version=2` is the only valid value).\n\n## Quick start\n\n```bash\n# one-shot: set a breakpoint, run, detach (target keeps serving)\nagent-go-debugger attach --port 2345 \\\n  --exec 'bp add --function github.com/org/repo/controller.GetStatus --name gs' \\\n  --exec 'continue'\n\n# interactive\nagent-go-debugger attach --port 2345\n```\n\nA breakpoint hit emits a `stop` event with the full context; the target is\npaused until you `continue`/`step` (see the stop-hold guard below).\n\n```\n$ agent-go-debugger attach --port 2345 --json --exec 'bp add --function ...GetStatus' --exec 'continue'\n{\"mode\":\"remote\",\"pid\":44132,\"target\":\"127.0.0.1:2345\",\"type\":\"attach\"}\n{\"line\":\"bp add --function github.com/org/repo/controller.GetStatus --name gs\",\"type\":\"command\"}\n{\"bp\":{\"cond\":\"\",\"disabled\":false,\"file\":\"/srv/app/controller/misc.go\",\"function\":\"github.com/org/repo/controller.GetStatus\",\"id\":2,\"line\":57,\"name\":\"gs\",...},\"once\":false,\"op\":\"add\",\"type\":\"bp\"}\n{\"line\":\"continue\",\"type\":\"command\"}\n{\"bp\":{\"cond\":\"\",\"disabled\":false,...},\"file\":\".../misc.go\",\"function\":\"...GetStatus\",\"line\":57,\"reason\":\"breakpoint\",\"source\":[{...}],\"type\":\"stop\"}\n```\n\n## Commands\n\n| command | meaning |\n|---|---|\n| `bp add --file PATH --line N` / `--function NAME` | set a breakpoint (`--cond`, `--name`, `--trace`, `--once`, `--hit-expr '>N'`, `--disabled`) |\n| `bp list` `bp remove <id\\|name>` `bp enable/disable <id\\|name>` `bp clear` `bp condition <id\\|name> EXPR` | manage breakpoints |\n| `continue` `c` `next` `n` `step` `s` `fin` | execution |\n| `halt` | pause a running target |\n| `goroutines` `goroutine <id>` | goroutine list / switch current |\n| `stack` `locals` `args` `eval EXPR` `source` | inspection |\n| `status` `trace` | session state / flush tracepoint hits |\n| `quit` `kill` | end session (target keeps running) / terminate (server-owned) |\n\nFunction breakpoints need the full name with its package path\n(`github.com/org/repo/package.Func`, receivers as `pkg.(*T).M`); bare names\nare ambiguous. File paths are matched against the target's build-time paths\n(absolute paths work best).\n\n## Exit codes\n\n`0` all good · `1` any command failed or a wait timed out · `2` usage or\nconnection error · `130` interrupted.\n\n## JSON events\n\n`--json` emits one JSON object per line on stdout (the target's own output\nis redirected to stderr so the stream stays pure). Stable event `type`s:\n`attach`, `command`, `bp`, `stop`, `trace`, `timeout`, `exited`, `error`,\n`goroutines`, `goroutine`, `stack`, `locals`, `args`, `eval`, `source`,\n`status`, `handoff`, `quit`. See `skills/agent-go-debugger/SKILL.md`\nfor the full schemas.\n\n## Design semantics (vs the py/java siblings)\n\n- **Runnable by default.** The target serves normally; nothing pauses it\n  until a breakpoint is actually hit or an execution command runs.\n- **Interrupt-and-resume.** Breakpoint management and inspection briefly\n  halt + resume a running target around their RPC (millisecond-scale), so a\n  service is never wedged by \"set a breakpoint while live\".\n- **Stop-hold guard.** When the target is stopped and no command arrives\n  within `--resume-after` (default 60s), it is auto-resumed and an `error`\n  event is emitted, so a dead agent cannot freeze a service.\n- **Quit never kills.** `quit` resumes a stopped target and disconnects;\n  breakpoints stay registered on the server for the next client. `kill` is\n  explicit and only meaningful for server-owned (exec) targets.\n- **No per-goroutine pause.** Delve pauses the whole process on a stop\n  (Go has no equivalent of Python's per-thread tracing); `next`/`step`\n  resume execution during the step, tracepoints never pause at all.\n- **No pending breakpoints.** Go binaries carry all symbols at build time:\n  a location that cannot be resolved now (dead code, inlined, wrong path)\n  fails immediately with a hint.\n- **No exception breakpoints.** An unhandled panic exits the process (an\n  `exited` event with `reason: panic`); to observe panics set a breakpoint\n  in your `recover()`/middleware instead.\n\n## Development\n\n```bash\nbash scripts/check-skill.sh     # lint SKILL.md frontmatter (name/description,\n                                # no bare \": \" in plain scalars)\nbash tests/run_sample.sh        # starts a sample Go service under dlv (port 23456)\nbash tests/e2e_sample.sh        # runs the end-to-end scenarios\n```\n\n## Publishing (npm)\n\nDeploy never builds. Each `npm publish` runs that package's own\n`prepublishOnly`, which builds exactly the binary it ships\n(`scripts/build.js --one <platform>`) right before uploading — a publish can\nnever ship stale output, and nothing is ever built twice:\n\n```bash\nnpm run build                   # optional: full cross-compile matrix at once\nnpm run deploy                  # publishes each platform package (each one\n                                # builds itself via prepublishOnly first),\n                                # then the main package\nnpm run deploy -- --dry-run     # rehearsal without uploading\n```\n\nA single platform package can be published on its own — it still builds\nitself first. Requires `npm login` beforehand.\n","readmeFilename":"README.md"}