Command reference

August 17, 2026 · View on GitHub

Full flag reference for every agent-strace command.

Session capture

`record`

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

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

Flag	Description
`--name NAME`	Label for the session
`--parent SESSION`	Link this session as a child of a parent session
`--redact`	Strip secrets before writing to disk; kept for compatibility because this is now the default
`--no-redact`	Disable automatic secret redaction
`--mask`	Mask PII (email, phone, CC, SSN)

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

`record-http`

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

`setup`

agent-strace setup [--cli claude|codex|gemini|cursor|copilot|all]
                    [--redact | --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.

Flag	Default	Description
`--cli PROVIDER`	`claude`	Configure `claude`, `codex`, `gemini`, `cursor`, `copilot`, or `all`
`--redact`	on	Explicitly enable secret redaction in generated hook commands
`--no-redact`	off	Disable automatic secret redaction in generated hook commands
`--global`	off	Compatibility flag; Claude setup already targets the user-level settings file

`hook`

agent-strace hook [--provider claude|codex|gemini|cursor|copilot] <event>

Internal hook receiver used by the configurations generated by setup. It reads one provider hook payload as JSON from standard input and appends the normalized event to the active session. --provider defaults to claude.

Event	Recorded data
`session-start`	Start or resume the provider-scoped session
`user-prompt`	User prompt text and available provider metadata
`pre-tool`	Tool name and input before execution
`post-tool`	Successful tool result and duration when it can be linked to the call
`post-tool-failure`	Failed tool result as an error event
`file-write`	Provider-reported file edit
`stop`	Assistant response or provider stop metadata
`session-end`	Finish the active session and clear its hook state

Provider-specific aliases in generated configurations are normalized to these events. Prefer agent-strace setup --cli PROVIDER over invoking hook manually. See setup.md for provider event coverage and generated configuration paths.

`telemetry`

agent-strace telemetry [status|enable|disable]

Show or change the anonymous product telemetry preference. Telemetry is enabled by default outside CI. disable persists an opt-out and deletes the local anonymous installation ID. DO_NOT_TRACK=1 or AGENT_STRACE_TELEMETRY=0 always disables collection; AGENT_STRACE_TELEMETRY=1 explicitly enables it, including in CI. See telemetry.md for the exact event schema and maintainer setup.

`import`

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

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

Replay and inspection

`replay`

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

Flag	Description
`--format html`	Export self-contained HTML viewer
`--live`	Replay with real-time delays
`--speed N`	Speed multiplier for `--live` (default: 1.0)
`--filter TYPES`	Comma-separated event types to show
`--limit N`	Cap at N events
`--expand-subagents`	Inline subagent sessions under parent tool_call
`--tree`	Show session hierarchy without full replay

`tree`

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.

`list`

agent-strace list [--tenant ID]

List all captured sessions with ID, timestamp, duration, tool calls, and errors. --tenant ID performs an exact tenant match before listing metadata.

`inspect`

agent-strace inspect <session-id>

Dump full session as JSON (meta + events).

`stats`

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

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

Understanding sessions

`explain`

agent-strace explain [session-id]

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

`timeline`

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

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

Flag	Default	Description
`--format`	`text`	`text` or `json`
`--model`	`sonnet`	Pricing model: `sonnet`, `opus`, `haiku`, `gpt4`, `gpt4o`

`why`

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

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

`cost`

agent-strace cost [session-id] [--model MODEL] [--input-price N] [--output-price N]
agent-strace cost --breakdown provider [--since DATE_OR_DURATION] [--csv] [--live-pricing]
agent-strace cost --tenant ID [--since DATE_OR_DURATION]

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

--breakdown provider aggregates all stored sessions in the selected window by inferred provider and model. It uses actual recorded token counters and a bundled, dated pricing snapshot, so the default path makes no network calls. CSV output has the stable columns provider, model, session_id, input_tokens, output_tokens, and cost_usd.

Flag	Default	Description
`--model`	`sonnet`	`sonnet`, `opus`, `haiku`, `gpt4`, `gpt4o`
`--input-price`	—	Custom input price per 1M tokens (requires `--output-price`)
`--output-price`	—	Custom output price per 1M tokens (requires `--input-price`)
`--breakdown provider`	—	Aggregate Anthropic, OpenAI, AWS Bedrock, and Gemini usage
`--since DATE_OR_DURATION`	`30d`	ISO date or duration such as `7d`, `24h`, or `2w`
`--csv`	off	Emit raw per-session/model rows instead of the dashboard
`--live-pricing`	off	Request authoritative live rates; error when compatible provider APIs are unavailable rather than scrape or guess
`--tenant ID`	—	Scope an explicit session or aggregate the selected time window to one tenant

Pricing estimates exclude caching, batch discounts, regional or service-tier differences, long-context premiums, and non-token charges. To update the bundled table, check the official URLs in PRICING_SOURCES, update PRICING and _MODEL_PROVIDERS, advance PRICING_SNAPSHOT_DATE, and extend tests/test_provider_cost.py for every added model family.

`diff`

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

Compare two sessions structurally.

Flag	Description
`--semantic`	Compare by outcome, not event order
`--compare`	Side-by-side table with verdict (cost, duration, tools, errors)

`compare`

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.

`token-budget`

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

Check token usage against model context limit.

`compaction`

agent-strace compaction [SESSION_ID] [--diff] [--behavior-diff]
                         [--compaction-threshold RATIO]

Detect provider-reported input-token drops between consecutive model requests and report the context discarded by compaction.

Flag	Description
`SESSION_ID`	Session ID or prefix (default: latest)
`--diff`	Classify constraints, decisions, and file context as survived or likely dropped
`--behavior-diff`	Compare lint findings, re-reads, loops, and exploration around compaction
`--compaction-threshold RATIO`	Minimum token drop ratio (default: `0.50`)

See the context compaction guide for interpretation and live checkpoint setup.

Control and protection

`watch`

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]
                   [--compaction-checkpoint] [--checkpoint-at RATIO] [--dry-run]
                   [--tenant-id ID]

