Full flag reference for every agent-strace command.

agent-strace record [--name NAME] [--parent SESSION] [--no-redact] [--mask] -- <command>

Capture an MCP stdio server session. Wraps <command> as a transparent proxy.

AGENT_STRACE_PARENT_SESSION can also be set by orchestrators that spawn child agents.

agent-strace record-http <url> [--port N] [--parent SESSION] [--no-redact] [--mask]

Capture an MCP HTTP/SSE server session. Listens on --port (default: 3100) and proxies to <url>.

agent-strace setup [--cli claude|codex|gemini|cursor|copilot|all] [--no-redact] [--global]

Print or install hooks config for supported agent CLIs. --cli claude prints Claude Code settings JSON for ~/.claude/settings.json; --cli codex writes $CODEX_CONFIG_DIR/hooks.json or ~/.codex/hooks.json; --cli gemini writes a Gemini CLI extension under $GEMINI_CONFIG_DIR/extensions/agent-strace or ~/.gemini/extensions/agent-strace; --cli cursor writes .cursor/hooks.json or $CURSOR_CONFIG_DIR/hooks.json; --cli copilot writes $COPILOT_HOME/hooks/agent-strace.json or ~/.copilot/hooks/agent-strace.json; --cli all configures all supported CLIs. Secret redaction is enabled by default; use --no-redact only for trusted local traces.

agent-strace import <path.jsonl> [--discover]

Import a Claude Code JSONL session log. --discover lists available sessions in ~/.claude/projects/.

agent-strace replay [session-id] [--format terminal|html] [--live] [--speed N]
                    [--filter TYPES] [--limit N] [--expand-subagents] [--tree]
                    [-o FILE]

agent-strace tree [session-id] [--format text|json]

Show the parent/child session hierarchy for a root session, including per-node cost, tool calls, status, and duration. Parent links come from record --parent, AGENT_STRACE_PARENT_SESSION, A2A trace propagation, or imported trace metadata.

agent-strace list

List all captured sessions with ID, timestamp, duration, tool calls, and errors.

agent-strace inspect <session-id>

Dump full session as JSON (meta + events).

agent-strace stats [session-id] [--include-subagents]

Tool call frequency and timing. --include-subagents rolls up across the full subagent tree.

agent-strace explain [session-id]

Plain-English phase breakdown: what the agent did, files touched, retries, wasted time. No LLM required.

agent-strace timeline [session-id] [--format text|json] [--model MODEL]

Structured phase-by-phase view with tool calls, errors, retries, and cost per phase.

agent-strace why [session-id] <event-number>

Trace the causal chain backwards from event #N. Run replay first to see event numbers.

agent-strace cost [session-id] [--model MODEL] [--input-price N] [--output-price N]

Token and dollar cost by phase. Flags wasted spend on failed phases.

agent-strace diff <session-a> <session-b> [--semantic] [--compare]

Compare two sessions structurally.

agent-strace compare [session-id-a] [session-id-b] [--tag TAG] [--format text|json]

Regression report with verdict. --tag compares the last two sessions whose name contains the tag.

agent-strace token-budget <session-id> [--model MODEL] [--warn-at PCT]

Check token usage against model context limit.

agent-strace watch [session-id] [--timeout DURATION] [--budget $N] [--on-violation ACTION]
                   [--on-death CMD] [--policy FILE] [--rules FILE_OR_BUILTINS] [--stream-to URL]
                   [--stream-batch-size N] [--stream-flush-interval S]
                   [--loop-threshold N] [--loop-window N] [--max-context-pct N] [--dry-run]

Live session monitor with kill-switch rules.

Project budget config (.agent-strace.yaml):

budget:
  weekly: 20.00
  warn_at: 0.80
  stop_at: 1.00
  per_session_max: 5.00

When this block is present, watch checks rolling seven-day spend at startup and during the session. warn_at writes a terminal warning and alert-log entry. stop_at blocks new record and record-http sessions. per_session_max uses the watchdog cost guard and kills only the over-budget session.

Rules file format (.watch-rules.json):

