Metadata-Version: 2.5
Name: stacktrace-cli
Version: 0.3.0
Summary: CLI for Stacktrace — Detection and Response platform for AI Agents.
Project-URL: Homepage, https://stacktrace.ai
Author-email: "Stacktrace AI, Inc" <founders@stacktrace.ai>
License-Expression: LicenseRef-Proprietary
Keywords: agent-security,ai-security,openaca,stacktrace
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx<1.0.dev0,>=0.28.1
Requires-Dist: openaca==0.6.0
Requires-Dist: openaidr==0.1.0
Description-Content-Type: text/markdown

# 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

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

Requires Python 3.11 or newer.

```console
$ stacktrace --version
stacktrace 0.2.1 (openaca 0.6.0)
```

## Quick start

```bash
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

| Command | |
|---|---|
| `sessions` | Print what the agents on this machine actually did. |
| `detect` | Find security and reliability findings in what agents did. |
| `monitor` | Watch this machine's agents in a browser, live. |
| `remote` | Configure remote endpoint services and upload to Stacktrace Cloud. |
| `scan` | Scan a repository or endpoint for agent-composition findings. |
| `bom` | Generate an Agent BOM for a repository or endpoint. |
| `policy` | Validate and compile restrictive endpoint policies. |

The last three are composition analysis, supplied by
[`openaca`](https://pypi.org/project/openaca/) and available under either
name.

## What it looks like

```console
$ stacktrace sessions --since 2d --include-content
claude-code:s1  [claude-code]  2026-08-27T09:00:00+00:00  2 turns  2 calls
  assistant: Reading the changelog before drafting the release notes.
    ok                28c  Read
        result: ## 0.4.0 - correlate, detect
  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 stalled loop and a leaked credential do not belong on one scale.

**Security** — a credential reaching an outbound call; an injected instruction
the agent then followed; a vulnerable component actually reached, with the
vulnerability behind it.

**Reliability** — a loop that stalled; a call that hung.

Findings are correlated against an Agent BOM before they are judged, so a
vulnerable component is reported when something actually used it rather than
because it is installed.

## What leaves your machine

Two of `detect`'s three stages run entirely locally and need no model or
credential, and they are the two a bare `detect` runs. The third sends flagged
sessions to the agent's *own* CLI — the provider that produced the transcript,
never a different one — and runs only when you pass `--reasoning`, capped by
`--budget`.

`sessions` omits prompts, tool arguments and results unless you pass
`--include-content`. `monitor` binds to loopback only, refuses a non-loopback
address rather than warning about it, and analyses nothing with a model unless
`--reasoning` is given.

## 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](https://github.com/open-agent-security/openaidr).

## Built on

Two Apache-2.0 packages, neither of which depends on this one:
[`openaca`](https://pypi.org/project/openaca/) for agent composition analysis,
and [`openaidr`](https://pypi.org/project/openaidr/) for session collection.

## Licence

Proprietary. © Stacktrace AI, Inc. — [stacktrace.ai](https://stacktrace.ai)