Live session monitor with kill-switch rules.

Flag	Description
`--timeout DURATION`	Kill after duration (e.g. `30m`, `2h`)
`--budget $N`	Kill when spend exceeds N dollars
`--loop-threshold N`	Alert when the same tool call and arguments repeat N times; default is 3
`--loop-window N`	Number of recent events to scan for repeated identical tool calls; default is 10
`--on-violation terminal\|file\|kill`	Action when a rule fires
`--on-death CMD`	Command to run after kill (receives `{post_mortem_path}`)
`--compaction-checkpoint`	Write a recovery checkpoint before context saturation
`--checkpoint-at RATIO`	Context fill ratio that triggers a checkpoint (default: `0.80`)
`--policy FILE`	Scope policy file to enforce (default: `.agent-scope.json`)
`--rules FILE_OR_BUILTINS`	JSON/YAML rules file, or comma-separated built-ins such as `mcp-poisoning,loop:3/10,budget:\$5,timeout:30m,cognitive-debt:0.8`
`--stream-to URL`	Stream events to HTTP endpoint in real-time
`--dry-run`	Evaluate rules without acting
`--tenant-id ID`	Tag the session and all events; defaults to `AGENT_STRACE_TENANT_ID`

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

`mcp-scan`

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.

Flag	Description
`--session ID`	Scan one session by ID or prefix
`--since DURATION_OR_DATE`	Scan recent sessions since a duration or ISO date (default: `7d`)
`--watch`	Tail the selected/latest session and alert as new events arrive
`--patterns FILE`	Add regex patterns from a plain text file
`--project-root DIR`	Root used to detect writes outside the project (default: `.`)
`--format text\|json`	Output format (default: `text`)

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.

`audit`

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"] }
}

`verify`

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.

`policy`

agent-strace policy [generate] [SESSION_ID ...] [--output FILE] [--dry-run]
agent-strace policy backtest [--policy FILE] [--days N] [--show-sessions] [--format text|json]
agent-strace policy diff OLD_POLICY NEW_POLICY [--days N] [--format text|json]
agent-strace policy coverage [--policy FILE] [--days N] [--show-uncovered] [--format text|json]

Generate .agent-scope.json from observed traces, or evaluate a proposed policy offline against stored sessions before enforcement. The existing bare policy form remains an alias for policy generate.