{
  "rules": [
    { "name": "cost cap", "condition": "cost_usd > 0.50", "action": "kill" },
    { "name": "protected env", "condition": "file_path matches \"**/production.env\"", "action": "kill" },
    { "name": "large edit", "condition": "files_modified > 30", "action": "pause" }
  ]
}

Built-in loop rule config:

watchers:
  loop:
    identical_calls: 3
    window: 10

agent-strace mcp-scan [--session ID] [--since DURATION_OR_DATE] [--watch]
                       [--patterns FILE] [--project-root DIR] [--format text|json]

Scan recorded sessions for runtime MCP tool poisoning indicators. Checks include suspicious tool description instructions, description hash drift against earlier sessions, and risky sequences such as credential reads followed by external HTTP calls.

Custom patterns are read from ~/.agent-strace/mcp-patterns.txt by default. Add one case-insensitive regex per line; blank lines and # comments are ignored.

agent-strace audit [session-id] [--policy FILE]

Check tool calls against a policy file. Flags sensitive file access even without a policy. Exits 1 on violations.

Policy file (.agent-scope.json):

{
  "files": {
    "read":  { "allow": ["src/**", "tests/**"], "deny": [".env"] },
    "write": { "allow": ["src/**"], "deny": [".github/**"] }
  },
  "commands": {
    "allow": ["pytest", "uv run", "cat"],
    "deny":  ["curl", "wget", "rm -rf"]
  },
  "network": { "deny_all": true, "allow": ["localhost"] }
}

agent-strace verify [session-id] [--format text|json]
agent-strace verify --from-export FILE [--format text|json]

Verify a session hash chain, or verify the chain links embedded in an EU AI Act export package.

agent-strace policy [--last N] [--output FILE]

Generate .agent-scope.json from observed traces. Review and tighten before committing.

agent-strace audit-tools [--repo .] [--since DATE] [--approved TOOLS]

Detect Shadow MCP servers and undeclared agent activity. No network calls, no API keys.

agent-strace postmortem [session-id] [--list] [--stale-after SECONDS]

Generate a structured postmortem for failed or crashed sessions. watch writes a lightweight heartbeat while monitoring; if the heartbeat becomes stale and the session has no clean SESSION_END, postmortem classifies the crash and writes .agent-traces/<session-id>/postmortem.md with recovery context.

agent-strace approval list [--status pending|approved|denied]
agent-strace approval show <request-id>
agent-strace approval approve <request-id> [--note TEXT]
agent-strace approval deny <request-id> [--note TEXT]

Human-in-the-loop approval queue. Agents pause at a checkpoint and wait for a human to approve or deny before continuing. Integrates with the watch kill-switch — a denied request triggers the configured --on-violation action.

agent-strace rbac assign --user USER --role ROLE [--scope org|workspace] [--workspace NAME]
agent-strace rbac revoke --user USER --role ROLE [--scope org|workspace]
agent-strace rbac list [--scope org|workspace]
agent-strace rbac check --user USER --action ACTION [--resource RESOURCE]

Role-based access control for the hosted collector. Roles: admin, editor, viewer.

agent-strace auth login --host URL [--client-id ID] [--issuer URL]
agent-strace auth logout
agent-strace auth status

Authenticate with a hosted collector via OIDC. Stores the token in ~/.agent-strace/token.json. All subsequent commands that contact the collector use the stored token automatically.

agent-strace apply [--config FILE] [--host URL] [--dry-run]

Apply .agent-strace.yaml to the local store or a hosted collector. Use --dry-run to preview changes without writing.

agent-strace config-diff [--config FILE] [--host URL]

Show the diff between the local .agent-strace.yaml and the live config on a hosted collector.

agent-strace workspace list
agent-strace workspace new <name>
agent-strace workspace use <name>
agent-strace workspace rm <name>

Isolated workspaces — each workspace has its own session store. Use use to print the shell export (AGENT_STRACE_STORAGE) for a workspace.

agent-strace compliance export [session-id] --framework eu-ai-act|soc2|hipaa|all
                                [--since Nd] [--output FILE]

Export a compliance report for the specified framework. Covers session retention, data handling, access logs, and policy enforcement evidence.

For an auditor-facing EU AI Act Article 12/13 package, use the session export path:

