ExecWeave

English | 繁體中文 | 简体中文 | 日本語 | 한국어 | Français | Deutsch | Русский

See what AI agents actually do on your machine.

ExecWeave is a source-available, local-first observability project that turns AI-agent activity into an interactive execution graph while keeping observed evidence, provider content, and derived inference explicitly separated.

Event is ground truth. The graph is a materialized view.

Install

Install the latest published wheel/sdist from PyPI:

python -m pip install -U execweave

The current release is v0.7.9.

For development:

git clone https://github.com/Irish-kw/ExecWeave.git
cd ExecWeave
python -m pip install -e ".[dev]"

Quick start

Live OS-runtime telemetry works with any local command. Agent/runtime names are examples, not a whitelist.

execweave live --open -- claude
execweave live --open -- codex
execweave live --open -- antigravity
execweave live --open -- cursor
execweave live --open -- opencode
execweave live --open -- ollama serve
execweave live --open -- python my_agent.py

Approve the hook when prompted. On the first provider-integrated run, the Agent/IDE may ask whether ExecWeave is allowed to enable its local hook integration. Choose Allow / Yes. If the hook is not approved, OS-runtime telemetry can still work, but provider-level tool, model, and supplied-content observability will be reduced or unavailable.

Google Antigravity uses the current agy CLI command; ExecWeave also accepts antigravity as a friendly alias and resolves it to agy. For Cursor, execweave live --open -- cursor first uses a normal PATH launcher when one exists, then falls back to the standard Cursor desktop application binary on macOS and Windows.

Or build the finalized artifact pipeline:

execweave record --open -- python my_agent.py

execweave top -- codex keeps the Agent interactive in the launch terminal while opening/attaching the detached Top dashboard according to the host environment.

v0.7.9 — one dashboard, while the run happens and afterwards. Live, the finished run and viewer.html were three renderings of the same evidence, and completion fetched a separate document and wrote it over the page a reader was watching. There is now one shell: finishing a run changes its state in place, and viewer.html is that same dashboard saved offline. Selecting an agent answers one question and stops — a root shows its Prompt and its Final response, a subagent shows its Task, its Thinking where the provider exposed plaintext, and its Response — while a process, a file, a network endpoint or a model shows no conversation at all, because a conversation belongs to an agent. A turn the provider encrypted reads as observed without plaintext rather than as never recorded, the block a provider prepends to every subagent is never presented as one agent's assignment, and an answer that quotes routing words survives intact. The provider-neutral, agent-local multi-agent conversations each agent owns are aggregated across every archive a run wrote, so an agent recorded many times still shows what it said. Release checks drive the shipped dashboard in a real browser through every selection a person can make, in both its live and its finished form.

The unified dashboard brings the execution graph, logs, and conversation records into the same inspection flow. Finalized runs generate conversations.md and conversations.json, while validated provider transcripts are copied into the run-local SHA-256 content store. Claude Code, OpenAI Codex, Cursor, OpenCode, and Google Antigravity use the strongest provider-exposed multi-agent evidence available to each integration. For gateways and local runtimes that expose only root request/response traffic, ExecWeave shows only that root conversation and does not invent subagents or hidden routing.

v0.6.9: full-fidelity observability with explicit evidence boundaries

v0.6.9 extends provider/runtime observability beyond compact metadata. When a supported integration point explicitly supplies content, ExecWeave can preserve the complete supplied value in a local SHA-256 content-addressed store while keeping only a reference in the semantic event stream.

<run-root>/content/sha256/<sha256>.<json|txt|bin>

Depending on the adapter and upstream hook/API surface, preserved content can include prompts/messages, model request/response objects, tool inputs/results, assistant responses, reasoning/thinking text when explicitly exposed, shell/MCP output, and file content supplied by provider hooks.

complete_from_source: true means ExecWeave stored the complete value delivered by that integration point. It does not mean ExecWeave observed hidden model state, provider-side stages that were never exposed, an unseen final wire request, or bytes it did not intercept.

Full fidelity also changes the privacy boundary: application-level secrets embedded inside content are preserved. Known transport credentials are filtered from selected provider-metadata projections where the adapter defines that behavior, but ExecWeave is not a general secret scanner or content redactor.

Supported semantic / inference surfaces

