The eunomia-bpf maintainers claim their released AgentSight — an eBPF and TLS-boundary tracer that observes closed-source coding agents (Claude Code, Codex, Gemini CLI) with no SDK, proxy, or vendor integration — makes kernel-level system observability a standard layer alongside harness-level tracing; sustained external adoption confirms it, quiet fading closes it as another niche profiler.

Open article · Retrieved 2026-10-03T20:26:19.738957+00:00

# AgentSight: System-wide AI agent profiling and monitoring with eBPF

[License: MIT](https://opensource.org/licenses/MIT)
[CI](https://github.com/eunomia-bpf/agentsight/actions/workflows/ci.yml)
[arXiv:2508.02736](https://arxiv.org/abs/2508.02736)
[DOI:10.1145/3766882.3767169](https://dl.acm.org/doi/10.1145/3766882.3767169)

**English** | [中文](https://github.com/eunomia-bpf/agentsight/blob/master/README.zh-CN.md)

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.

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.

- **See what the agent is doing now.** Monitor active sessions, processes, resource, model and tool calls, file and network activity.
- **Understand failures and improve agent behavior.** Connect prompts and skills to errors, then turn them into better instructions and skills.
- **Find where time, tokens, and resources go.** Spot slow steps, retry loops, repeated model or tool calls, token-heavy sessions, and resource-hungry processes.
- **Audit data movement and security-sensitive effects.** See which services received requests, which files changed, and whether agents stayed and give safety/security suggestions.
- **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.

No SDK, no proxy, no vendor integration. AgentSight observes with eBPF and TLS traffic tracing, so it works even when the agent is a
closed-source CLI. **✨ Zero SDK Required**

## Quick Start

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

[AgentSight top live session view](https://github.com/eunomia-bpf/agentsight/raw/master/docs/top-mode-demo.png)

*Live sessions ranked by model, session tokens, health, process family, tool calls, file activity, and network activity*

```
agentsight top
```

[Agent Nebula replay of Agent development across the ACTplane repository](https://github.com/eunomia-bpf/agentsight/raw/master/ext/vis/examples/actplane-agent-nebula.gif)

*Agent Nebula replays how coding agents read, write, create, rename, and delete files across the ACTplane repository*

```
agentsight vis
```

[Semantic flamegraph of the top 200 agent stacks](https://github.com/eunomia-bpf/agentsight/raw/master/docs/flamegraph-example/semantic-flamegraph-top200.svg)

*Width is system-effect weight; the uneven stack height shows prompt, tool-call, process, and effect paths ending at different depths. See the [agentpprof guide](https://github.com/eunomia-bpf/agentsight/blob/master/docs/agentpprof.md#example-flamegraphs) for the other profiles and how widths and stack depths are drawn.*

## 🚀 Why AgentSight?

### Traditional Observability vs. System-Level Monitoring

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.

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.

| **Challenge** | **Application-Level Tools** | **AgentSight Solution** |
| --- | --- | --- |
| **Framework Adoption** | ❌ SDK, callback, or gateway integration per app | ✅ Drop-in system tracer, no code changes |
| **Closed-Source CLIs** | ❌ Limited to what the tool exposes or logs | ✅ Observes existing binaries and CLI agents from outside |
| **Agent-Controlled Logs** | ❌ Logs can be incomplete, disabled, or modified | ✅ Kernel-level events independent of app logging |
| **TLS LLM Traffic** | ❌ Visible when routed through SDKs/proxies | ✅ Captures plaintext at SSL/TLS calls without a proxy |
| **System Actions** | ❌ Often misses subprocesses and local file activity | ✅ Tracks process execution, file access, and resource use |
| **Cross-Boundary Behavior** | ❌ Traces usually stop at framework/process boundaries | ✅ Correlates LLM traffic with process and file events |

AgentSight captures critical interactions that application-level tools miss:

- Subprocess executions that bypass instrumentation
- Plaintext LLM payloads at SSL/TLS call boundaries
- File operations and system resource access
- Cross-boundary behavior across LLM, process, and file events

## Usage

### Prerequisites

- **Windows, macOS, or Linux**: `top`, `bind`, `vis`, and `report` can use
  agent-native session files without eBPF
- **Linux kernel**: 4.1+ with eBPF support (5.0+ recommended) for `record` and
  the eBPF-backed debug commands
- **sudo access on Linux**: optional for `top`; eBPF is enabled automatically
  when sudo is already available

For source builds, see [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md).

### Rust Library

Rust applications can depend on
[`agentsight-capture`](https://crates.io/crates/agentsight-capture) to reuse the
same eBPF runners, agent-native sources, analyzers, event model, materialized
view, and sinks as the `agentsight` binary. The CLI is published separately as
the `agentsight` package and is the library's primary consumer.

### Installation

#### Homebrew on Linux

```
brew tap eunomia-bpf/tap
brew install eunomia-bpf/tap/agentsight
agentsight --version
```

The current Homebrew formula supports Linux x86-64.

#### Cargo or Release Binary

For local use, install with `cargo install agentsight` or download the latest
release binary, then start with `agentsight top`. Use the examples below when
you want to record a specific command or inspect saved sessions.

GitHub releases provide `agentsight-x86_64` and `agentsight-aarch64` for Linux.
The unsuffixed `agentsight` asset remains an x86\_64 compatibility alias.
Native Windows builds are exercised by the Windows CI workflow; until a Windows
release asset is published, download its `agentsight-windows-x86_64` artifact or
build the collector crate from source.

For Linux and Windows installation, background monitoring, Node binding,
automatic startup, upgrades, and removal, see
[Installation and Automatic Startup](https://github.com/eunomia-bpf/agentsight/blob/master/docs/installation.md).

#### Docker

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

#### Build from Source

Build requirements and source build commands live in [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md).

### Replay a Repository Session

Run `agentsight vis` inside a Git worktree. It scans matching local Claude,
Codex, and Gemini sessions without sudo, then writes an animated replay to
`output/agent-nebula.gif`:

```
cd your-repository
agentsight vis
```

GIF export requires local Chromium and FFmpeg. Use
`agentsight vis -o output/agent-nebula.html` for a self-contained HTML artifact
that needs neither dependency to generate.

### Querying Past Sessions

Every `record` session is automatically saved to an `agentsight-*.db` SQLite
file in the current directory. Start with the live and record commands, then
use `agentsight report` for structured queries:

```
agentsight top                               # live ranked view; uses eBPF when sudo is already available
agentsight monitor install-service           # install/start the background monitor service
agentsight report --db run.db                 # summary of a specific saved run
sudo agentsight record -- claude             # record a command
agentsight report                            # high-level latest-run summary (default)
agentsight report list                       # recorded sessions in this directory
agentsight report prompts --json             # full LLM request/response JSON
agentsight report token                      # token usage from latest DB, or local agent sessions
agentsight report token --group-by dir       # token usage by session/process working directory
agentsight report audit --json               # process spawns, file opens, API calls
agentsight report serve                      # open the web UI for the latest session in this directory
agentsight report export -o snapshot.json    # export for web dashboard; see docs/snapshot-schema.md
agentsight report --local                    # summarize native Claude/Codex/Gemini sessions
```

### Offline Agent pprof Profiles

Use `agentpprof` when you want a no-sudo pprof/folded-stack/SVG summary of
local Codex or Claude session history:

```
cargo run --manifest-path ext/pprof/Cargo.toml -- \
  --project-root . \
  --view tokens \
  -o agent.pb.gz

go tool pprof -top agent.pb.gz
```

The `tokens` view is the best first flamegraph for cost analysis: it aggregates
real local Codex/Claude development sessions by project, agent, session tag,
prompt tag, model, and token kind.

[agentpprof token flamegraph from real bpf-benchmark development sessions](https://github.com/eunomia-bpf/agentsight/raw/master/docs/flamegraph-example/bpf-benchmark-tokens.svg)

*Offline token profile generated from real local bpf-benchmark coding-agent sessions*

See [ext/pprof/README.md](https://github.com/eunomia-bpf/agentsight/blob/master/ext/pprof/README.md) for CLI details and the
[agentpprof profiling guide](https://github.com/eunomia-bpf/agentsight/blob/master/docs/agentpprof.md#example-flamegraphs) for
flamegraph examples, rendering, view selection, and deterministic tagging rules.

### Web Interface

During a session, visit <http://127.0.0.1:7395> for live traffic, process trees, and metrics:

- **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.
- **Timeline View**: <http://127.0.0.1:7395/timeline>
- **Process Tree**: <http://127.0.0.1:7395/tree>
- **Event Log**: <http://127.0.0.1:7395/logs>
- **Metrics View**: <http://127.0.0.1:7395/metrics>

For a saved SQLite session, run `agentsight report serve --db run.db` and open the same routes.

[AgentSight Demo - Process Tree Visualization](https://github.com/eunomia-bpf/agentsight/raw/master/docs/demo-tree.png)

*Process tree visualization for agent subprocesses and file activity*

[AgentSight Demo - Timeline Visualization](https://github.com/eunomia-bpf/agentsight/raw/master/docs/demo-timeline.png)

*Timeline visualization for LLM, process, file, and network events*

[AgentSight Demo - Metrics Visualization](https://github.com/eunomia-bpf/agentsight/raw/master/docs/demo-metrics.png)

*Metrics visualization for memory and CPU usage*

**Try the [live demo](https://agentsight.us)** to explore a real recorded Claude Code session in the browser.

### Supported Agents

> **Privileges:** eBPF probes need root. Use `sudo` for live capture commands.

`record` auto-discovers binaries, SSL libraries, and container processes. Works out of the box for:

| Agent | Command |
| --- | --- |
| Claude Code | `sudo ./agentsight record -- claude` |
| Gemini CLI | `sudo ./agentsight record -- gemini` |
| Kimi Code | `sudo ./agentsight record -- kimi` |
| Grok Build | `sudo ./agentsight record -- grok` |
| Python (aider, open-interpreter, …) | `sudo ./agentsight record -c python` |
| Docker contain