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 consume [n] Dump every outstanding error (everything past the cursor) as full JSON, oldest first, and advance the cursor past them. n takes only the oldest n.
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 shelf [n] List quarantined events (browser JS + ad-hoc shell) — stored, never streamed, untrusted. jslogs is an alias
ghosttrap record-sdk Record SDK wiring state (--version, --init-file) — the CLI is the sole writer of config.json
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)
  • Cursors are per-repo (cli >= 0.3.34), so peeks for different repos coexist on one machine without stepping on each other's replay position
  • 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.37

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.37
File Size Uploaded Provenance Actions
ghosttrap_cli-0.3.37.tar.gz 21.3 kB Without provenance Details for ghosttrap_cli-0.3.37.tar.gz

Built distribution (wheel)

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

Total release size: 41.1 kB

Release files / ghosttrap_cli-0.3.37.tar.gz

Download URL ghosttrap_cli-0.3.37.tar.gz
Size 21.3 kB
Tags Source
SHA-256 checksum
How to use checksums
5445648b53e05418ff9316614692fdfeafe494c6486ba98a7cf71faad2dae053
BLAKE2b-256 checksum
How to use checksums
d016cf5330f4f5484d11ebe1cbefe19f5158ea9f8b37339098e7f62cd5f70713
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

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

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

Security for ghosttrap-cli 0.3.37

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.37 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