stacktrace-cli

Detection and response for AI coding agents, from the command line.

Coding agents read files, run shell commands and call MCP servers on their own initiative, and they write a transcript of every bit of it to disk. stacktrace reads those transcripts, correlates what ran against the components the agent is built from, and reports the security and reliability findings in it — locally, on the machine the agent worked on.

The PyPI distribution is stacktrace-cli; the command it installs is stacktrace. The two names differ because the bare stacktrace name on PyPI belongs to an unrelated project.

Installation

uv tool install stacktrace-cli     # isolated; recommended
# or
pip install stacktrace-cli

Requires Python 3.11 or newer.

$ stacktrace --version
stacktrace 0.11.0 (openaca 0.10.1)

Python package namespace

The implementation package is stacktrace, installed from the stacktrace-cli distribution. There is no stacktrace_cli compatibility alias. Update direct Python imports and custom launchers to python -m stacktrace; reinstall any daemon or service definitions that still name the old module. CLI commands and the distribution name remain unchanged.

Do not install the unrelated PyPI distribution stacktrace in the same Python environment. Use pip install stacktrace-cli, not pip install stacktrace. Python agents can import ObservationClient from stacktrace to send configured observations to Core. Shared validation and projection APIs live in stacktrace.core. See the Python example and observation contract.

Quick start

stacktrace sessions      # what the agents on this machine did
stacktrace detect        # what is wrong with it
stacktrace monitor       # the same, live in a browser

Commands

The last three are composition analysis, supplied by openaca and available under either name.

Webhook notifications

Configure one host-level endpoint; the running daemon delivers retained eligible findings and new findings automatically:

stacktrace webhook configure --url https://alerts.example.com/stacktrace
stacktrace webhook status
stacktrace webhook disable

configure prompts for an optional HMAC-SHA256 signing secret without echoing it. The endpoint receives a narrow JSON document containing the event ID, rule, severity, confidence and session identity—not transcript content, finding prose or evidence. Delivery is at least once, so receivers should deduplicate on event_id. The URL and secret are stored in a mode-0600 host configuration file. HTTP is accepted only for loopback development endpoints.

Failed deliveries retry without a limit while enabled. Outages can grow the local backlog, bounded by the local retention window—findings older than that when the endpoint next accepts requests are not sent. Changing the endpoint sends the remaining backlog to the new destination; rotating its signing secret preserves progress. Configure and disable take effect from the next request: one already in flight may still complete with the previous configuration. Re-enabling resumes only pending findings still within the retention window, not already-delivered findings.

What it looks like

$ stacktrace sessions --since 2d --include-content
claude-code:s1  [claude-code]  2026-08-27T09:00:00+00:00  2 turns  2 calls
  2026-08-29T12:00:00+00:00  assistant: Reading the changelog before drafting the release notes.
    ok                28c  Read
        result: ## 0.4.0 - correlate, detect
  2026-08-29T12:00:00+00:00  assistant: Filing the release-notes follow-up.
                        -  github/create_issue

Summary — 1 sessions, 2 turns, 2 tool calls

  agent kinds
          1  claude-code

  tools called (2 distinct)
          1  Read
          1  github/create_issue

  MCP servers reached (1 distinct)
          1  github

  0 subagent turns · 0 results abridged upstream · 1 ok

1 of 2 calls returned with no outcome the collector could establish; the agent's parser supplies no success signal.

A blank status column is the collector's unknown, not a pending call: the client recorded no outcome that could be established, and the closing line counts those rather than filling one in.

What detect finds

Four kinds of finding, under two families that carry separate severity ladders — a blocked agent and a leaked credential do not belong on one scale.

Security — a credential reaching an outbound call; success reported against the session's own evidence of failure; an infrastructure change beyond what the user asked for.

Reliability — why the agent stopped, in words, with what to do about it: a spend limit reached, a safety check blocking, a service refusing a call.

Findings are correlated against an Agent BOM before they are reported, so one that names a component names the one a call actually reached.

What leaves your machine

On a default run, detect reads the record on this machine. It needs no model, no credential and no account, and nothing derived from a session — no prompt, no tool argument, no result — is sent anywhere.

