CLI Reference

Complete reference for all agentrace command-line interface commands.

Global Options

These options are available for all commands:

--help, -h - Show help information
--version, -V - Show version number

Commands

`agentrace list [options]`

List and discover agent sessions.

Aliases: ls

Description: Lists agent sessions from the last 7 days by default. Supports filtering by agent type, status, and time period. Can automatically scan for new sessions before listing.

Options:

Option	Type	Default	Description
`--agent <name>`	string	-	Filter by agent type: claude-code, codex, openclaw, cursor
`--last <duration>`	string	`7d`	Time period: 7d, 2w, 1m, 6m, 1y
`--status <status>`	string	-	Filter by status: running, completed, failed, abandoned
`--limit <number>`	number	`50`	Maximum number of sessions to show
`--working-dir <path>`	string	-	Filter by working directory (partial match)
`--scan`	boolean	`false`	Scan for new sessions before listing
`--json`	boolean	`false`	Output as JSON instead of table

Examples:

# List recent sessions
agentrace list

# Find all Claude Code sessions from last month
agentrace list --agent claude-code --last 30d

# Show failed sessions with scanning
agentrace list --status failed --scan

# Get JSON output for scripting
agentrace list --json --limit 10

# Filter by working directory
agentrace list --working-dir "/home/user/project"

Output Format:

ID         Agent        Started              Status     Tokens    Cost     Prompt
abc123     claude-code  2026-03-16 07:30     completed  45,230    $1.23    "Fix TypeScript error in main.ts"
def456     codex        2026-03-16 06:15     failed     12,100    $0.34    "Refactor auth module"

Total: 15 sessions (12 completed, 2 failed, 1 running)

`agentrace watch [options]`

Watch and trace a live or recent session.

Description: Monitors agent sessions in real-time, showing events as they happen. If no session is specified, automatically finds and watches the most recent active session.

Options:

Option	Type	Default	Description
`--agent <name>`	string	-	Filter by agent type
`--session <id>`	string	-	Watch specific session ID
`--follow`	boolean	`true`	Follow session updates in real-time
`--interval <ms>`	number	`2000`	Polling interval in milliseconds

Examples:

# Watch most recent active session
agentrace watch

# Watch specific session
agentrace watch --session abc123

# Watch latest Claude Code session
agentrace watch --agent claude-code

# Watch with faster polling
agentrace watch --interval 1000

Output Format:

📺 Watching Session
ID: abc123
Agent: claude-code
Status: 🟡 running
Started: 2026-03-16 7:30:00 AM
Prompt: Fix TypeScript error in main.ts
---

07:30:15 🔧 Read
  file_path: src/main.ts

07:30:18 📋 Read
  Duration: 150ms

