https://github.com/monsterxx03/gospy
Non-Invasive goroutine inspector
https://github.com/monsterxx03/gospy
aider golang goroutine mcp-server profiling
Last synced: 4 months ago
JSON representation
Non-Invasive goroutine inspector
- Host: GitHub
- URL: https://github.com/monsterxx03/gospy
- Owner: monsterxx03
- License: mit
- Created: 2019-08-30T04:10:17.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-06-13T13:56:42.000Z (12 months ago)
- Last Synced: 2025-06-13T14:51:48.996Z (12 months ago)
- Topics: aider, golang, goroutine, mcp-server, profiling
- Language: Go
- Homepage:
- Size: 5.28 MB
- Stars: 90
- Watchers: 4
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- toolsdk-mcp-registry - ❌ gospy
- metorial-index - Go Process Inspector - Inspect and analyze running Go processes, providing detailed information about goroutines, memory usage, and binary data through an interactive terminal and an HTTP API. Features include programmatic access via a Server-Sent Events endpoint and tools for inspecting goroutine states and memory statistics. (Monitoring and Logging)
README
# Go Process Inspector
[](https://goreportcard.com/report/github.com/monsterxx03/gospy)
[](LICENSE)
[](https://cursor.com/install-mcp?name=gospy&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojg5NzQvbWNwIn0%3D)
A tool for inspecting and analyzing running Go processes, including goroutine states, memory statistics, and binary information.
## Features
- View detailed goroutine information (status, scheduling info)
- Analyze process memory statistics
- Cross-platform support (Linux and macOS)
- Terminal UI for interactive inspection
- HTTP API for programmatic access
- mcp server
## Installation
```bash
go install github.com/monsterxx03/gospy@latest
```
## Usage
### CLI Interface
```bash
# Interactive terminal UI
sudo gospy top --pid
# HTTP API server
sudo gospy serve --port 8974
# Get process summary
sudo gospy summary --pid
# Get process summary in JSON format
sudo gospy summary --pid --json
```
#### Summary Command Options
- `--pid/-p` - Target process ID (required)
- `--bin/-b` - Path to binary file (optional)
- `--json/-j` - Output results in JSON format
### API Endpoints
- `GET /goroutines?pid=` - List all goroutines
- `GET /memstats?pid=` - Get memory statistics
- `GET /runtime?pid=` - Get runtime version info
### MCP Server
The MCP server provides an http (streamableHTTP) endpoint. To enable:
```bash
>>> sudo gospy serve --enable-mcp --port 8974
Starting API server on port 8974
Endpoints:
GET /runtime?pid= - Get runtime info
GET /goroutines?pid= - Get goroutines list
GET /memstats?pid= - Get memory stats
GET /mcp - MCP http endpoint
```
Available MCP tools:
- `goroutines` - Dump goroutines for a go process
- `gomemstats` - Dump memory stats for a go process
- `goruntime` - Dump runtime info for a go process
- `pgrep` - Find pid from process name
Config in cursor
### Terminal UI Controls
- `q` - Quit
- `r` - Refresh data
- `s` - Suspend/Resume top view
- `/` - Search/filter goroutines
### Terminal UI Screenshot
## Building from Source
```bash
git clone https://github.com/monsterxx03/gospy.git
cd gospy
make
```
## Requirements
- Go 1.20+
- Linux or macOS (Apple Silicon only)
- Root privileges (required for memory access)
## Root Privileges
gospy requires root privileges to:
- Read process memory (/proc//mem on Linux)
- Access Mach APIs on macOS
Run with sudo:
```bash
sudo gospy top --pid
```
For development/debugging, you may want to:
1. Build the binary first: `make`
2. Run with sudo: `sudo ./gospy [command]`
## Credits
Version 0.7.0 was completely rewritten from scratch with [aider](https://aider.chat), which wrote >90% of the code. Additional assistance from:
- [DeepSeek](https://deepseek.com) (R1 + V3 models) - AI coding assistant
Total AI compute cost: ~$2 USD
## License
MIT - See [LICENSE](LICENSE) file for details.