Skip to main content

ghosttrap-cli

The developer-side listener for ghosttrap. Connects errors from remote servers to Claude Code in real time.

Works with any Python app. Django and Celery get deep integration (middleware, app config, task failure hooks). Flask and other frameworks work via Python's logging and excepthook.

Setup

Requires the GitHub CLI (gh) and Claude Code.

pip install ghosttrap-cli
cd ~/your-project
ghosttrap setup

Then in Claude Code:

/ghosttrap

That's it. setup authenticates via gh, claims the repo, and installs a Claude Code skill. The /ghosttrap skill handles everything else — it installs the SDK into your app, wires in the error hooks, and starts monitoring.

What happens next

The skill file tells Claude Code to run ghosttrap peek in the background. Peek opens a WebSocket to ghosttrap.io and waits. When a production error arrives, Claude sees the full traceback — exception type, message, file, line, function — and starts fixing.

After fixing, Claude restarts peek and waits for the next one. Errors become a real-time stream that your AI agent dispatches automatically.

The SDK

Your app needs ghosttrap-sdk to report errors. The Claude Code skill handles the integration automatically — it installs the SDK, wires it into your app, and adds Django/Celery hooks if applicable. You shouldn't need to touch the SDK manually.

If you want to manually flag a caught exception or a non-exception condition, call ghosttrap.trap(exc_or_message) from your app code — see the SDK README.

Commands

Command What it does
ghosttrap setup Claim a repo, install the Claude Code skill
ghosttrap peek Wait for the next error, print it, exit
ghosttrap peek --clear Skip outstanding errors, then wait for the next one
ghosttrap last Fetch the most recent error and exit (no waiting)
ghosttrap last --clear Fetch the most recent error and skip everything older
ghosttrap watch Deprecated — peek reconnects until an error arrives, which covers the streaming case
ghosttrap list [n] Print a numbered summary of the most recent n errors (default 10, max 50). Doesn't move the cursor.
ghosttrap show <i> Full details for row i from the last list (1-based). Doesn't move the cursor.
ghosttrap raise "summary" Post an issue into a repo's stream — report body (markdown) from stdin
ghosttrap reply "summary" Answer a prior raise (deliverable ready, blocked, question) — body from stdin
ghosttrap clear Skip all outstanding errors
ghosttrap nuke Permanently delete every server-side row for the current repo (errors + token). Requires typed confirmation.

Every command except setup and nuke accepts --repo owner/name to target a specific claimed repo when you're not inside its working tree (e.g. ghosttrap peek --repo alex-rowley/ghosttrap-cli). Otherwise the repo is detected from cwd. nuke is intentionally cwd-locked.

Agent-to-agent issues

ghosttrap raise lets one agent (or person) hand a diagnosed issue to whatever agent is watching another repo's stream:

ghosttrap raise --repo owner/name "payments API rejecting valid ISO dates" < report.md

The markdown report travels verbatim inside the event and arrives through peek like any error, as type RaisedIssue — no traceback, no frames, just the report. The receiving agent is expected to verify the claim against its own codebase before acting. The same 5-minute dedup window as errors applies, so repeated identical raises collapse.

ghosttrap reply sends the same shape back as type RaisedReply, closing the loop in multi-stage exchanges: one agent raises "build me an endpoint shaped like this," the other builds, deploys, and replies "it's live, here's how to consume it" — and the first agent's peek picks that up and resumes the work that was waiting. Replies should be self-contained: the reader may be a fresh session with no memory of the request.

How it works

  • Setup authenticates with GitHub (via the active gh account) to prove you have access to the repo, then saves a repo token locally. If your active gh account can't see the repo, setup fails with a clear message; switch with gh auth switch and retry.
  • Peek connects to ghosttrap.io using that token — no GitHub auth needed after setup
  • If the connection drops or the server closes an idle socket, peek reconnects with a 60-second backoff for as long as it runs — it only exits once it has delivered an error (or hit a real failure, which it reports on stderr)
  • Errors that arrive while you're offline are replayed on next connect (cursor-based, no duplicates)
  • Repos are tracked by GitHub's immutable repo id, so a rename or transfer doesn't require any action — the next connect picks up the new owner/name and your token keeps working
  • Local state is stored in ~/.ghosttrap/config.json, keyed by GitHub repo id

Requirements

  • Python 3.10+
  • GitHub CLI (gh) — used for authentication during setup
  • Claude Code — the AI agent that fixes your errors
  • macOS or Linux (Windows is untested)

Privacy

Error data (tracebacks, exception messages, file paths) is routed through ghosttrap.io. The server is not open source yet — if there's demand for self-hosting, we'll open it up. Your GitHub token is used only during setup to verify repo access; it's never stored on the server. After setup, all communication uses a repo-specific token that grants access only to that repo's error stream — it cannot access your GitHub account.

User context (Django user id + username) is never sent unless you opt in with ghosttrap.init(token, send_user=True) in your app. Server hostname is captured automatically.

Run ghosttrap nuke from inside a repo to permanently delete every server-side row for that repo (errors + the token itself). Requires typing the repo name to confirm.

Metadata

Release files for ghosttrap-cli 0.3.30

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ghosttrap-cli 0.3.30
File Size Uploaded Provenance Actions
ghosttrap_cli-0.3.30.tar.gz 17.8 kB Without provenance Details for ghosttrap_cli-0.3.30.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ghosttrap-cli 0.3.30
File Interpreter ABI Platform Actions
ghosttrap_cli-0.3.30-py3-none-any.whl Python 3 none any Details for ghosttrap_cli-0.3.30-py3-none-any.whl

Total release size: 34.2 kB

Release files / ghosttrap_cli-0.3.30.tar.gz

Download URL ghosttrap_cli-0.3.30.tar.gz
Size 17.8 kB
Tags Source
SHA-256 checksum
How to use checksums
48499f7d81dd82cedb7d5cf16b7be44ff2cf1258c16e2d543bcb8f230d04ad76
BLAKE2b-256 checksum
How to use checksums
0d556bdcec6ea1814343cfa9509385fa80660a37be9f0009722d4740e2736540
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.14

Release files / ghosttrap_cli-0.3.30-py3-none-any.whl

Download URL ghosttrap_cli-0.3.30-py3-none-any.whl
Size 16.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a5774a6edfe9d79ab9d695e5fb6a368422aebf24e9ac6be23a6843eb587bb078
BLAKE2b-256 checksum
How to use checksums
7a01cac7a2b86fef0a81555ce744d2bdf2708197b7fde0e56a956d11ba8df4c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.14

Security for ghosttrap-cli 0.3.30

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.30 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page