@ura-dev/agentrace

agentrace

Structured observability for AI agents. See what your agent does, why it decides, and where it fails.

MCP server + CLI viewer. Zero dependencies. Works with Claude Code, Cursor, or any MCP client.

Install

# CLI only (global)
npm install -g @ura-dev/agentrace

# As a library in your project
npm install @ura-dev/agentrace

Usage

After install, the agentrace CLI and MCP server are available globally.

# View recent traces
agentrace list

# View a specific trace
agentrace view <trace-id>

# Watch a trace in real-time
agentrace watch <trace-id>

# Show statistics
agentrace stats

MCP Setup

Add to your AI tool config:

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

Your AI agent now has access to structured tracing tools.

MCP Tools

Tool	Description
trace_start	Start a new trace session
trace_step	Log a step (action, tool used, input/output)
trace_decision	Log a decision point (options, chosen, reasoning)
trace_error	Log an error or unexpected state
trace_end	End a trace session
trace_list	List recent traces
trace_view	View a complete trace

CLI

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

How it works

When an AI agent starts a complex task, it calls trace_start. As it works, it logs each step (trace_step), records decision points (trace_decision), and captures errors (trace_error). When done, it calls trace_end.

Traces are stored as JSON files in ~/.agentrace/traces/. You can view them with the CLI, or read them directly.

As a library

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

const { id } = createTrace({ name: 'deploy pipeline', agent: 'my-agent' });
addStep(id, { action: 'build', tool: 'npm', output: 'success' });
addDecision(id, { question: 'Deploy target?', chosen: 'staging', reasoning: 'Friday deploy' });
endTrace(id, { status: 'completed', summary: 'Deployed to staging' });

Config

Env var	Description
AGENTRACE_DIR	Override storage directory (default: ~/.agentrace)

License

MIT — ura