OpenRouter exchange is caller-supplied request+response evidence, not transparent wire interception. LiteLLM Proxy remains a narrower metadata-oriented integration in the current baseline. Provider-neutral conversation projection never upgrades missing provider evidence into a fabricated agent relationship.

Evidence layers

ExecWeave keeps evidence layers separate instead of flattening them into one trace:

Agent / IDE semantic + supplied content evidence
          ↓
Inference gateway / routing evidence
          ↓
Model runtime / inference-server evidence
          ↓
OS runtime evidence: process / file / network

A relationship is causal only when the underlying telemetry supports that claim. Tool → Process bridges remain conservative derived evidence:

inferred: true
causal: false

Ambiguity produces no edge. Exact shared request identity across Gateway and Model Runtime remains identity evidence rather than causal evidence:

identity_exact: true
inferred: false
causal: false

Agent / IDE integrations

execweave-claude-hook --print-config
execweave-claude-record --open -- claude

execweave-codex-hook --print-config
execweave-codex-record --open -- codex

execweave-antigravity-hook --print-config
execweave-antigravity-record --open -- antigravity

execweave-cursor-hook --print-config
execweave-cursor-record --open -- cursor

execweave-opencode-plugin --install
execweave-opencode-record --open -- opencode

Provider-integrated recorders keep raw runtime, semantic, correlated, and conversation artifacts separate. Stable provider identifiers such as Cursor tool_use_id, Codex rollout thread identity, or OpenCode sessionID + callID prove logical provider identity; they are not OS PIDs. Cross-agent content is shown only when the provider exposes an explicit route, delegation, or result. Legacy Gemini CLI hook entry points remain packaged for existing installations, but Gemini CLI is no longer advertised as a current integration; new Google CLI usage should use Antigravity (agy).

Inference gateways and model runtimes

Capture OpenRouter or LiteLLM gateway evidence:

execweave-inference-gateway event --gateway openrouter --sidecar gateway.jsonl
execweave-inference-gateway event --gateway litellm --sidecar gateway.jsonl
execweave-inference-gateway exchange --gateway openrouter --sidecar gateway.jsonl

Capture model-runtime evidence for Ollama, llama.cpp, vLLM, or LM Studio:

execweave-model-runtime event --runtime ollama --sidecar model-runtime.jsonl
execweave-model-runtime exchange --runtime ollama --sidecar model-runtime.jsonl
execweave-model-runtime probe --runtime ollama --sidecar model-runtime.jsonl

event is response-only evidence; exchange stores a caller-supplied request+response object and does not assert transparent interception. Runtime catalog relations retain their source-specific meaning: LOADED_MODEL, SERVES_MODEL, and ADVERTISES_MODEL are not interchangeable. LM Studio catalog visibility remains ADVERTISES_MODEL, not proof that weights were resident in memory.

Security analysis, evidence grades, and bounded rule packs

Run the built-in analysis:

execweave analyze run.graph.json --output analysis.json

Findings expose an evidence grade independent from severity. Current grades are A, B, C, D, and U, from direct syscall attribution through inferred/unknown provenance. Grades are evidence-strength categories, not probabilities or trust scores.

Local rule packs add bounded, explainable single-edge observation policies without executing third-party code:

execweave-rule-pack graph.json --rule-pack local-policy.json --output report.json

Rule packs cannot execute code, define regex/path programs, or assert byte-level data flow/exfiltration. Rule-pack findings remain observation-only.

Security findings continue to make stronger non-claims explicit:

{
  "data_flow_proven": false,
  "exfiltration_proven": false
}

Run integrity

Seal a completed run and later verify that its regular-file inventory has not changed relative to the seal:

execweave-integrity seal .execweave/runs/<run-id>
execweave-integrity verify .execweave/runs/<run-id>

The deterministic manifest records file size/SHA-256 and rejects symbolic links. It detects missing, modified, replaced, or newly added regular files after sealing.

This local seal is deliberately not described as adversary-resistant tamper evidence when both evidence and manifest remain inside the same writable trust boundary. The manifest records malicious_writer_resistance: false and external_trust_anchor: false; copy/protect the manifest digest outside that boundary when a stronger trust anchor is required.

Runtime evidence and graph operations