07:30:22 🔧 Edit
  file_path: src/main.ts
  old_string: function main() {
  new_string: function main(): void {

Session completed with status: completed

`agentrace replay <session-id> [options]`

Step-by-step replay of a session with rich terminal output.

Description: Replays a completed session event by event, showing tool calls, file changes, costs, and timing. Supports filtering, stepping, and speed control.

Arguments:

<session-id> - Required. The session ID to replay

Options:

Option	Type	Default	Description
`--speed <1-10>`	number	`3`	Replay speed multiplier
`--filter <type>`	string	-	Filter events by type: tool_call, message, error, etc.
`--from <timestamp>`	string	-	Start replay from specific timestamp (ISO 8601)
`--to <timestamp>`	string	-	End replay at specific timestamp (ISO 8601)
`--step`	boolean	`false`	Step through events manually (press Enter)
`--detailed`	boolean	`false`	Show detailed event content

Examples:

# Normal speed replay
agentrace replay abc123

# Fast replay (10x speed)
agentrace replay abc123 --speed 10

# Manual stepping with details
agentrace replay abc123 --step --detailed

# Replay only tool calls
agentrace replay abc123 --filter tool_call

# Replay specific time range
agentrace replay abc123 --from "2026-03-16T07:30:00Z" --to "2026-03-16T07:35:00Z"

Output Format:

🎬 Session Replay
ID: abc123
Agent: claude-code
Started: 2026-03-16 7:30:00 AM
Duration: 25m 30s
Events to replay: 47
Prompt: Fix TypeScript error in main.ts
────────────────────────────────────────────

Progress [████████████████████████████░░] 90% (42/47)

🔧 Event #42 - tool_call
Time: 7:54:22 AM (+24m 22s)
Name: Edit
Duration: 340ms
Tokens: 15

Content:
{
  "file_path": "src/main.ts",
  "old_string": "function main() {",
  "new_string": "function main(): void {"
}

File Changes:
📝 src/main.ts (+1/-1)
────────────────────────────────────────────

`agentrace stats [options]`

Show analytics dashboard with session statistics.

Description: Displays comprehensive analytics including success rates, token usage, cost analysis, most-used tools, and pattern detection.

Options:

Option	Type	Default	Description
`--last <duration>`	string	`7d`	Time period to analyze
`--agent <name>`	string	-	Filter by agent type
`--by <grouping>`	string	`agent`	Group stats by: day, week, agent, model
`--costs`	boolean	`false`	Include detailed cost breakdown
`--patterns`	boolean	`false`	Include pattern analysis
`--json`	boolean	`false`	Output as JSON

Examples:

# Basic stats for last week
agentrace stats

# Comprehensive analysis for last month
agentrace stats --last 30d --costs --patterns

# Claude Code specific stats
agentrace stats --agent claude-code --costs

# Group by model usage
agentrace stats --by model

# Daily breakdown
agentrace stats --by day --last 14d

Output Format:

📊 Session Statistics

Total Sessions    25
Total Tokens      127,450
Total Cost        $3.82
Success Rate      88.0%
Avg Duration      18.4m

🔧 Most Used Tools
Tool       Count
Read       89
Edit       67
Write      34
Bash       23
Grep       18

📁 Most Changed Files
File                          Changes
src/components/Button.tsx     12
src/utils/helpers.ts         8
README.md                    6
package.json                 4
src/types/index.ts          3

💡 Recommendations:
• ✅ Excellent success rate! Your agents are performing well.
• 🔥 High activity! Consider monitoring for potential loops.

`agentrace diff <session-a> <session-b> [options]`

Side-by-side comparison of two sessions.

Description: Compares two sessions across multiple dimensions including duration, tokens, costs, tools used, files modified, and performance metrics.

Arguments:

<session-a> - Required. First session ID to compare
<session-b> - Required. Second session ID to compare

Options:

Option	Type	Default	Description
`--metrics-only`	boolean	`false`	Show only metric comparison
`--events`	boolean	`false`	Include detailed event comparison
`--files`	boolean	`false`	Include file change comparison
`--json`	boolean	`false`	Output as JSON

Examples:

# Compare two sessions
agentrace diff abc123 def456

# Include file changes
agentrace diff abc123 def456 --files

# Detailed comparison
agentrace diff abc123 def456 --events --files

# JSON output for analysis
agentrace diff abc123 def456 --json

Output Format:

🔄 Session Comparison

Metric           Session A    Session B    Difference
Agent            claude-code  claude-code  =
Status           completed    failed
Duration         25m 30s      15m 12s      -10m 18s
Tokens           45,230       28,100       -17,130
Cost             $1.23        $0.76        -$0.47
Events           89           52           -37
File Changes     12           8            -4
Model            claude-3-sonnet claude-3-sonnet =

⚡ Performance Metrics
Metric              Session A  Session B  Winner
Tokens/min          1774.1     1848.7     B
Events/min          3.5        3.4        A
Cost/1K tokens      $0.0272    $0.0270    B

💡 Insights
• ⚡ Session B was 1.7x faster than Session A
• ❌ Session B failed while Session A completed successfully
• 📁 High file overlap (75%) - similar work patterns

`agentrace export <session-id> [options]`

Export session as shareable document.

Description: Exports session data in various formats including Markdown reports, JSON data dumps, and HTML documents. Supports including analysis and cost data.

Arguments:

<session-id> - Required. The session ID to export

Options:

Option	Type	Default	Description
`--format <format>`	string	`markdown`	Output format: markdown, json, html
`--output <file>`	string	`session-{id}.{ext}`	Output file path
`--include-costs`	boolean	`false`	Include cost analysis
`--include-patterns`	boolean	`false`	Include pattern analysis
`--include-timeline`	boolean	`false`	Include detailed timeline
`--detailed`	boolean	`false`	Include full event content

Examples:

# Export as Markdown
agentrace export abc123

# Comprehensive JSON export
agentrace export abc123 --format json --detailed --include-costs --include-patterns

# Custom filename with analysis
agentrace export abc123 --output my-report.md --include-timeline

# HTML report
agentrace export abc123 --format html --include-costs

Output:

✅ Export successful!
File: session-abc123.md
Format: markdown
Size: 47.2 KB

Session summary:
  Events: 89
  File Changes: 12
  Duration: 25m 30s

Exported Formats:

Markdown: Human-readable report with tables, timeline, and analysis
JSON: Complete machine-readable data dump with all session details
HTML: Styled web page with interactive elements

`agentrace serve [options]`

Start MCP server for programmatic access.

Description: Starts an HTTP server that exposes agentrace functionality via the Model Context Protocol (MCP). Enables AI agents to query their own session history.

Options:

Option	Type	Default	Description
`--port <port>`	number	`3000`	Port to listen on
`--auto-scan`	boolean	`false`	Scan for sessions on startup
`--scan-interval <minutes>`	number	`0`	Auto-scan interval (0 to disable)

Examples:

# Start on default port
agentrace serve

# Custom port with auto-scanning
agentrace serve --port 8080 --auto-scan

# Auto-scan every 5 minutes
agentrace serve --scan-interval 5

Output:

🚀 Starting agentrace MCP Server
Port: 3000
Detected adapters: claude-code, codex

✅ MCP Server running on port 3000

Available MCP Tools:
  • query_sessions    - Search and filter sessions
  • get_timeline      - Get session event timeline
  • get_stats         - Get aggregate statistics
  • get_file_changes  - Get file change history
  • scan_for_sessions - Scan for new sessions

API Endpoints:
  POST http://localhost:3000/  - MCP JSON-RPC requests

Press Ctrl+C to stop the server

Duration Format

Duration strings support the following units:

d - Days (e.g., 7d, 30d)
w - Weeks (e.g., 2w, 4w)
m - Months (e.g., 1m, 6m)
y - Years (e.g., 1y)

Examples:

7d - Last 7 days
2w - Last 2 weeks
1m - Last month
3m - Last 3 months
1y - Last year

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Session not found
4	Database error
5	Network error (MCP server)

Environment Variables

Variable	Description	Default
`AGENTRACE_DB_PATH`	Custom database location	`~/.agentrace/agentrace.db`
`AGENTRACE_LOG_LEVEL`	Logging level	`info`

Example:

export AGENTRACE_DB_PATH="/custom/path/agentrace.db"
export AGENTRACE_LOG_LEVEL="debug"
agentrace list

Configuration Files

agentrace is zero-configuration by design. All settings are controlled via command-line options and environment variables.

Troubleshooting

Common Issues

No sessions found:

# Scan for new sessions
agentrace list --scan

# Check agent directories exist
ls ~/.claude/projects/
ls ~/.codex/sessions/

Performance issues:

# Limit query scope
agentrace list --last 7d --limit 20

# Use JSON for processing
agentrace stats --json | jq '.basic_stats'

Database locked:

# Check for running agentrace processes
ps aux | grep agentrace

# Force unlock (last resort)
rm ~/.agentrace/agentrace.db-wal

Debug Mode

Enable debug logging:

AGENTRACE_LOG_LEVEL=debug agentrace list --scan

Getting Help

agentrace --help - General help
agentrace <command> --help - Command-specific help
GitHub Issues
Documentation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Reference

Global Options

Commands

`agentrace list [options]`

`agentrace watch [options]`

`agentrace replay <session-id> [options]`

`agentrace stats [options]`

`agentrace diff <session-a> <session-b> [options]`

`agentrace export <session-id> [options]`

`agentrace serve [options]`

Duration Format

Exit Codes

Environment Variables

Configuration Files

Troubleshooting

Common Issues

Debug Mode

Getting Help

FilesExpand file tree

cli-reference.md

Latest commit

History

cli-reference.md

File metadata and controls

CLI Reference

Global Options

Commands

agentrace list [options]

agentrace watch [options]

agentrace replay <session-id> [options]

agentrace stats [options]

agentrace diff <session-a> <session-b> [options]

agentrace export <session-id> [options]

agentrace serve [options]

Duration Format

Exit Codes

Environment Variables

Configuration Files

Troubleshooting

Common Issues

Debug Mode

Getting Help

`agentrace list [options]`

`agentrace watch [options]`

`agentrace replay <session-id> [options]`

`agentrace stats [options]`

`agentrace diff <session-a> <session-b> [options]`

`agentrace export <session-id> [options]`

`agentrace serve [options]`