Command / flag	Description
`generate [SESSION_ID ...]`	Suggest a policy from selected sessions, or all sessions by default
`backtest`	Report per-rule matches and calls/sessions that would be blocked
`diff OLD NEW`	Compare both policies over the identical history window
`coverage`	Measure the fraction of tool calls matched by an explicit rule
`--policy FILE`	Policy to evaluate (default: `.agent-scope.json`)
`--days N`	Evaluate sessions started in the last N days (default: `30`)
`--show-sessions`	List session IDs containing calls that would be blocked
`--show-uncovered`	List calls that did not match an explicit rule
`--format text\|json`	Human-readable or machine-readable output

Backtesting is read-only and uses the same matching semantics as audit; it never enforces a policy or contacts a remote service.

`audit-tools`

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

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

`postmortem`

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.

Flag	Description
`--list`	List crashed sessions and write missing `postmortem.md` files
`--stale-after SECONDS`	Heartbeat age before a session is treated as crashed (default: 30)
`--agents-md FILE`	AGENTS.md file used for instruction-violation checks

`approval`

agent-strace approval list [--state pending|approved|denied]
agent-strace approval show <request-id>
agent-strace approval approve <request-id> [--by NAME] [--no-resume]
agent-strace approval deny <request-id> [--reason TEXT] [--by NAME] [--no-kill]

Human-in-the-loop approval queue. A policy rule with action=require_approval pauses the agent while it waits for a decision. Approving resumes the agent with SIGCONT by default; denying terminates it with SIGTERM by default.

Command/flag	Description
`list --state STATE`	List requests, optionally filtered to `pending`, `approved`, or `denied`
`show REQUEST_ID`	Show a request by ID or ID prefix
`approve REQUEST_ID`	Approve a pending request
`approve --by NAME`	Record the approver name
`approve --no-resume`	Approve without sending `SIGCONT` to the agent
`deny REQUEST_ID`	Deny a pending request
`deny --reason TEXT`	Record the reason for denial
`deny --by NAME`	Record the reviewer name
`deny --no-kill`	Deny without sending `SIGTERM` to the agent

`rbac`

agent-strace rbac assign (--user EMAIL | --group GROUP) --role ROLE [--workspace ID] [--by NAME]
agent-strace rbac revoke (--user EMAIL | --group GROUP) [--workspace ID]
agent-strace rbac list [--workspace ID]
agent-strace rbac check --user EMAIL --action ACTION [--workspace ID]

Manage org-level and workspace-scoped role assignments. Org roles are owner, admin, member, viewer, and machine. Workspace roles are workspace:admin, workspace:member, and workspace:viewer.

Flag	Description
`--user EMAIL`	Select a user principal for `assign` or `revoke`; required unless `--group` is used
`--group GROUP`	Select a group principal for `assign` or `revoke`; required unless `--user` is used
`--role ROLE`	Role to assign; required for `assign`
`--workspace ID`	Assign, revoke, list, or check in a workspace context; omit for org-level operations
`--by NAME`	Record the assigner name in the audit trail
`--action ACTION`	Authorization action to check; required for `check`

Supported actions are read_sessions, run_agent, annotate, manage_policies, manage_identities, manage_workspaces, export_compliance, manage_rbac, manage_billing, and manage_sso. Unknown actions require the effective owner role.

`auth`

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.

`apply`

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.

`config-diff`

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.

`workspace`

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.

`compliance`

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.

This is the legacy compatibility command. For a privacy-minimized, explicitly heuristic evidence crosswalk with current versioned framework manifests, use compliance-report. The two output schemas and claims are intentionally separate.

Framework	Coverage
`eu-ai-act`	Transparency, human oversight, data governance
`soc2`	Access control, availability, confidentiality
`hipaa`	PHI handling, audit trail, access logs

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]

`compliance-report`

agent-strace compliance-report --framework aicpa-tsc|owasp-agentic|eu-ai-act
    [--since UTC_OR_DURATION] [--until UTC]
    [--format json|sarif|pdf] [--output FILE]
    [--policy FILE] [--rescan [installed|FILE]]

Build a privacy-minimized evidence crosswalk from the flat trace store and all workspace stores. It reports only evidence_observed, risk_signal, gap, or not_assessed. These are evidence labels, not control conclusions. JSON is the authoritative output; SARIF and PDF are deterministic limited projections. See the compliance evidence guide for interpretation, framework sources, privacy behavior, and limitations.

