A
abhishekash/spanhound
Capture local AI agent traces and inspect failures, approvals, token usage, and run regressions through MCP.
no SECURITY.md
View on GitHub ↗Link checked 2026-11-12 · HTTP 200 · opens the vendor's own site
Install & config
- Copy the command above
- Paste it as one entry under
mcpServersinclaude_desktop_config.json— local servers take command + args (example: clients) - Restart your client
Client config (built from the install command this repo gives)
{
"mcpServers": {
"abhishekash-spanhound": {
"command": "uvx",
"args": ["spanhound"]
}
}
}Parsed from the README we fetched on 2026-10-26; we have not executed it.
command/args come from the install command the repository states. When it is ambiguous, the project README wins.
VS Code (.vscode/mcp.json - the key is servers)
{
"servers": {
"abhishekash-spanhound": {
"command": "uvx",
"args": ["spanhound"]
}
}
}Same server, but VS Code keeps it under <code>servers</code>.
Claude Code (command line)
claude mcp add --transport stdio abhishekash-spanhound -- uvx spanhound
Claude Code does not read a config file; add the server with this command.
Key names differ by client: Clients & CLI
- Star count
- 1 ★ · abhishekash/spanhound · read from the GitHub search API · (checked 2026-11-13 20:00:50)
- Source
- collected from the punkpeye/awesome-mcp-servers list · type: MCP server
- Harvest history
- first seen 2026-10-23 · last seen 2026-11-14 · seen 26× · listed by 23 sources
- Score
- score 2,300 · 1 ★ · 23 sources · mcp
- Install
uvx spanhound
FAQ (answers come from our records)
How do I install it?
The repository provides this install command:
uvx spanhound. It comes from the repository itself; we cannot guarantee it runs as-is in your client.Who is it for?
We filed it under these tags: MCP 服务. The tags come from the entry itself, not a taxonomy we imposed.
Who maintains it?
repository
abhishekash/spanhound；first catalogued 2026-10-23；last seen 2026-11-14。There is no official certification or quality rating here — we record sources and dates only.# SpanHound
以下摘录自该仓库的 README（片段） · 在 GitHub 读完整 README →
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
(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
Listed badge (optional)
Copy this line into the README if you want the listing mark. Optional, and it does not affect being listed.
[](https://anclum.com/en/s/abhishekash-spanhound/)
- Source
- awesome · https://github.com/abhishekash/spanhound
- Browse by field
- MCP servers
- Traction
- 1 ★
- Listed by
- 23 independent sources
- added
- today
- Security policy
- no
SECURITY.mdat the repository root (which does not mean it is unsafe)
More like this
Filed under
Every tag opens the full list for that filter. Counts are the live catalogue figures.