One network call is made even then, and it is worth stating because nothing leaves is not what happens: correlation matches advisories by sending the package coordinates of the components a session invoked to osv.dev. Coordinates only.

One flag pair changes that, and it has to be typed in full. detect --reasoning --analyzer jev adds a third stage that sends two small states to TypeSafe's Jev: a gate carrying the closing lines of each hand-back, capped, which ends most sessions there — and, for a session that clears it, one per-call window each carrying a completion claim, one verification command and the tail of its output. A session that ran a mutating infrastructure command (aws ecs update-service, kubectl apply, terraform apply) also sends one window per such command: the command itself and your own requests in that session — the opening prompt, your later messages and the agent line before each — so Jev can judge whether you asked for the change. Neither flag has a default and neither implies the other, so naming the vendor is your act rather than ours (ADR-0033). Without both, stage three is not asked. detect --analyzer jev alone reads back what such a run already paid for and commissions nothing (ADR-0035).

With Fleet configured (stacktrace remote configure), the daemon sends its findings, and its token usage for the cost ledger: tokens per run, session, model and minute, and per run the repository's name (owner/repo, from its origin remote), the branch, the session's own title (never the prompt) and the opaque id of the account the agent is signed into, Claude Code's or Devin's. With each account go its display name (else the part of its email before the @), its plan, and a key that groups one person's accounts: a hash of the email and the Fleet organization, never the email itself. A finding carries its session's account the same way. Prompts, tool arguments, results and paths are not sent (ADR-0096, ADR-0104, ADR-0101, ADR-0112).

To learn who Devin is signed in as, stacktrace runs Devin's own devin auth status, which asks Devin's server. It asks again only after Devin's sign-in changes, or ten minutes after an ask that named no one (ADR-0110).

sessions omits prompts, tool arguments and results unless you pass --include-content. monitor binds to loopback only, and refuses a non-loopback address rather than warning about it.

Usage telemetry is enabled by default. Disable it before normal use with stacktrace telemetry off. An existing opt-out stays off; unreadable or invalid settings also disable telemetry. The first enabled usage event creates a random identifier. Five event types go to PostHog's US region through its managed proxy at w.stacktrace.ai: an enabled identity first becomes active, a command completes, a session starts, a finding is delivered, or a product error occurs. Event fields describe the command's name (sessions, detect, ... — never its arguments, flags, paths or values), the rule, severity, destination or error category, the session id and agent kind for session and finding events, plus CLI version, OS, environment, whether it ran in a Claude Code cloud session (remote), whether it ran on a Stacktrace team machine (internal) and timestamp. An error also names the component that met it. PostHog stores the sending IP address and derives a country and city from it. Help, --version, a mistyped command and stacktrace telemetry itself send nothing. environment is production unless STACKTRACE_TELEMETRY_ENV is set to staging, development or test. internal is true on a development build, or once any command has run with STACKTRACE_INTERNAL=1; that run saves the mark so the daemon sees it, and STACKTRACE_INTERNAL=0 clears it (ADR-0091). They do not include prompts, tool arguments, results, full findings, paths or repository names. The persistent identifier and timing mean this is not anonymous data.

stacktrace telemetry show prints the state, the destination, the location lookup, the environment, the identifier and every event with every property it may carry. off deletes the local identifier; it does not delete previously uploaded records, and an event already handed to the client may still be sent. stacktrace telemetry on enables telemetry again under a new identity (ADR-0039, ADR-0090). STACKTRACE_TELEMETRY_DISABLED=1 sends nothing, for CI and test runs.

Status

Beta, and under active development.

sessions, detect and monitor work end to end today, for Claude Code and Devin sessions alike (Devin CLI and Devin Desktop's local agent). Session collection is OpenAIDR's, and further agent kinds arrive with it. The daemon observes every kind it reads, sub-agents included.

Built on

Two Apache-2.0 packages, neither of which depends on this one: openaca for agent composition analysis, and openaidr for session collection.

Licence

Proprietary. © Stacktrace AI, Inc. — stacktrace.ai