abhishekash/spanhound

Capture local agent traces. Ask your MCP client what happened. SpanHound
(formerly mcp-trace-inspector) captures supported Python agent calls, receives
OpenTelemetry over local OTLP/HTTP, and exposes read-only MCP tools for
failures, approval decisions, token usage, and run comparisons. It reads JSONL
spans and OTLP JSON exports as described in the
user guide, including traces from
agent-harness.
Demo: Watch the full 48-second video · Read the reproducible story. This is a scripted regression trace, not a live-model benchmark.
The project's concrete origin was a shell-boundary regression: the harness blocked
cat ../outside.txt, but the old trace recorded only that runshell was
called, not the returned diagnostic. SpanHound and the harness now preserve and
query that bounded error.
## Try it in one command
bash
uvx spanhound demo
text
SpanHound demo — recorded agent failure
Tool: runshell
Failure: error: shell path escapes workspace root: '../outside.txt'
Approval: approve (auto)
Trace: 563e779ee8fa2d7069fc63ed2cf9c8ec (6 spans)
The demo shows a recorded runshell failure and its approval evidence from a
bundled scripted regression trace. It needs no clone, account, trace backend, or
MCP client. To inspect your own traces, point SpanHound at a directory of JSONL
spans or saved OTLP JSON exports:
bash
uvx spanhound --trace-dir /path/to/traces --check
--check prints the runs it found and exits. Connect an MCP client with the
configuration below to ask questions about those runs.
## Explore the repository fixtures
bash
git clone https://github.com/abhishekash/spanhound.git
cd spanhound
uvx --from . spanhound --trace-dir examples --check
--check also reports a missing directory or malformed complete JSONL or OTLP
JSON record.
To try an OTLP JSON export, run the same command with --trace-dir tests/fixtures.
The sample export includes a model call, token
usage, a tool call, and an exception.
## Capture your own traces
For a Python agent, install SpanHound's optional auto instrumentation in the
same environment as the agent, then run it through SpanHound:
bash
python -m pip install 'spanhound[auto]'
spanhound run --trace-dir ./traces -- python agent.py
The command starts and stops a local receiver, configures OTLP export, and
captures supported library calls without changes to agent.py. The optional
package includes instrumentation for OpenAI, Anthropic, OpenAI Agents, HTTPX,
and Requests. It reports when no spans were produced. Your Python agent and
SpanHound must share one environment; for a uv project, use
uv add 'spanhound[auto]' and uv run spanhound run -- python agent.py.
See the Python capture guide.
For other runtimes, or agents that already export OpenTelemetry traces, start
the receiver in one terminal:
bash
uvx spanhound collect --trace-dir ./traces
Point an agent that already uses an OpenTelemetry trace exporter at the
receiver, then run the agent:
bash
export OTELEXPORTEROTLPTRACESENDPOINT=http://127.0.0.1:4318/v1/traces
export OTELEXPORTEROTLPTRACESPROTOCOL=http/protobuf
# Start your instrumented agent here.
SpanHound stores each accepted OTLP/HTTP trace request as a local JSON file.
Run uvx spanhound --trace-dir ./traces --check to see the captured runs, then