Flag	Description
`--framework ID`	Required crosswalk: `aicpa-tsc`, `owasp-agentic`, or `eu-ai-act`
`--since VALUE`	Inclusive UTC timestamp/date or duration such as `90d`; default is `90d`
`--until UTC`	Exclusive UTC timestamp/date; default is the fixed snapshot time
`--format FORMAT`	`json` (authoritative), `sarif`, or `pdf`; default is `json`
`--output FILE`, `-o FILE`	Atomically write a nonsymlinked private file with mode `0600`; required for PDF
`--policy FILE`	Evaluate a bounded local policy at report time; outcomes are `would_allow`/`would_deny`, never historical authorization
`--rescan [installed\|FILE]`	With no value or `installed`, explicitly reuse the installed manifest; a file selects a local versioned JSON manifest. Performs no network, CVE, or SBOM scan

PDF support is optional: pip install 'agent-strace[pdf]'.

`audit-readiness`

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.

Analysis across sessions

`dashboard`

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"

`drift`

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

`baseline`

agent-strace baseline update [--since DAYS] [--output FILE]
agent-strace baseline check [session-id] [--baseline FILE] [--sigma N]
agent-strace baseline show [--baseline FILE]

Build and inspect a statistical profile of completed sessions, then compare a session with that profile. The default profile path is .agent-traces/baseline.json.

Command or flag	Default	Description
`update`	—	Build a profile from completed sessions in the selected time window
`update --since DAYS`	`30`	Include sessions started within the last number of days
`update --output FILE`	`.agent-traces/baseline.json`	Write the profile to a custom path
`check [session-id]`	latest	Check a session ID or prefix against the profile
`check --baseline FILE`	`.agent-traces/baseline.json`	Read a custom profile
`check --sigma N`	`2.0`	Flag metrics more than N standard deviations from the mean
`show --baseline FILE`	`.agent-traces/baseline.json`	Display profile statistics from a custom path

The profile tracks cost, tool calls, duration, error rate, and LLM requests. check exits with status 1 for an anomalous session, a missing session, or a missing or unreadable baseline, so it can be used as a CI gate. See production.md for an example.

`fingerprint`

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.

`freeze`

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

`lint`

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, and post-compaction regressions. The post-compaction-regression rule warns when re-reading, exploration, context saturation, or other lint findings increase after a detected compaction.

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

`eval`

agent-strace eval [session-id] [--config FILE] [--baseline FILE]
                  [--save-baseline FILE] [--tolerance N] [--format table|json]
agent-strace eval run [session-id]
agent-strace eval compare <session-a> <session-b>
agent-strace eval ci

Gate the latest or selected session against named, raw-value criteria. The direct command exits 1 when a criterion fails or a score regresses beyond the allowed tolerance, making it suitable for CI. The run, compare, and ci subcommands remain available for legacy normalized scorers.

Configure named criteria in .agent-evals.yaml:

evals:
  - name: cost-ceiling
    scorer: cost_usd
    threshold: 0.50
    fail_on: above
  - name: no-errors
    scorer: error_count
    threshold: 0
    fail_on: above
  - name: task-completed
    scorer: session_status
    expected: completed
    fail_on: not_equal

Built-in scorers are cost_usd, error_count, session_status, redundant_read_ratio, tool_call_count, context_fill_ratio, duration_seconds, and lint_violations. A custom Python callable can be referenced as package.module:function and receives session events plus any criterion-specific parameters it declares.

Flag	Default	Description
`--config FILE`	`.agent-evals.yaml`	Named criteria configuration
`--baseline FILE`	—	Compare current raw scores with a saved baseline
`--save-baseline FILE`	—	Save current scores as versioned JSON
`--tolerance N`	`0`	Allowed fractional regression from the baseline
`--format table\|json`	`table`	Human-readable or machine-readable output

`budget-report`

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

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

`team-report`

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.

Flag	Description
`--since DATE`	Start of reporting window. Accepts ISO dates or durations like `7d`; default is 7 days ago
`--until DATE`	End of reporting window. Accepts ISO dates or durations like `7d`; default is now
`--by author	branch
`--export text	csv
`--outlier-threshold N`	Flag sessions whose cost is above `N` times the report average; default is `2.0`

`org-report`