The portable collector runs on Linux, macOS, and Windows. Linux also has a syscall-backed strace reference backend.

execweave doctor
execweave run --backend portable -- your-command
execweave run --backend strace -- your-command
execweave graph-summary run.graph.json
execweave graph-filter run.graph.json --causal-only --output causal.graph.json
execweave graph-focus run.graph.json NODE_ID --hops 2 --output focused.graph.json
execweave path run.graph.json SOURCE TARGET --causal-only

Portable filesystem observation is session-correlated rather than process-causal, and polling can miss sufficiently short-lived activity. Linux strace provides stronger process-attributed syscall evidence for supported executions. Future native collectors remain planned for Linux eBPF, Windows ETW, and macOS Endpoint Security.

Performance and large-run safety

ExecWeave includes bounded filesystem/viewer protections, incremental Live JSONL tailing, large-graph safety guards, detached Top, and provisional live sidecars for configured provider integrations.

The reproducible incremental GraphAccumulator reference result reaches 164,273 ev/s at 1M synthetic events on the documented GitHub Actions workload. This is a graph-accumulation benchmark, not end-to-end collector/browser throughput.

Run the package-level overhead benchmark on a representative host/workload:

execweave-overhead --iterations 7 --strace auto --output-json benchmark-results.json
execweave-scalability

See docs/benchmarks/ for reference data and methodology.

Layered artifacts

A provider-integrated run may contain:

.execweave/runs/<run-id>/
├── events.jsonl
├── graph.json
├── viewer.html
├── semantic.jsonl
├── content/sha256/...
├── conversations.md
├── conversations.json
├── events.semantic.jsonl
├── graph.semantic.json
├── viewer.semantic.html
├── events.correlated.jsonl
├── graph.correlated.json
├── viewer.correlated.html
└── integrity.json            # after an explicit seal

Derived correlation never rewrites the raw runtime or provider sidecar evidence.

Privacy

ExecWeave is local-first: captures, content blobs, graphs, reports, and viewers remain local by default. The OS runtime collector does not intentionally capture file contents or raw read/write byte buffers. That boundary must not be confused with the provider full-fidelity content store introduced in v0.6.9: supported hooks/APIs can explicitly supply prompts, tool arguments/results, model responses, reasoning/thinking text, shell output, file content, or other sensitive values, and ExecWeave can preserve those values completely.

Conversation isolation is an attribution/display rule, not a redaction boundary. If a provider explicitly sends Agent 1 content to Agent 2, that routed evidence can legitimately appear at the participating endpoints. Do not assume content has been secret-redacted. Commands, paths, endpoint metadata, identifiers, model metadata, prompts, tool values, and content blobs can all be sensitive. Review the entire run directory before sharing it.

Current status

v0.7.9 combines cross-platform runtime collection, materialized execution graphs, standalone/live dashboards, conservative provider↔runtime correlation, full-fidelity content-addressed provider evidence, attributable multi-agent execution traces, direct run-local conversation access, agent-local conversation isolation across provider-neutral projections, and per-agent conversation focus in the standalone and live dashboards. Supported integrations preserve the strongest identity/routing evidence actually exposed by each provider and abstain when that evidence is unavailable. Observed evidence and inference remain separate by design.

Documentation

• Phase 1 — Runtime Collection
• Phase 2 — Execution Graph
• Live Graph
• Semantic Telemetry
• Claude Code Hooks
• OpenAI Codex Hooks
• Google Antigravity Hooks
• Cursor Hooks
• OpenCode Plugin
• Inference Gateway / OpenRouter / LiteLLM
• Model Runtime / Ollama / llama.cpp / vLLM / LM Studio
• Runtime Threat Model
• Evidence Grades
• Rule Packs
• Run Integrity
• Security Analysis
• Performance Benchmarks

Contributing

Contributions are welcome, especially around native OS collectors, Agent/IDE adapters, inference gateways, model runtimes, evidence/correlation methods, privacy/redaction, graph UX, multi-agent conversation attribution, and performance evaluation.

License

Starting with v0.6.8, ExecWeave is licensed under the PolyForm Noncommercial License 1.0.0. Noncommercial use, modification, and redistribution are permitted under its terms. Commercial use requires a separate written commercial license from the licensor. See LICENSE.