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.4.0 (openaca 0.7.0)

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.

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

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

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

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. The daemon sends four event types to PostHog's US region: an enabled identity first becomes active, a session starts, a finding is delivered, or a product error occurs. Event fields describe the rule, severity, destination, reason code 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) and timestamp. environment is production unless STACKTRACE_TELEMETRY_ENV is set to staging, development or test. 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 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). 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. Session collection currently reads Claude Code transcripts; further agent kinds are in progress upstream in OpenAIDR.

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