agent-strace org-report [--month YYYY-MM] [--team SELECTOR]
                         [--format text|json|html] [--anonymize]
                         [--model MODEL] [-o FILE]
                         [--endpoint URL] [--auth-key-file FILE]
                         [--ca-file FILE] [--allow-insecure-http]

Build a monthly organization digest from the flat trace directory plus all workspace stores, or from one explicitly selected authenticated collector. Spend is an offline estimate for sessions with usable event data; the report shows its coverage and labels averages as per cost-estimated session. Task types and anomaly callouts are heuristics, not completion or efficiency measurements. See the organization reporting guide for the security boundary and interpretation details.

Flag	Description
`--month YYYY-MM`	Half-open UTC calendar month; default is the current UTC month
`--team SELECTOR`	Exact team tag or workspace. Use `tag:NAME` or `workspace:NAME` to resolve a name collision
`--format text\|json\|html`	Terminal text, strict versioned JSON, or self-contained static HTML
`--anonymize`	Replace team/workspace and attributed identity labels with deterministic aliases local to this report
`--model MODEL`	Bundled offline pricing model; default is `sonnet`
`--output FILE`, `-o FILE`	Atomically write the complete report; symlinked destinations are refused
`--endpoint URL`	Explicit collector base URL. This command never infers it from `AGENT_STRACE_ENDPOINT`
`--auth-key-file FILE`	Read the collector bearer key from a file; otherwise use `AGENT_STRACE_AUTH_KEY`
`--ca-file FILE`	Trust a custom CA bundle for the HTTPS collector
`--allow-insecure-http`	Opt in to plain HTTP for a non-loopback collector

`cognitive-debt`

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.

Flag	Description
`--session ID`	Score one session by ID or prefix
`--since DATE`	Start of reporting window. Accepts ISO dates or durations like `30d`; default is `30d`
`--until DATE`	End of reporting window. Accepts ISO dates or durations like `7d`; default is now
`--by author	branch`
`--threshold N`	Flag sessions above this debt score; default is `0.7`
`--format text	json`
`--github-token TOKEN`	Optional GitHub token for merged PR review/comment enrichment; local git works without it

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.

`context-score`

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.

Flag	Description
`--file PATH`	Context file to score; defaults to the first existing AGENTS.md, CLAUDE.md, or GEMINI.md
`--history N`	Days of session history to analyse; default is `30`
`--compare`	Compare current context version against the previous version
`--min-sessions N`	Minimum sessions per version before scoring; default is `5`
`--format text	json`

`standup`

agent-strace standup [--session SESSION_ID]

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

`freshness`

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.

`oncall`

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

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

`curve`

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.

`inflation`

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

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

`optimize`

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.

`config-watch`

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

Export and integration

`export`

agent-strace export <session-id> [--format json|csv|ndjson|otlp|otlp-genai|temporal|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 temporal emits OTLP/HTTP JSON using the upstream W3C trace ID and Temporal activity parent span previously captured by watch. It can be written to a file or sent directly with --endpoint. See Temporal workflows.

--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]
agent-strace share --assignment [session-id] --output submission.zip

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

--assignment instead creates a deterministic, privacy-minimized ZIP with a sanitized trace, offline replay, derived stats/cost/lint reports, and a versioned manifest. It cannot be combined with --stdout, --open, or --postmortem. The output name must have a lowercase .zip suffix and is atomically written with owner-only permissions. See the assignment review guide for the privacy boundary and interpretation limits.

`score`

agent-strace score SUBMISSION.zip --rubric FILE [--format text|json]
agent-strace score DIRECTORY --rubric FILE --compare [--format text|json]

Validate an assignment bundle without extracting it, then apply a strict, deterministic process-telemetry rubric. Comparison mode considers only direct children with a lowercase .zip suffix, anonymizes input filenames, rejects duplicate bundles, and gives equal scores the same rank with digest-stable tie ordering.

Flag	Description
`SUBMISSION.zip`	One canonical assignment bundle
`DIRECTORY`	Directory of direct lowercase `.zip` files; requires `--compare`
`--rubric FILE`	Required strict assignment rubric; symbolic links are rejected
`--compare`	Score and rank a bounded directory batch
`--format text\|json`	Human-readable table/detail or versioned JSON (default: `text`)

