AgentHawk

Agents that can debug themselves. An MCP server that exposes your agent runs — stored as plain OpenTelemetry JSONL span files — as queryable tools: runs, span trees, failures, tool health, security evidence, live activity, regressions, human-approval logs, token/cost usage.

The idea: observability shouldn't be a dashboard you read after the fact. It should be tools your agent can call mid-run — "why was I slow yesterday?", "what did the human deny me last time?", "which tool keeps timing out?" — or query interactively from Claude Desktop / pi / any MCP client.

Pairs with agent-harness (which writes the traces), but the reader is format-simple: any JSONL of OTel-shaped spans works.

AI-native use cases

The tools read stored traces and can poll files being written, but they do not push events or infer intent from the final answer. See the real trace fixture and the tool descriptions for the exact query contract.

Install & run

AgentHawk is the new canonical name. The legacy abhishekash-mcp-trace distribution and mcp-trace commands remain compatibility aliases for existing users.

uvx agenthawk --trace-dir ./traces
# or, for local development:
git clone https://github.com/abhishekash/agenthawk
cd agenthawk && uv pip install -e .
agenthawk --trace-dir ./traces

The agenthawk 0.2.0 release is the renamed successor to the published abhishekash-mcp-trace 0.1.1 distribution. Existing clients can continue using the legacy command while migrating.

Client configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "agent-traces": {
      "command": "uvx",
      "args": ["agenthawk", "--trace-dir", "/path/to/traces"]
    }
  }
}

pi (~/.pi/agent/settings.json):

{
  "mcpServers": {
    "agent-traces": {
      "command": "uvx",
      "args": ["agenthawk", "--trace-dir", "/path/to/traces"]
    }
  }
}

agent-harness (mounted as gated tools):

harness run "Why was my last run slow?" --mcp "uvx agenthawk --trace-dir ./traces"

Tools

Tool descriptions are written as prompts (when-to-use, not just what-it-does) — descriptions are the interface for agent-called tools.

Example session (real fixture trace)

> list_runs
[{ "trace_id": "f920798dd255…", "task": "Summarize the workspace's notes…",
   "tool_calls": 4, "human_decisions": 2, "stopped_reason": "completed" }]

> approval_log
[{ "tool": "write_file", "decision": "approve", "approver": "auto", … },
 { "tool": "run_shell",  "decision": "approve", "approver": "auto", … }]

Design

traces/*.jsonl ──▶ agenthawk.core (pure query functions, zero deps)
                          │
                   agenthawk.server (thin MCPServer adapter, mcp 2.x)
                          │
                    stdio (NDJSON JSON-RPC)

• core/server split: all logic is pure functions over parsed spans; the MCP layer only parses args and JSON-encodes results. Tests hit both layers.
• trace_id prefixes: agents fumble full 32-char hex ids; every tool accepts prefixes.
• bounded output: diagnostics are truncated and obvious credentials are redacted before query results leave the server.
• cursor polling: recent_activity makes the snapshot reader useful while a run is still writing spans.
• The demo fixture (examples/example_trace.jsonl) is a real agent-harness run, not hand-written.

Research-driven gaps addressed

A small Reddit review surfaced the same production problems repeatedly: auth and identity are unclear after the demo, versions and logs are hard to compare, tool fleets become noisy and expensive, operators lack visibility into what is happening, and raw logs are not a useful analysis surface. Examples:

• ChatGPT + MCP gets painful after the demo — auth, versions, logs, and safe tools.
• MCP logging and correlation IDs — preserve intent, tool arguments, results, and correlation IDs.
• 180 tools becomes a permission/context/debugging problem.
• MCP security — identity, access, credentials, approved versions, and audit logs.
• Raw logs are noisy and hard to query.

This update adds five focused query surfaces rather than pretending a Dashboard solves those problems: failure_report, tool_stats, security_audit, recent_activity, and compare_runs. Trace discovery is also recursive, and query results redact obvious credential patterns.

Honest limitations

• stdio transport only (Streamable HTTP plus authenticated remote access is the next transport boundary)
• live polling re-reads snapshots; it is not a push subscription
• security audit can only report identity/provenance that the trace producer records
• read-only tools; trace mutation (annotations) is roadmap
• mcp_trace remains the compatibility Python import; new code should use agenthawk

License

MIT