agent-strace export <session-id> --format eu-ai-act --output compliance-report.json
agent-strace export --all --since 2026-01-01 --until 2026-03-31 \
  --format eu-ai-act --output Q1-audit.json
agent-strace verify --from-export compliance-report.json
agent-strace audit-readiness [--format text|json]

agent-strace audit-readiness [--retention-days N] [--format text|json]

Check whether the local trace store has hash-chain integrity, retention coverage, timestamp continuity, and hash-chain presence before generating an EU AI Act audit package.

agent-strace dashboard [--last N] [--since DATE] [--html FILE] [--trend]

Multi-session aggregate view. --trend shows eval quality and behavioral metrics over time.

# Add a timeline annotation (appears as a vertical marker on trend charts)
agent-strace dashboard annotate --date 2026-05-10 --note "Added retry policy"

agent-strace drift [--since DURATION] [--baseline FILE] [--save-baseline FILE]
                   [--threshold N] [--format text|json]

Detect behavioral drift across sessions. Exits non-zero when drift score exceeds --threshold (default: 0.20).

agent-strace fingerprint [--sessions N] [--output FILE] [--format text|json]
agent-strace fingerprint --compare A.json B.json [--threshold N] [--format text|json]

Characterize an agent's recent behavior: tool mix, error rate, retry rate, file touch radius, duration, and decision depth. Saved JSON fingerprints can be used as drift baselines or compared directly.

agent-strace freeze [session-id] [--output FILE] [--task TEXT] [--format text|json]
agent-strace regression <fixture-file> [session-id] [--threshold N] [--format text|json]

Freeze a session's tool-call sequence as a JSON fixture containing tool names and stable input hashes, not raw tool inputs. regression compares a later session against the fixture and exits non-zero when structural divergence exceeds --threshold (default: 0.0).

agent-strace lint [session-id] [--all] [--since DURATION] [--strict] [--format text|json]

Flag bad behavior patterns: tool loops, reasoning spirals, budget proximity, context saturation, redundant reads, error-retry loops, no-output sessions.

--strict exits 1 on any WARN or ERROR. Configure rules via .agent-strace-lint.json.

agent-strace eval [session-id] [--format text|json]
agent-strace eval compare <session-a> <session-b>
agent-strace eval ci

Score a session against configurable criteria. eval ci exits non-zero if any scorer fails.

Configure scorers in .agent-evals.yaml:

scorers:
  - type: no_errors
  - type: cost_under
    max_dollars: 0.10
  - type: files_scoped
    allowed_paths: ["src/", "tests/"]

agent-strace budget-report [--since DATE] [--until DATE] [--format text|markdown|json]

Weekly spend digest: total cost, top sessions, cost by tool, watchdog savings.

agent-strace team-report [--since DATE] [--until DATE] [--by author|branch|pr] [--export text|csv|json] [--outlier-threshold N]

Team cost attribution across recorded sessions. By default it groups spend by git author, using the last author of modified files when git is available. If git is unavailable or a file has no history, it falls back to session attribution and the local user.

agent-strace cognitive-debt [--session ID] [--since DATE] [--until DATE]
                            [--by author|branch] [--threshold N]
                            [--format text|json] [--github-token TOKEN]

Measure unreviewed agent-written code from trace file-write events and local git history. The report works without a GitHub token; when git history is unavailable it still reports agent-written lines and treats review evidence as unknown.

agent-strace watch --rules cognitive-debt:0.8 enables a live rule that alerts when a session has modified files that have not yet had human review.

agent-strace context-score [--file AGENTS.md] [--history N] [--compare]
                           [--min-sessions N] [--format text|json]

Score AGENTS.md, CLAUDE.md, or GEMINI.md from actual session outcomes. The command groups sessions by context-file hashes recorded by config-watch, then compares cost efficiency, tool efficiency, lint findings, and scope adherence between versions. If no version history exists, it reports current-version stats only.

agent-strace standup [--session SESSION_ID]

Structured standup from a session trace. No LLM required. Covers files touched, approaches tried, dependencies added, TODOs written.

agent-strace freshness [--since DATE] [--scope GLOB]

Check how stale the agent's last view of the codebase is. Reports files changed since last session and a freshness score 0–100.

agent-strace oncall --rotation-start DATE [--scope GLOB]

