Skip to content
Back to search

agent-trace

AgentTrace plugins for agent observability.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/siddhant-k-code--agent-trace/badge.svg)](/listings/siddhant-k-code--agent-trace)

HTML

<a href="/listings/siddhant-k-code--agent-trace"><img src="/api/listings/siddhant-k-code--agent-trace/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Option 1: CLI hooks.** Captures prompts, responses, and hook-visible tool calls

agent-strace setup             # Claude Code hooks for ~/.claude/settings.json
agent-strace setup --cli claude --verify # check Claude Code hooks + CLI, not live capture
agent-strace setup --cli codex # OpenAI Codex hooks in ~/.codex/hooks.json
agent-strace setup --cli codex --verify # check Codex user hooks + CLI, not live capture
agent-strace setup --cli gemini # Gemini CLI extension under ~/.gemini/extensions
agent-strace setup --cli cursor # Cursor project hooks in .cursor/hooks.json
agent-strace setup --cli copilot # GitHub Copilot CLI hooks in ~/.copilot/hooks
agent-strace list              # list sessions

Provider coverage and known gaps: [docs/capture-matrix.md](docs/capture-matrix.md)

Claude Code plugin

After installing `agent-strace`, install the repository as a native Claude Code plugin to enable tracing hooks plus the shared trace analyst agent and skill:

claude plugin marketplace add Siddhant-K-code/agent-trace
claude plugin install agent-strace@agent-trace

See the [Claude Code plugin guide](docs/claude-code-plugin.md) for verification, updates, uninstall steps, privacy boundaries, provider gaps, and release publication.

GitHub Copilot CLI plugin

After installing `agent-strace`, install the repository as a Copilot CLI plugin to enable tracing hooks plus the trace analyst agent and skill:

copilot plugin marketplace add Siddhant-K-code/agent-trace
copilot plugin install agent-strace@agent-trace

Restart Copilot CLI, then use `/agent` to select `agent-strace:trace-analyst`. Traces are written to `.agent-traces/` in the repository you opened. Do not also run `agent-strace setup --cli copilot`, which would register duplicate hooks.

See the [Copilot CLI plugin guide](docs/copilot-plugin.md) for verification, updates, and usage.

**Option 2: MCP proxy.** Wraps any MCP server, works with Cursor, Windsurf, and Copilot Desktop MCP servers

agent-strace record -- npx -y @modelcontextprotocol/server-filesystem /tmp
agent-strace replay

**Option 3: Python decorator.** No MCP required.

from agent_trace import trace_tool, start_session, end_session

start_session(name="my-agent")

@trace_tool
def search_codebase(query: str) -> str:
    return search(query)

end_session()

Sessions go to `$AGENT_TRACE_DIR` when set, else `.agent-traces`; an explicit `start_session(trace_dir=...)` wins.

Full setup guide: [docs/setup.md](docs/setup.md). Machine-wide install for platform teams: [docs/platform-install.md](docs/platform-install.md)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines
  1. {
  2. "name": "agent-trace",
  3. "description": "AgentTrace plugins for agent observability.",
  4. "owner": {
  5. "name": "Siddhant Khare",
  6. "email": "siddhantkhare2694@gmail.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "agent-strace",
  11. "source": "./",
  12. "description": "Capture and investigate Claude Code agent sessions with local AgentTrace hooks.",
  13. "version": "0.115.2"
  14. }
  15. ]
  16. }
