debughub
v1.2.0
Published
Cross-platform CLI tool for agent-agnostic deterministic debug logging
Downloads
300
Maintainers
Readme
DebugHub
A cross-platform CLI tool providing a Cursor-like "Debug Mode" loop for any coding agent (Codex, Claude, etc.), without requiring MCP or complex remote execution setups.
Features
- Runtime Setup Guide: See
docs/RUNTIME_PREREQS.mdfor installing Java/Go/Python/Rust/PHP/.NET required by helper E2E tests. - Agent-Agnostic: Works with any coding assistant capable of modifying files and running basic OS commands.
- Vendored Runtime Helpers: Small, standalone helpers for TypeScript/Node, Browser TS/JS, Java, Python, Rust, PHP, Go, and C# are installed in
.debughub/vendor. - Shared HTTP Contract: All helpers follow one event contract (
.debughub/vendor/<version>/http/EVENT_CONTRACT.mdafterdebughub install) and submit best-effort HTTP events to the local collector. - Deterministic: A
MANIFEST.jsonand strict integrity verification ensures files are not tampered with. - Safe and Local: By default, the collector server only binds to
127.0.0.1.
Quick Start
- Install inside any repository:
npx debughub install- Start the local collector:
npx debughub startRead the given
sessionIdand endpoint. Follow the instructions to configure your environment variables:DEBUGHUB_ENABLED=1DEBUGHUB_SESSION=<sessionId>DEBUGHUB_ENDPOINT=http://127.0.0.1:<port>
Use the helper inside your app code (see
.debughub/vendor/<version>).Run your app and reproduce the issue.
Check logs:
npx debughub tail --n 50Security Model
- No network traffic leaves your local machine.
- No remote code is downloaded at runtime.
- No
evalor shell spawning in helpers. - The
debughub verifycommand validates the helper code matches the official SHA-256 signatures.
Commands
debughub install: Installs support files to.debughub/.debughub start: Starts the collector server in the background.debughub stop: Stops the background collector.debughub tail: Print the latest recorded events.debughub search "<query>": Search events by text or label.debughub clear: Clears the output log file.debughub verify: Verifies integrity of the vendor code in.debughub/.debughub doctor: Checks installation and system status.