Cross-reference agent-modified files against git history to find gaps before a rotation.

agent-strace curve [--min-sessions N] [--export csv]

Personal agent cost-efficiency curve by task type. Verdict per type: efficient / over sweet spot / do this yourself.

agent-strace inflation [--compare MODELS] [--sessions N]

Measure tokenizer cost impact of switching model versions. No API calls required.

agent-strace optimize [--target FILE] [--dataset NAME] [--apply]
                      [--base-url URL] [--model MODEL] [--api-key KEY]

Cluster failures by root cause and propose additions to AGENTS.md or any instruction file. Three built-in heuristic patterns require no LLM.

agent-strace config-watch snapshot [--label TEXT] [--watch PATH]
agent-strace config-watch check [--format text|json] [--watch PATH]
agent-strace config-watch history [--format text|json]
agent-strace config-watch affected [--since DURATION] [--format text|json]

Track changes to AGENTS.md and other config files. check exits 1 when config has changed (CI gate).

agent-strace export <session-id> [--format json|csv|ndjson|otlp|otlp-genai|eu-ai-act]
                    [--endpoint URL] [--header KEY:VALUE] [--service-name NAME]
                    [--anonymize] [--scores] [--metrics] [--backend otlp|langfuse]
                    [--all] [--since DURATION_OR_DATE] [--until DATE] [--output FILE]

Export a session. See production.md for per-backend OTLP setup.

--format eu-ai-act writes a structured JSON package with Article 12 logging evidence, Article 13 transparency documentation, hash-chain integrity metadata, and event-level line hashes for agent-strace verify --from-export.

agent-strace share <session-id> [-o FILE]

Generate a self-contained HTML report. No server needed.

agent-strace sample [--strategy worst|diverse|recent|random] [--n N]
                    [--deduplicate] [--seed N] [--output FILE]

Export sessions as JSONL for eval datasets. Compatible with LangSmith, Braintrust, and custom eval frameworks.

agent-strace server [--port N] [--host HOST] [--storage DIR] [--auth-key KEY]
agent-strace server keygen

Start a server-side event collector. See server.md.

keygen prints a new ast_-prefixed API key to stdout. Set AGENT_STRACE_AUTH_KEY on the client side to inject the header automatically into all outbound collector requests.

agent-strace auto [--framework NAME] [--detect] -- <command>

Run a command with auto-instrumentation. See integrations.md.

agent-strace mcp [--transport stdio|http] [--port N]

Start an MCP server that exposes your session store as queryable tools for a debugging agent.

agent-strace a2a-tree [session-id] [--format text|json]

Visualise the A2A agent call graph. Exports as OTLP spans for Jaeger, Tempo, or any OpenTelemetry backend.

agent-strace identity show
agent-strace identity sign <session-id>
agent-strace identity verify <session-id>

Machine identity for agent sessions. show creates a persistent identity (stored in ~/.agent-strace/identity.json) if one does not exist. sign attaches an HMAC signature to a session. verify checks the signature.

Use machine identity to prove which machine produced a session — useful for compliance and multi-machine deployments.

agent-strace annotate <session-id> [--event ID] [--at OFFSET] [--note TEXT] [--label LABEL]
                      [--author NAME] [--list] [--delete ANNOTATION_ID]
                      [--filter-label LABEL] [--filter-author AUTHOR] [--since Nd]
                      [--export-format json]

Add notes, labels, and bookmarks to session events. Annotations appear in shared HTML reports.

agent-strace retention status
agent-strace retention clean [--dry-run] [--max-age-days N] [--max-sessions N] [--max-size-mb N]

Enforce data retention policies. Configure via .agent-strace.yaml:

retention:
  max_age_days: 30
  max_sessions: 1000
  max_size_mb: 500
  on_delete: log

The agent-trace eval composite action runs evals in CI, posts a scored table to the GitHub Actions step summary, and exits non-zero on regression.

- uses: Siddhant-K-code/agent-trace@gha-v1
  with:
    config: .agent-evals.yaml
    baseline: .agent-evals-baseline.json
    tolerance: "0.05"
    save-baseline: "false"

Trace artifacts are uploaded automatically under the agent-traces artifact name.

Marketplace listing