Invalid archives and rubrics exit non-zero. A low rubric score is a report for human review, not a pass/fail hiring gate. See hiring.md.

`pr-comment`

agent-strace pr-comment [SESSION_ID] [--dry-run] [--platform github|gitlab]
                           [--repo OWNER/REPO] [--pr NUMBER]
                           [--api-url URL] [--share-url URL]

Post a structured session summary to the current branch's open pull request or merge request. The comment includes duration, cost, model, status, tool calls, files changed, lint findings, errors, redundant reads, and replay commands. An embedded marker makes repeated runs update the existing comment.

Flag	Description
`SESSION_ID`	Explicit session ID or prefix; otherwise use sessions attributed to the current branch
`--dry-run`	Render locally without resolving a PR or making a network request
`--platform github\|gitlab`	Review platform (default: `github`)
`--repo OWNER/REPO`	Override the repository/project inferred from CI or the git remote
`--pr NUMBER`	Override the PR/MR number inferred from CI or the current branch
`--api-url URL`	GitHub Enterprise or self-hosted GitLab API base URL
`--share-url URL`	Optional HTML replay URL; `{session_id}` is replaced for each session

GitHub uses GITHUB_TOKEN or GH_TOKEN. GitLab requires a writable project or personal access token in GITLAB_TOKEN, GITLAB_ACCESS_TOKEN, or PRIVATE_TOKEN; GitLab job tokens cannot write merge-request notes. Tokens are read only from the environment.

`sample`

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.

`server`

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.

Flag	Description
`--port N`	Port to listen on (default: 4317)
`--host HOST`	Host to bind to (default: 0.0.0.0)
`--storage DIR`	Trace storage directory (default: `$AGENT_STRACE_STORAGE` or `.agent-traces`)
`--auth-key KEY`	Require `Authorization: Bearer KEY` on all requests (also read from `AGENT_STRACE_AUTH_KEY`)

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.

`auto`

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

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

`mcp`

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

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

`a2a-tree`

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.

`identity`

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.

Annotations and metadata

`annotate`

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.

Flag	Description
`--event ID`	Event ID to annotate
`--at OFFSET`	Time offset to annotate (e.g. `2m14s`, `1:30`)
`--note TEXT`	Text note to attach
`--label LABEL`	Label chip (`root-cause`, `decision`, `retry`, `fix`, `question`)
`--author NAME`	Author name or email
`--list`	List all annotations for the session
`--delete ID`	Delete an annotation by ID
`--filter-label LABEL`	Filter `--list` by label
`--filter-author AUTHOR`	Filter `--list` by author
`--since Nd`	Filter `--list` to annotations created in the last N days
`--export-format json`	Output `--list` as JSON instead of terminal text

`retention`

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

`tenant`

agent-strace tenant report [--month YYYY-MM] [--model MODEL] [--format text|json]
agent-strace tenant export ID [--format json] [--output FILE]
agent-strace tenant delete ID --confirm

Report monthly cost allocation, produce a tenant-scoped subject access export, or irreversibly erase all local trace data for one tenant. Deletion requires --confirm and appends a minimal audit record. See the multi-tenant deployment guide for isolation and GDPR notes.

GitHub Actions

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.

permissions:
  contents: read
  pull-requests: write

steps:
  - uses: Siddhant-K-code/agent-trace@v0.93.1
    with:
      config: .agent-evals.yaml
      baseline: .agent-evals-baseline.json
      tolerance: "0.05"
      post-pr-comment: "true"
      github-token: ${{ secrets.GITHUB_TOKEN }}

Input	Default	Description
`config`	`.agent-evals.yaml`	Eval config file
`baseline`	none	Baseline scores file for regression gating
`save-baseline`	none	Path to write current scores as a new baseline
`tolerance`	`0.05`	Max allowed score regression (0.0 to 1.0)
`trace-dir`	`.agent-traces`	Session storage directory
`python-version`	`3.12`	Python version
`install-extras`	none	Optional extras, e.g. `openai,anthropic`
`post-pr-comment`	`false`	Post or update the structured session summary on the PR
`github-token`	none	Token for PR comments; pass `${{ secrets.GITHUB_TOKEN }}`

Output	Description
`passed`	`true` if all scorers passed
`summary-path`	Path to the written eval summary markdown

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

Marketplace listing