agenttrace

See what your AI agent does, why it decides, and where it fails.

MCP server CLI viewer zero dependencies file-based MIT license

The problem

AI agents work in a black box — you can't see what's happening until something breaks
No standard way to log agent decisions, reasoning, or tool calls
Post-mortem debugging without structured traces wastes hours
Existing observability tools are built for microservices, not agents

The solution

7 MCP tools that any AI agent can call to trace its own execution
Structured events: steps, decisions (with reasoning), errors
File-based JSON storage — human-readable, git-friendly, no database
CLI viewer with color-coded output, real-time watch mode
Works with Claude Code, Cursor, or any MCP client

Install

npm install -g @ura-dev/agentrace

Add to your AI tool config:

{
  "mcpServers": {
    "agentrace": { "command": "agentrace-mcp" }
  }
}

MCP Tools

trace_start

Start a new trace session for a task

trace_step

Log each action: tool call, file read, code change

trace_decision

Record decision points with options and reasoning

trace_error

Capture errors with context and recoverability

trace_end

End a trace with status and summary

trace_list

List recent traces across sessions

What the output looks like

refactor auth module [b665af12f975]
agent: claude-code | status: completed | 2.3s | 5 events
────────────────────────────────────────
14:23:01 >> [Glob] read codebase
       src/auth/**/*.ts → 12 files
14:23:01 >> [Read] analyze auth middleware (150ms)
14:23:02 ?? Session storage approach?
       * JWT with httpOnly cookies
         Server-side sessions
         reason: Stateless, no DB dependency
14:23:02 !! Token validation fails on refresh [AUTH_003]
       context: existing refresh token logic
14:23:03 >> [Edit] fix token refresh flow
────────────────────────────────────────
Result: Auth module refactored, refresh flow fixed

CLI

agentrace list              # Recent traces
agentrace view <trace-id>   # Full trace with all events
agentrace watch <trace-id>  # Real-time tail of active trace
agentrace stats             # Trace statistics

As a library

const { createTrace, addStep, addDecision, endTrace } = require('@ura-dev/agentrace');

const { id } = createTrace({ name: 'deploy', agent: 'my-agent' });
addStep(id, { action: 'build', tool: 'npm', output: 'ok' });
addDecision(id, {
  question: 'Deploy target?',
  chosen: 'staging',
  reasoning: 'Friday — no prod deploys'
});
endTrace(id, { status: 'completed' });