README.md · README · 298 lines
  1. # agent-trace
  2. [![PyPI](https://img.shields.io/pypi/v/agent-strace)](https://pypi.org/project/agent-strace/)
  3. [![Python](https://img.shields.io/pypi/pyversions/agent-strace)](https://pypi.org/project/agent-strace/)
  4. [![CI](https://github.com/Siddhant-K-code/agent-trace/actions/workflows/test.yml/badge.svg)](https://github.com/Siddhant-K-code/agent-trace/actions/workflows/test.yml)
  5. [![GitHub Marketplace](https://img.shields.io/badge/Marketplace-agent--trace%20eval-blue?logo=github)](https://github.com/marketplace/actions/agent-trace-eval)
  6. [![Open VSX](https://img.shields.io/open-vsx/v/Siddhant-K-code/agent-strace)](https://open-vsx.org/extension/Siddhant-K-code/agent-strace)
  7. [![VS Marketplace](https://img.shields.io/badge/VS%20Marketplace-v0.3.0-blue?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=Siddhant-K-code.agent-strace)
  8. [![License](https://img.shields.io/github/license/Siddhant-K-code/agent-trace)](LICENSE)
  9. [![PyPI Downloads](https://static.pepy.tech/personalized-badge/agent-strace?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/agent-strace)
  10. **Local evidence and replay for coding agents.**
  11. `agent-strace` records what a coding agent did in a session (prompts, tool calls, file operations, commands, failures) as local files, then does three jobs:
  12. 1. **Replay what happened.** [`replay`](docs/commands.md#replay) shows the session in order. [`explain`](docs/commands.md#explain) summarizes it in phases.
  13. 2. **See what the trace could not prove.** [`health`](docs/evidence-health.md) rates the evidence `healthy`, `partial`, `unknown`, or `invalid`, with observed gaps and known provider capture limits.
  14. 3. **Attach safe evidence to review.** [`review`](docs/review.md) checks a PR's reviewability from its authoring session. [`share`](docs/commands.md#share) writes a privacy-minimized HTML evidence packet; `share --dry-run` previews what it would disclose.
  15. ```bash
  16. uv tool install agent-strace
  17. agent-strace setup --cli copilot # or claude, codex, gemini, cursor; then use the agent
  18. agent-strace replay # latest session
  19. agent-strace health # what the capture missed
  20. agent-strace review # reviewability of this branch
  21. ```
  22. Works with Claude Code, Codex, Copilot CLI, Gemini CLI, Cursor, and any MCP server, plus partial [Copilot cloud agent capture](docs/copilot-cloud-agent.md). Python 3.10+ standard library only. Secret redaction is on by default. Start with the [docs index](docs/index.md), [provider guides](docs/capture-matrix.md), and [PR evidence workflow](docs/ai-agent-pr-evidence.md).
  23. ![Terminal output of agent-strace replay, health and review on a real GitHub Copilot CLI session that fixes a small bug: replay lists the prompt, tool calls and results; health reports the evidence status and the provider's capture gaps; review reports rationale, scope, validation, stewardship and evidence health for the branch.](assets/demo.svg)
  24. > [!WARNING]
  25. > Experimental. Do not treat it as a production security boundary without your own threat model, controls, and testing.
  26. ## Try it without setup: which skills never load
  27. ```bash
  28. uvx agent-strace skills --from-claude
  29. ```
  30. This reads the Claude Code transcripts already on your machine (`~/.claude/projects`), writes no persistent trace store (it uses a temporary directory deleted on exit), and reports each skill as available, loaded, followed, and what happened after the load. It reports counts, not a score, and only for what the sessions recorded. `--from-copilot` and `--from-codex` do the same for GitHub Copilot and Codex session logs, using the skill list each session recorded. For other agents, record sessions first, then run `agent-strace skills`. A never-loaded skill is a lead, not a verdict: no task may have needed it. Test it with [`skills eval`](docs/skills-eval.md). Guide: [docs/skills.md](docs/skills.md).
  31. Sample output (139 recorded sessions, trimmed):
  32. ```text
  33. Skills across 139 sessions since 2025-11-09. Availability reflects the filesystem now, not session time.
  34. skill avail loaded load rate user model median t pre-edit follow tests
  35. ------------------------------------------------------------------------------------------
  36. frontend-design 139 2 2/139 0 3 3.1h 1/2 0/2 0/2
  37. grilling 139 0 0/139 0 0 - - - -
  38. web-design-guidelines 139 0 0/139 0 0 - - - -
  39. Never loaded (available in >= 5 sessions, loaded in 0):
  40. grilling (available in 139 sessions)
  41. web-design-guidelines (available in 139 sessions)
  42. ```
  43. ## Quick start
  44. **Option 1: CLI hooks.** Captures prompts, responses, and hook-visible tool calls
  45. ```bash
  46. agent-strace setup # Claude Code hooks for ~/.claude/settings.json
  47. agent-strace setup --cli claude --verify # check Claude Code hooks + CLI, not live capture
  48. agent-strace setup --cli codex # OpenAI Codex hooks in ~/.codex/hooks.json
  49. agent-strace setup --cli codex --verify # check Codex user hooks + CLI, not live capture
  50. agent-strace setup --cli gemini # Gemini CLI extension under ~/.gemini/extensions
  51. agent-strace setup --cli cursor # Cursor project hooks in .cursor/hooks.json
  52. agent-strace setup --cli copilot # GitHub Copilot CLI hooks in ~/.copilot/hooks
  53. agent-strace list # list sessions
  54. ```
  55. Provider coverage and known gaps: [docs/capture-matrix.md](docs/capture-matrix.md)
  56. ### Claude Code plugin
  57. After installing `agent-strace`, install the repository as a native Claude Code
  58. plugin to enable tracing hooks plus the shared trace analyst agent and skill:
  59. ```bash
  60. claude plugin marketplace add Siddhant-K-code/agent-trace
  61. claude plugin install agent-strace@agent-trace
  62. ```
  63. See the [Claude Code plugin guide](docs/claude-code-plugin.md) for verification,
  64. updates, uninstall steps, privacy boundaries, provider gaps, and release
  65. publication.
  66. ### GitHub Copilot CLI plugin
  67. After installing `agent-strace`, install the repository as a Copilot CLI plugin to enable tracing hooks plus the trace analyst agent and skill:
  68. ```bash
  69. copilot plugin marketplace add Siddhant-K-code/agent-trace
  70. copilot plugin install agent-strace@agent-trace
  71. ```
  72. Restart Copilot CLI, then use `/agent` to select
  73. `agent-strace:trace-analyst`. Traces are written to `.agent-traces/` in the
  74. repository you opened. Do not also run `agent-strace setup --cli copilot`,
  75. which would register duplicate hooks.
  76. See the [Copilot CLI plugin guide](docs/copilot-plugin.md) for verification,
  77. updates, and usage.
  78. **Option 2: MCP proxy.** Wraps any MCP server, works with Cursor, Windsurf, and Copilot Desktop MCP servers
  79. ```bash
  80. agent-strace record -- npx -y @modelcontextprotocol/server-filesystem /tmp
  81. agent-strace replay
  82. ```
  83. **Option 3: Python decorator.** No MCP required.
  84. ```python
  85. from agent_trace import trace_tool, start_session, end_session
  86. start_session(name="my-agent")
  87. @trace_tool
  88. def search_codebase(query: str) -> str:
  89. return search(query)
  90. end_session()
  91. ```
  92. Sessions go to `$AGENT_TRACE_DIR` when set, else `.agent-traces`; an explicit `start_session(trace_dir=...)` wins.
  93. Full setup guide: [docs/setup.md](docs/setup.md). Machine-wide install for platform teams: [docs/platform-install.md](docs/platform-install.md)
  94. ## What you can do
  95. ### Understand a session
  96. | Command | What it does |
  97. |---|---|
  98. | [`agent-strace replay <id>`](docs/commands.md#replay) | Replay a session in the terminal or as HTML |
  99. | [`agent-strace replay <id-a> --diff <id-b>`](docs/commands.md#replay) | Side-by-side session comparison with tool args and output delta |
  100. | [`agent-strace health <id>`](docs/commands.md#health) | Evidence health with observed gaps and capture-matrix provider limitations |
  101. | [`agent-strace explain <id>`](docs/commands.md#explain) | Plain-English phase summary, no LLM required |
  102. | [`agent-strace timeline <id>`](docs/commands.md#timeline) | Phase-by-phase view with costs and retries |
  103. | [`agent-strace why <id> <event>`](docs/commands.md#why) | Causal chain for a specific decision |
  104. | [`agent-strace diff <id-a> <id-b>`](docs/commands.md#diff) | Structural or semantic session comparison |
  105. | [`agent-strace compare <id-a> <id-b>`](docs/commands.md#compare) | Regression report with verdict |
  106. | [`agent-strace compaction <id>`](docs/compaction.md) | Inspect context loss and behavior changes after compaction |
  107. ### Control and protect
  108. | Command | What it does |
  109. |---|---|
  110. | [`agent-strace watch`](docs/commands.md#watch) | Live monitor with kill-switch rules |
  111. | [`agent-strace watch --timeout 30m --budget 5`](docs/commands.md#watch) | Watchdog mode: kills on limit and heartbeats sessions for postmortems |
  112. | [`agent-strace mcp-scan`](docs/commands.md#mcp-scan) | Scan runtime MCP poisoning indicators |
  113. | [`agent-strace audit <id>`](docs/commands.md#audit) | Audit tool calls against a policy file |
  114. | [`agent-strace policy backtest`](docs/commands.md#policy) | Test policy impact against historical sessions |
  115. | [`agent-strace approval list`](docs/commands.md#approval) | Human-in-the-loop approval queue |
  116. | [`agent-strace rbac assign`](docs/commands.md#rbac) | Org and workspace-scoped role assignments |
  117. | [`agent-strace auth login`](docs/commands.md#auth) | SSO/OIDC login to a hosted collector |
  118. | [`agent-strace telemetry status`](docs/telemetry.md) | Inspect, disable, or re-enable anonymous CLI telemetry, on by default once its [one-time notice](docs/telemetry.md#when-sending-starts) is shown |
  119. | [`agent-strace apply`](docs/commands.md#apply) | Apply `.agent-strace.yaml` config to local store or collector |
  120. | [`agent-strace workspace new`](docs/commands.md#workspace) | Create an isolated workspace |
  121. | [`agent-strace compliance export`](docs/commands.md#compliance) | Export compliance reports (EU AI Act, SOC 2, HIPAA) |
  122. | [`agent-strace record`](docs/commands.md#record) | Strip secrets from traces before storage by default |
  123. | [`agent-strace export --anonymize`](docs/commands.md#export) | Remove PII at export time |
  124. ### Analyse across sessions
  125. | Command | What it does |
  126. |---|---|
  127. | [`agent-strace dashboard`](docs/commands.md#dashboard) | Multi-session overview |
  128. | [`agent-strace budget-report`](docs/commands.md#budget-report) | Weekly spend digest |
  129. | [`agent-strace team-report`](docs/commands.md#team-report) | Team spend by author, branch, or PR |
  130. | [`agent-strace org-report`](docs/org-report.md) | Monthly organization usage and estimated-cost digest |
  131. | [`agent-strace compliance-report`](docs/compliance-report.md) | Privacy-minimized framework evidence crosswalk |
  132. | [`agent-strace cost --breakdown provider`](docs/commands.md#cost) | Offline spend by provider and model |
  133. | [`agent-strace tenant report`](docs/tenancy.md) | Per-customer cost, export, and erasure workflows |
  134. | [`agent-strace backfill-meta`](docs/commands.md#backfill-meta) | Write missing metadata for older subagent session dirs (dry run by default) |
  135. | [`agent-strace cognitive-debt`](docs/commands.md#cognitive-debt) | Unreviewed agent-written code by session |
  136. | [`agent-strace context-score`](docs/commands.md#context-score) | Compare efficiency stats (cost, tool calls, lint, scope) across AGENTS.md/CLAUDE.md versions. Not an outcome score |
  137. | [`agent-strace skills`](docs/skills.md) | Skill adoption: available → loaded → followed → outcome (no score) |
  138. | [`agent-strace skills eval`](docs/skills-eval.md) | Experimental: run should/shouldn't-trigger tasks and count skill loads |
  139. | [`agent-strace lint <id>`](docs/commands.md#lint) | Flag bad behaviour patterns (loops, spirals, waste) |
  140. | [`agent-strace drift`](docs/commands.md#drift) | Detect behavioural drift over time |
  141. | [`agent-strace fingerprint`](docs/commands.md#fingerprint) | Baseline an agent's behavioural profile |
  142. | [`agent-strace tree`](docs/commands.md#tree) | Show parent/child session hierarchy |
  143. | [`agent-strace freeze`](docs/commands.md#freeze) | Freeze a tool-call sequence for regression checks |
  144. | [`agent-strace standup`](docs/commands.md#standup) | Plain-English summary of one session (latest by default) |
  145. | [`agent-strace eval <id>`](docs/commands.md#eval) | Gate a session on named quality criteria and baselines |
  146. | [`agent-strace eval ci`](docs/commands.md#eval) | Run the legacy normalized-score CI workflow |
  147. ### Export and integrate
  148. | Command | What it does |
  149. |---|---|
  150. | [`agent-strace export --format otlp-genai`](docs/production.md) | Export to Datadog, Honeycomb, Grafana, Jaeger |
  151. | [`agent-strace export --format temporal`](docs/integrations.md#temporal-workflows) | Nest agent spans under Temporal activities |
  152. | [`agent-strace export --format eu-ai-act`](docs/commands.md#export) | Generate Article 12/13 audit packages |
  153. | [`agent-strace export --metrics`](docs/production.md#behavioral-metrics) | Export per-session behavioral metrics as OTLP gauges |
  154. | [`agent-strace identity show`](docs/commands.md#identity) | Machine identity: sign and verify sessions |
  155. | [`agent-strace mcp`](docs/mcp.md) | MCP server: query sessions, health, skill, and PR reviewability reports from Claude Code, Copilot CLI, Codex, or Gemini CLI |
  156. | [`agent-strace server`](docs/server.md) | Server-side collector for multi-agent, multi-machine |
  157. | [`agent-strace share <id>`](docs/commands.md#share) | Generate a shareable HTML replay |
  158. | [`agent-strace share --assignment <id>`](docs/hiring.md) | Create a privacy-minimized assignment submission ZIP |
  159. | [`agent-strace score submission.zip`](docs/hiring.md) | Apply a deterministic process-telemetry rubric |
  160. | [`agent-strace pr-comment`](docs/commands.md#pr-comment) | Post or update a session summary on the current PR |
  161. | [`agent-strace review`](docs/review.md) | Check PR reviewability: rationale, scope, validation, stewardship, evidence health |
  162. | [`agent-strace sample`](docs/commands.md#sample) | Export worst sessions as JSONL for eval datasets |
  163. Full flag reference: [docs/commands.md](docs/commands.md)
  164. ## VS Code extension
  165. Install **agent-strace** from the [Extensions panel](https://open-vsx.org/extension/Siddhant-K-code/agent-strace) to see live session activity without leaving the editor.
  166. Anonymous extension usage telemetry is enabled by default, sends nothing until
  167. its one-time notice is shown, and can be disabled from the Command Palette or
  168. `agentTrace.telemetry.enabled` setting. No prompts, trace contents, paths, session IDs, command arguments, or repository data are sent.
  169. | Feature | Description |
  170. |---|---|
  171. | Status bar | Live cost, tool call count, and active tool name. Click to open the event stream. |
  172. | Gutter annotations | Blue border on files the agent read, amber on files it modified. |
  173. | Evidence review | Ordered events, evidence health, gaps, relationships, annotations, raw fields, and reviewer filters. |
  174. | Local review actions | Compare sessions, save a privacy-minimized HTML review, or download OTLP JSON without uploading. |
  175. | Pause button | Stops the agent mid-session via SIGSTOP. |
  176. ```bash
  177. pip install agent-strace # 1. install
  178. agent-strace setup # 2. add hooks to Claude Code; use --cli codex, gemini, cursor, or copilot for other CLIs
  179. # 3. open project in VS Code; extension activates when .agent-traces/ exists
  180. # 4. start Claude Code; status bar appears immediately
  181. ```
  182. Full docs: [docs/vscode.md](docs/vscode.md)
  183. ## Production
  184. **OTLP export**: sessions become traces, tool calls become spans:
  185. ```bash
  186. agent-strace export <session-id> --format otlp-genai \
  187. --endpoint http://localhost:4318
  188. ```
  189. Per-backend setup (Datadog, Honeycomb, Grafana, New Relic, Splunk, Langfuse): [docs/production.md](docs/production.md)
  190. **Server-side collector**: for containers, CI, and multi-machine setups:
  191. ```bash
  192. agent-strace server --port 4317 --storage ./traces
  193. export AGENT_STRACE_ENDPOINT=http://collector:4317 # read by hook commands and Python integrations
  194. ```
  195. Full guide: [docs/server.md](docs/server.md)
  196. **Auto-instrumentation**: no code changes required:
  197. ```bash
  198. agent-strace auto --detect -- python my_agent.py
  199. ```
  200. Supported: OpenAI Agents SDK, LangChain, LangGraph, CrewAI, LiteLLM, Anthropic SDK, OpenAI SDK, AWS Strands. Guide: [docs/integrations.md](docs/integrations.md)
  201. **GitHub Actions**: run evals in CI, post results to the step summary, fail on regression:
  202. ```yaml
  203. - uses: Siddhant-K-code/agent-trace@v0.115.2
  204. with:
  205. config: .agent-evals.yaml
  206. baseline: .agent-evals-baseline.json
  207. tolerance: "0.05"
  208. ```
  209. [Marketplace listing](https://github.com/marketplace/actions/agent-trace-eval) · [Action reference](action.yml)
  210. ## How it works
  211. **Claude Code hooks**: Claude Code fires hook events at every stage of its agentic loop. agent-strace registers as a handler, reads JSON from stdin, and writes trace events. Each hook runs as a separate process; session state in `.agent-traces/.active-session` correlates PreToolUse and PostToolUse for latency measurement.
  212. **MCP stdio proxy**: sits between the agent and the MCP server, reads JSON-RPC messages (Content-Length framed or newline-delimited), classifies each one, and writes a trace event. Messages are forwarded unchanged. The agent and server do not know the proxy exists.
  213. **MCP HTTP/SSE proxy**: same idea, different transport. Listens on a local port, forwards POST and SSE requests to the remote server, captures every JSON-RPC message in both directions.
  214. **Python decorator**: `@trace_tool` logs a `tool_call` event before execution and a `tool_result` after. Errors and timing are captured automatically. `@trace_llm_call` does the same for LLM calls.
  215. ## Running tests
  216. ```bash
  217. python -m unittest discover -s tests -v
  218. ```
  219. ## License
  220. MIT. Use it however you want.
  221. ---
  222. <!-- mcp-name: io.github.Siddhant-K-code/agent-trace -->
  223. [Sponsor](https://github.com/sponsors/Siddhant-K-code) · [ADRs](ADRs/) · [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Release guide](docs/releases.md) · [PyPI](https://pypi.org/project/agent-strace/)

Version history

  • v0.101.010/23/2026

  • v0.98.010/21/2026

  • v0.97.010/19/2026

  • v0.96.010/18/2026

  • v0.95.010/18/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.