Skip to main content

​
Why Use Tracer for AI Agents?

Tracer is designed to help AI agents (Claude, GPT, Cursor, etc.) maintain context, coordinate work, and organize tasks more effectively than traditional markdown TODOs.

​
For Long-Horizon Tasks

Tracer helps maintain context across sessions:
  • Persistent work lists - Your tasks persist between conversations
  • Dependency tracking - Never forget what’s blocking what
  • Discovered work tracking - Issues found during work don’t get lost

​
For Multi-Agent Coordination

Multiple agents can work on the same project:
  • Git-based sync - Database syncs across machines via Git
  • Ready work detection - Prevents conflicts by showing unblocked work
  • Audit trail - Track who did what and when

​
For Better Organization

Move beyond markdown TODOs:
  • Proper epics and subtasks - Organize complex features hierarchically
  • Dependency tracking - Model blocking relationships explicitly
  • Priority management - Focus on what matters most
  • Status updates - Track progress in real-time
Tracer is particularly valuable for agents working on projects that span multiple sessions or involve complex dependency chains.

​
Core Workflow Overview

AI agents should follow this workflow when using Tracer:
1

Find Ready Work

Check for unblocked tasks at the start of each session using tracer ready --json
2

Claim and Start

Update the issue status to in_progress to claim the work
3

Create Issues During Work

File new issues as you discover them, linking them back to the parent task
4

Add Dependencies

Model blocking relationships and epic structures as you discover them
5

Complete Work

Close issues with meaningful completion messages
6

Check Status

Review overall progress with tracer stats

​
Quick Start

# Initialize tracer in your project
tracer init

​
Key Benefits

Unlike conversation-based task lists, Tracer persists your work across sessions. When you return to a project, tracer ready immediately shows you what’s unblocked and ready to work on.
Tracer prevents you from starting work that’s blocked by other tasks. The dependency system ensures you always work on tasks that can actually be completed.
When you discover bugs or additional work while implementing a feature, Tracer lets you file them immediately and link them back to the parent task using discovered-from relationships.
Multiple agents (or humans) can work on the same Tracer database. Git syncing ensures everyone sees the same view of the work, and the ready work algorithm prevents conflicts.

​
When to Use Tracer

Use Tracer when:
  • Working on projects that span multiple sessions
  • Building features with complex dependencies
  • Coordinating with other agents or humans
  • Managing long-horizon tasks with many subtasks
Consider alternatives when:
  • Working on simple, single-session tasks
  • The project has no dependencies or complexity
  • You need a lightweight TODO list only

​
JSON-First Design

All Tracer commands support --json output for programmatic parsing: 
# Get ready work in JSON format
tracer ready --json

# Create issue and capture ID
NEW_ID=$(tracer create "Fix bug" -t bug --json | jq -r '.id')

# Check stats programmatically
tracer stats --json
This makes it easy to integrate Tracer into agent workflows and scripts.

​
Next Steps

Agent Workflow

Learn the detailed workflow from finding work to completion

JSON Output

Understand JSON formats for all commands

Best Practices

Follow proven patterns for agent integration

CLI Reference

Complete command reference

Build docs developers (and LLMs) love

Get started for freeTalk to us