io.github.GillMacedoPublished by GitHub account GillMacedov0.1.0Updated Nov 3, 2026
Find what a stuck Go program is waiting on from a goroutine dump, with no connection to it.
Reads Go goroutine dumps and tells an assistant what a stuck or leaking Go program is waiting on, without connecting to the program.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
An MCP server and CLI that reads a Go goroutine dump and tells you what the program is waiting on. It finds goroutine leaks, lock pile-ups, full database pools and HTTP calls with no timeout. It works from the dump text alone, so it never connects to your service.
A hung service can have thousands of goroutines, and most of them are normal: listeners, read loops, idle workers. stuckgo groups identical stacks, sets aside what's normally idle, and ranks what's left. When 40 goroutines wait on a mutex, it also names what might be holding it.
As a Claude Code plugin:
As an MCP server, for any client:
As a CLI, with Node 18 or newer:
Or with Go 1.27 or newer: go install github.com/GillMacedo/stuckgo@latest.
Get a dump from a service that imports net/http/pprof. This doesn't stop the program:
kill -QUIT <pid> also prints a dump, but it ends the process. Crash output works too, and GOTRACEBACK=all shows every goroutine rather than just the failing one.
Here's a real dump from a made-up service in examples/, run from a clone of this repo:
To check for a leak, compare two dumps taken some time apart. A stack that grows, with the same goroutine IDs staying in place, is much stronger evidence than one dump:
With Go 1.27 or newer, Go can also check for itself: /debug/pprof/goroutineleak?debug=2. stuckgo reads that output too.
Add --json for JSON, or --fail-on high to exit 1 in CI. Use - to read from stdin.
Severity comes from how many goroutines are involved and how long they've waited. These thresholds are judgment calls.
debug=1 shows less. It has counts, with no wait times or goroutine IDs, and hides most of what a goroutine waits on. Use debug=2 when you can.net/http, database/sql, gRPC and golang.org/x/net/http2. Other libraries' background loops show up as groups, but rarely as findings.stuckgo stays on your machine, but your MCP client sends tool results to its model.How do I find a goroutine leak in Go? Take two dumps some time apart and run stuckgo compare. A growing stack whose goroutine IDs stay in place is the sign to look for.
How do I get a goroutine dump from a running Go program? Import net/http/pprof, then fetch /debug/pprof/goroutine?debug=2. Keep that endpoint private.
What does [chan send, 5 minutes] mean in a goroutine dump? That goroutine has been blocked for about 5 minutes, sending on a channel nothing is receiving from. SG109 covers it.
Why is my Go service out of database connections? Goroutines waiting in database/sql.(*DB).conn mean the pool is full. SG105 flags them. Look at what's holding the connections, such as slow queries or Rows that aren't closed.
How is this different from panicparse or goroutine-inspect? panicparse and goroutine-inspect help a person read and explore a dump. stuckgo gives an agent ranked findings, can compare two dumps, and sets aside what's normally idle.
examples/programs/: every rule from SG101 to SG109, plus SG111, SG114 and SG117, fired on dumps from programs that really got stuck, in examples/dumps/. Most also ran on Go 1.22.examples/dumps/real/, raised nothing above low. Prometheus gets two low WaitGroup findings, which are normal there.It hasn't been used on an incident in production yet, or in a fresh Claude session.
Contributions are welcome, from people and from people working with AI agents. See CONTRIBUTING.md. Good first issues are listed here.
This project was largely generated with Claude Code and reviewed by its maintainer.
I'm Giulliano Macedo, and I build developer tools at GoTech Solutions. Follow along or get in touch:
If stuckgo found what your program was stuck on, a star helps others find it.
Built by Giulliano Macedo, GoTech Solutions · LinkedIn · X
Source: README.md at commit 6627356
Compare two Go goroutine dumps
Compares two goroutine dumps of one Go program taken some time apart, and shows which stacks are growing and which goroutine IDs never moved, which is stronger evidence of a leak than one dump. It never connects to the program.
afterbeforeafter_pathbefore_pathReview a Go goroutine dump
Finds what a stuck or leaking Go program is waiting on, from a goroutine dump: /debug/pprof/goroutine?debug=2 or debug=1, a panic traceback, or SIGQUIT output. Groups identical stacks, separates normal idle goroutines, and flags channel leaks, lock pile-ups with possible holders, WaitGroups that never finish, full database pools, HTTP calls with no timeout and nil channels. It only reads the text you give it and never connects to the program. Findings are leads.
dumppath90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
claude plugin marketplace add GillMacedo/stuckgoclaude plugin install stuckgo@stuckgo-marketplace{"mcpServers": {"stuckgo": {"command": "npx", "args": ["-y", "[email protected]", "serve"]}}}npx stuckgo review dump.txtcurl 'http://localhost:6060/debug/pprof/goroutine?debug=2' > dump.txt$ go run . review examples/dumps/mutex-late.txt43 goroutines, 1 normally idle
Groups: 40 sync.Mutex.Lock, up to 2 min main.(*store).Get (app/main.go:109) 1 chan receive, up to 2 min main.mutex (app/main.go:130) 1 select, up to 2 min main.(*store).Refresh (app/main.go:118)
HIGH SG107 main.(*store).Get (app/main.go:109) 40 goroutines waiting for a mutex, waiting up to 2 minutes. Possible holder, not proven: main.(*store).Refresh (app/main.go:118), in select. Try: Look at what the holder does while it holds the lock. Don't hold a lock across network calls, channel operations or slow work.$ go run . compare examples/dumps/leak-early.txt examples/dumps/leak-late.txtGoroutines: 344 -> 637 (+293)
Growing: +293 342 -> 635 chan send main.lookupPrice.func1 (app/main.go:79)
Same goroutine IDs in the same place in both dumps: 342 chan send, up to 2 min main.lookupPrice.func1 (app/main.go:79)