Gospy

🚀 Go Process Inspector

A tool for inspecting and analyzing running Go processes, including goroutine status, memory statistics, and binary information.

✨ Features

• View detailed goroutine information (status, scheduling information).
• Analyze process memory statistics.
• Support cross - platform (Linux and macOS).
• Provide interactive inspection through a terminal UI.
• Implement programmatic access via HTTP API (SSE endpoint for MCP server).

📦 Installation

go install github.com/monsterxx03/gospy@latest

💻 Usage Examples

CLI Interface

# Interactive terminal UI
sudo gospy top --pid <Process ID>

# HTTP API server
sudo gospy serve --port 8974

# Get process summary
sudo gospy summary --pid <Process ID>

# Get process summary in JSON format
sudo gospy summary --pid <Process ID> --json

Summary Command Options

• --pid/-p - Target process ID (required).
• --bin/-b - Path to the executable file (optional).
• --json/-j - Output results in JSON format.

API Endpoints

• GET /goroutines?pid=<PID> - List all goroutines.
• GET /memstats?pid=<PID> - Get memory statistics.
• GET /runtime?pid=<PID> - Get runtime version information.

MCP Server

The MCP server provides an SSE (Server - Sent Events) endpoint. To enable it:

>>> sudo gospy serve --enable-mcp --port 8974

Start the API server, listening on port 8974.
Endpoints:
  GET /runtime?pid=<PID>     - Get runtime information.
  GET /goroutines?pid=<PID> - Get the goroutine list.
  GET /memstats?pid=<PID>   - Get memory statistics.
  GET /mcp/sse   - MCP SSE endpoint.

Available MCP tools:

• goroutines - Dump goroutines in a Go process.
• gomemstats - Dump memory statistics.
• goruntime - Get runtime information.
• pgrep - Find the PID by process name.

Configuration in the cursor:

Terminal UI Controls

• q - Exit.
• r - Refresh data.
• s - Pause/resume the top view.
• / - Search/filter goroutines.

Terminal UI Screenshot

Building from Source

git clone https://github.com/monsterxx03/gospy.git
cd gospy
make

Requirements

• Go version 1.20 or higher.
• Linux or macOS (Apple Silicon only).
• Root privileges (required to read process memory).

Root Privileges

Gospy requires root privileges to:

• Read process memory (/proc//mem on Linux).
• Access the Mach API on macOS.

Run with sudo:

sudo gospy top --pid <Process ID>

For development/debugging, you may need to:

1. Build the binary first: make.
2. Run with sudo: sudo ./gospy [command].

Acknowledgments

Version 0.7.0 was completely rewritten from scratch and over 90% of the code was written by aider. Other assistance came from:

• DeepSeek (R1 + V3 model) - AI coding assistant.

Total AI computing cost: ~$2.

📄 License

MIT - For detailed information, please refer to the LICENSE file.