Skip to content
Back to search

agentsight

lightweight system-level observability for AI Agents

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/eunomia-bpf/agentsight with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/eunomia-bpf/agentsight'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/eunomia-bpf--agentsight/badge.svg)](/listings/eunomia-bpf--agentsight)

HTML

<a href="/listings/eunomia-bpf--agentsight"><img src="/api/listings/eunomia-bpf--agentsight/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.

cargo install agentsight
# or: wget https://github.com/eunomia-bpf/agentsight/releases/latest/download/agentsight && chmod +x agentsight

<div align="center"> <p><em>Live sessions ranked by model, session tokens, health, process family, tool calls, file activity, and network activity</em></p> </div>

agentsight top

<div align="center"> <p><em>Agent Nebula replays how coding agents read, write, create, rename, and delete files across the ACTplane repository</em></p> </div>

agentsight vis

<div align="center"> <p><em>Width is system-effect weight; the uneven stack height shows prompt, tool-call, process, and effect paths ending at different depths. See the <a href="docs/agentpprof.md#example-flamegraphs">agentpprof guide</a> for the other profiles and how widths and stack depths are drawn.</em></p> </div>

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.

README.md · README · 313 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # AgentSight: System-wide AI agent profiling and monitoring with eBPF
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
  3. [![CI](https://github.com/eunomia-bpf/agentsight/actions/workflows/ci.yml/badge.svg)](https://github.com/eunomia-bpf/agentsight/actions/workflows/ci.yml)
  4. [![arXiv:2508.02736](https://img.shields.io/badge/arXiv-2508.02736-b31b1b.svg)](https://arxiv.org/abs/2508.02736)
  5. [![DOI:10.1145/3766882.3767169](https://img.shields.io/badge/DOI-10.1145%2F3766882.3767169-blue.svg)](https://dl.acm.org/doi/10.1145/3766882.3767169)
  6. **English** | [中文](https://github.com/eunomia-bpf/agentsight/blob/master/README.zh-CN.md)
  7. AI agents can run commands, rewrite files, spawn processes, and contact remote services—but when a run fails, stalls, or behaves unexpectedly, their logs rarely tell the whole story.
  8. AgentSight is a local-first `top`/`strace`-like observability tool for AI agents. It connects prompts, model calls, and tool decisions to their real effects on your machine.
  9. - **See what the agent is doing now.** Monitor active sessions, processes, resource, model and tool calls, file and network activity.
  10. - **Understand failures and improve agent behavior.** Connect prompts and skills to errors, then turn them into better instructions and skills.
  11. - **Find where time, tokens, and resources go.** Spot slow steps, retry loops, repeated model or tool calls, token-heavy sessions, and resource-hungry processes.
  12. - **Audit data movement and security-sensitive effects.** See which services received requests, which files changed, and whether agents stayed and give safety/security suggestions.
  13. - **Use it with your existing agents.** Run AgentSight around Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, or any command—without an SDK, proxy, or vendor integration.
  14. No SDK, no proxy, no vendor integration. AgentSight observes with eBPF and TLS traffic tracing, so it works even when the agent is a
  15. closed-source CLI. **✨ Zero SDK Required**
  16. ## Quick Start
  17. ```bash
  18. cargo install agentsight
  19. # or: wget https://github.com/eunomia-bpf/agentsight/releases/latest/download/agentsight && chmod +x agentsight
  20. ```
  21. <div align="center">
  22. <img src="https://github.com/eunomia-bpf/agentsight/raw/master/docs/top-mode-demo.png" alt="AgentSight top live session view" width="1000">
  23. <p><em>Live sessions ranked by model, session tokens, health, process family, tool calls, file activity, and network activity</em></p>
  24. </div>
  25. ```sh
  26. agentsight top
  27. ```
  28. <div align="center">
  29. <img src="https://github.com/eunomia-bpf/agentsight/raw/master/ext/vis/examples/actplane-agent-nebula.gif" alt="Agent Nebula replay of Agent development across the ACTplane repository" width="1000">
  30. <p><em>Agent Nebula replays how coding agents read, write, create, rename, and delete files across the ACTplane repository</em></p>
  31. </div>
  32. ```sh
  33. agentsight vis
  34. ```
  35. <div align="center">
  36. <img src="https://github.com/eunomia-bpf/agentsight/raw/master/docs/flamegraph-example/semantic-flamegraph-top200.svg" alt="Semantic flamegraph of the top 200 agent stacks" width="1000">
  37. <p><em>Width is system-effect weight; the uneven stack height shows prompt, tool-call, process, and effect paths ending at different depths. See the <a href="docs/agentpprof.md#example-flamegraphs">agentpprof guide</a> for the other profiles and how widths and stack depths are drawn.</em></p>
  38. </div>
  39. ## 🚀 Why AgentSight?
  40. ### Traditional Observability vs. System-Level Monitoring
  41. Application-level tools such as [LangSmith](https://docs.langchain.com/langsmith/observability-concepts), [Langfuse](https://langfuse.com/docs/observability/overview), and [Phoenix](https://arize.com/docs/phoenix/) are great for traces, prompts, tokens, evals, and latency when you own the application code. Gateway/proxy tools such as [Helicone](https://docs.helicone.ai/getting-started/integration-method/gateway) are useful when you can route provider traffic through a managed endpoint.
  42. AgentSight focuses on the layer those tools often miss: what the agent actually does at the system boundary. It observes existing binaries and CLI agents without SDKs or proxies, then correlates LLM traffic with process execution, file access, and system activity.
  43. | **Challenge** | **Application-Level Tools** | **AgentSight Solution** |
  44. |---------------|----------------------------|------------------------|
  45. | **Framework Adoption** | ❌ SDK, callback, or gateway integration per app | ✅ Drop-in system tracer, no code changes |
  46. | **Closed-Source CLIs** | ❌ Limited to what the tool exposes or logs | ✅ Observes existing binaries and CLI agents from outside |
  47. | **Agent-Controlled Logs** | ❌ Logs can be incomplete, disabled, or modified | ✅ Kernel-level events independent of app logging |
  48. | **TLS LLM Traffic** | ❌ Visible when routed through SDKs/proxies | ✅ Captures plaintext at SSL/TLS calls without a proxy |
  49. | **System Actions** | ❌ Often misses subprocesses and local file activity | ✅ Tracks process execution, file access, and resource use |
  50. | **Cross-Boundary Behavior** | ❌ Traces usually stop at framework/process boundaries | ✅ Correlates LLM traffic with process and file events |
  51. AgentSight captures critical interactions that application-level tools miss:
  52. - Subprocess executions that bypass instrumentation
  53. - Plaintext LLM payloads at SSL/TLS call boundaries
  54. - File operations and system resource access
  55. - Cross-boundary behavior across LLM, process, and file events
  56. ## Usage
  57. ### Prerequisites
  58. - **Windows, macOS, or Linux**: `top`, `bind`, `vis`, and `report` can use
  59. agent-native session files without eBPF
  60. - **Linux kernel**: 4.1+ with eBPF support (5.0+ recommended) for `record` and
  61. the eBPF-backed debug commands
  62. - **sudo access on Linux**: optional for `top`; eBPF is enabled automatically
  63. when sudo is already available
  64. For source builds, see [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md).
  65. ### Rust Library
  66. Rust applications can depend on
  67. [`agentsight-capture`](https://crates.io/crates/agentsight-capture) to reuse the
  68. same eBPF runners, agent-native sources, analyzers, event model, materialized
  69. view, and sinks as the `agentsight` binary. The CLI is published separately as
  70. the `agentsight` package and is the library's primary consumer.
  71. ### Installation
  72. #### Homebrew on Linux
  73. ```bash
  74. brew tap eunomia-bpf/tap
  75. brew install eunomia-bpf/tap/agentsight
  76. agentsight --version
  77. ```
  78. The current Homebrew formula supports Linux x86-64.
  79. #### Cargo or Release Binary
  80. For local use, install with `cargo install agentsight` or download the latest
  81. release binary, then start with `agentsight top`. Use the examples below when
  82. you want to record a specific command or inspect saved sessions.
  83. GitHub releases provide `agentsight-x86_64` and `agentsight-aarch64` for Linux.
  84. The unsuffixed `agentsight` asset remains an x86_64 compatibility alias.
  85. Native Windows builds are exercised by the Windows CI workflow; until a Windows
  86. release asset is published, download its `agentsight-windows-x86_64` artifact or
  87. build the collector crate from source.
  88. For Linux and Windows installation, background monitoring, Node binding,
  89. automatic startup, upgrades, and removal, see
  90. [Installation and Automatic Startup](docs/installation.md).
  91. #### Docker
  92. Docker is useful for container, CI, or isolated Linux environments, but it still needs privileged host access for eBPF. See [docs/docker.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/docker.md).
  93. #### Build from Source
  94. Build requirements and source build commands live in [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md).
  95. ### Replay a Repository Session
  96. Run `agentsight vis` inside a Git worktree. It scans matching local Claude,
  97. Codex, and Gemini sessions without sudo, then writes an animated replay to
  98. `output/agent-nebula.gif`:
  99. ```bash
  100. cd your-repository
  101. agentsight vis
  102. ```
  103. GIF export requires local Chromium and FFmpeg. Use
  104. `agentsight vis -o output/agent-nebula.html` for a self-contained HTML artifact
  105. that needs neither dependency to generate.
  106. ### Querying Past Sessions
  107. Every `record` session is automatically saved to an `agentsight-*.db` SQLite
  108. file in the current directory. Start with the live and record commands, then
  109. use `agentsight report` for structured queries:
  110. ```bash
  111. agentsight top # live ranked view; uses eBPF when sudo is already available
  112. agentsight monitor install-service # install/start the background monitor service
  113. agentsight report --db run.db # summary of a specific saved run
  114. sudo agentsight record -- claude # record a command
  115. agentsight report # high-level latest-run summary (default)
  116. agentsight report list # recorded sessions in this directory
  117. agentsight report prompts --json # full LLM request/response JSON
  118. agentsight report token # token usage from latest DB, or local agent sessions
  119. agentsight report token --group-by dir # token usage by session/process working directory
  120. agentsight report audit --json # process spawns, file opens, API calls
  121. agentsight report serve # open the web UI for the latest session in this directory
  122. agentsight report export -o snapshot.json # export for web dashboard; see docs/snapshot-schema.md
  123. agentsight report --local # summarize native Claude/Codex/Gemini sessions
  124. ```
  125. On supported Linux kernels, process `FILE_OPEN` events include resolved paths,
  126. read/write/exec access, and overlay layer and inode metadata. See the
  127. [process probe reference](bpf/README.md#1-process-tracer-process) for the JSON
  128. fields and older-kernel fallback.
  129. ### Offline Agent pprof Profiles
  130. Use `agentpprof` when you want a no-sudo pprof/folded-stack/SVG summary of
  131. local Codex or Claude session history:
  132. ```bash
  133. cargo run --manifest-path ext/pprof/Cargo.toml -- \
  134. --project-root . \
  135. --view tokens \
  136. -o agent.pb.gz
  137. go tool pprof -top agent.pb.gz
  138. ```
  139. The `tokens` view is the best first flamegraph for cost analysis: it aggregates
  140. real local Codex/Claude development sessions by project, agent, session tag,
  141. prompt tag, model, and token kind.
  142. <div align="center">
  143. <img src="https://github.com/eunomia-bpf/agentsight/raw/master/docs/flamegraph-example/bpf-benchmark-tokens.svg" alt="agentpprof token flamegraph from real bpf-benchmark development sessions" width="1000">
  144. <p><em>Offline token profile generated from real local bpf-benchmark coding-agent sessions</em></p>
  145. </div>
  146. See [ext/pprof/README.md](ext/pprof/README.md) for CLI details and the
  147. [agentpprof profiling guide](docs/agentpprof.md#example-flamegraphs) for
  148. flamegraph examples, rendering, view selection, and deterministic tagging rules.
  149. ### Web Interface
  150. During a session, visit [http://127.0.0.1:7395](http://127.0.0.1:7395) for live traffic, process trees, and metrics:
  151. - **Overview Dashboard** (landing): http://127.0.0.1:7395/ — tokens, model calls, process/file/network effects, resource shape, and friction signals for the whole session, with drill-down into the detail views.
  152. - **Timeline View**: http://127.0.0.1:7395/timeline
  153. - **Process Tree**: http://127.0.0.1:7395/tree
  154. - **Event Log**: http://127.0.0.1:7395/logs
  155. - **Metrics View**: http://127.0.0.1:7395/metrics
  156. For a saved SQLite session, run `agentsight report serve --db run.db` and open the same routes.
  157. <div align="center">
  158. <img src="https://github.com/eunomia-bpf/agentsight/raw/master/docs/demo-tree.png" alt="AgentSight Demo - Process Tree Visualization" width="800">
  159. <p><em>Process tree visualization for agent subprocesses and file activity</em></p>
  160. </div>
  161. <div align="center">
  162. <img src="https://github.com/eunomia-bpf/agentsight/raw/master/docs/demo-timeline.png" alt="AgentSight Demo - Timeline Visualization" width="800">
  163. <p><em>Timeline visualization for LLM, process, file, and network events</em></p>
  164. </div>
  165. <div align="center">
  166. <img src="https://github.com/eunomia-bpf/agentsight/raw/master/docs/demo-metrics.png" alt="AgentSight Demo - Metrics Visualization" width="800">
  167. <p><em>Metrics visualization for memory and CPU usage</em></p>
  168. </div>
  169. <div align="center">
  170. <p><strong>Try the <a href="https://agentsight.us">live demo</a></strong> to explore a real recorded Claude Code session in the browser.</p>
  171. </div>
  172. ### Supported Agents
  173. > **Privileges:** eBPF probes need root. Use `sudo` for live capture commands.
  174. `record` auto-discovers binaries, SSL libraries, and container processes. Works out of the box for:
  175. | Agent | Command |
  176. |-------|---------|
  177. | Claude Code | `sudo ./agentsight record -- claude` |
  178. | Gemini CLI | `sudo ./agentsight record -- gemini` |
  179. | Kimi Code | `sudo ./agentsight record -- kimi` |
  180. | Grok Build | `sudo ./agentsight record -- grok` |
  181. | Python (aider, open-interpreter, …) | `sudo ./agentsight record -c python` |
  182. | Docker containers (OpenClaw, …) | `sudo ./agentsight record -c node --binary-path docker://openclaw` |
  183. | Cursor (IDE) | `agentsight top` reads its local sessions, no sudo needed |
  184. | CodeBuddy CLI | `agentsight top` reads `~/.codebuddy/projects`; `sudo ./agentsight record -c codebuddy` attaches the running Node process |
  185. | Any command | `sudo ./agentsight record -- <command>` |
  186. See [docs/agents.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/agents.md) for agent-specific setup, SSL quirks, browser capture, MCP stdio, and advanced flags.
  187. ### OpenTelemetry Export
  188. AgentSight can export captured LLM calls as OpenTelemetry **GenAI**
  189. (`gen_ai.*`) spans over OTLP/HTTP — standards-compliant agent telemetry for any
  190. agent, with zero in-process instrumentation.
  191. ```bash
  192. sudo ./agentsight debug trace --otel --otel-endpoint http://localhost:4318
  193. ```
  194. See [docs/otel.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/otel.md) for
  195. collector setup and backend integration.
  196. ## ❓ Frequently Asked Questions
  197. **Q: What permissions does AgentSight need?**
  198. A: `top` uses live eBPF process capture when you run it with sudo or your user already has passwordless/cached sudo. Without eBPF privileges, it falls back to process snapshots and native agent session files. With `record -- <command>`, the monitored agent still runs as your normal user; only the probes are elevated.
  199. **Q: What's the performance impact?**
  200. A: Our evaluation reports less than 3% CPU overhead for typical traced agent workloads.
  201. **Q: Where does captured data go?**
  202. A: `record` stores sessions as `agentsight-*.db` files in the current directory by default, and `report` reads the latest matching file from that directory unless you pass `--db`. When no default DB exists, report commands warn and fall back to local Claude/Codex/Gemini agent sessions where available. `monitor` stores its weekly background DBs under `~/.agentsight/monitor`, while `top` only shows live sessions. Use `agentsight report`, `agentsight report list`, `agentsight report audit --json`, and `agentsight report token` to inspect prior runs. Captured data can include prompts, responses, paths, headers, and network targets, so treat logs and DBs as sensitive.
  203. **Q: Why doesn't AgentSight capture traffic from Claude Code, Node.js, or Gemini CLI?**
  204. A: These applications statically link their SSL library (BoringSSL for Claude/Bun, OpenSSL for **all** Node.js — both NVM and system installs) into their own binary instead of using system `libssl.so`, so there's nothing for sslsniff to hook by default. AgentSight handles this for you: `record -- <command>` always discovers the binary, and `record -c node` now auto-discovers the Node binary too. For Claude attach mode, pass `--binary-path`. See the "Zero-Config: record" and "Monitoring Node.js AI Tools" sections.
  205. **Q: Can AgentSight trace IDE agents like Cursor?**
  206. A: Not through eBPF. They are Electron apps that mostly run on macOS or Windows, their TLS sits inside a stripped framework binary and a helper process, and Cursor's API traffic is protobuf rather than JSON, so even a successful capture produces no LLM events. Support for these agents goes through the agent-native session path instead. See [IDE-Based Agents](https://github.com/eunomia-bpf/agentsight/blob/master/docs/agents.md#ide-based-agents-cursor-antigravity-windsurf) for the details.
  207. **Q: What should I check if tracing fails?**
  208. A: Verify you are on Linux with eBPF support, have `sudo` or `CAP_BPF`/`CAP_SYS_ADMIN`, and are using `record -- <command>` or the correct `--binary-path` for statically linked agents.
  209. ## 🤝 Contributing
  210. We welcome contributions! After cloning and building (see [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md)), you can:
  211. ```bash
  212. # Run tests
  213. make test
  214. # Frontend development server
  215. cd frontend && npm run dev
  216. # Build debug versions with AddressSanitizer
  217. make -C bpf debug
  218. ```
  219. ### Key Resources
  220. - [CLAUDE.md](https://github.com/eunomia-bpf/agentsight/blob/master/CLAUDE.md) - Project guidelines and architecture
  221. - [docs/design/README.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/design/README.md) - archived design notes and research drafts
  222. ## 📄 License
  223. MIT License - see [LICENSE](https://github.com/eunomia-bpf/agentsight/blob/master/LICENSE) for details.
  224. ---
  225. **💡 The Future of AI Observability**: As AI agents become more autonomous and capable of self-modification, traditional observability approaches become insufficient. AgentSight provides independent, system-level monitoring for safe AI deployment at scale.

Ratings and comments

Sign in to rate this skill.

Sign in

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