Skip to main content
This guide walks you through using Tracer for the first time. You’ll initialize a project, create issues, track dependencies, and find ready work.

​
Step 1: Initialize Tracer

Navigate to your project directory and initialize Tracer: 
cd ~/my-project
tracer init
By default, Tracer uses the prefix bd for issue IDs (e.g., bd-1, bd-2). You can customize this with tracer init --prefix myapp.
You should see: 
✓ Initialized tracer database at /path/to/my-project/.trace/bd.db
  Prefix: bd
  JSONL: /path/to/my-project/.trace/issues.jsonl

Next steps:
  1. Create your first issue: tracer create "My first task"
  2. See ready work: tracer ready
  3. Add to git: git add .trace/issues.jsonl
This creates two files:
  • .trace/bd.db - SQLite database for fast queries
  • .trace/issues.jsonl - Git-friendly export for version control

​
Step 2: Create Your First Issue

Let’s create a feature to implement: 
tracer create "Implement user authentication" -p 1 -t feature
Output: 
✓ Created issue bd-1 Implement user authentication
Priority ranges from 0 (highest) to 4 (lowest). Default is 2. Issue types include: task, bug, feature, epic, chore.

​
Step 3: Break Down Work

Large features should be broken into smaller tasks. Let’s create an epic with subtasks:
1

Create the epic

tracer create "User authentication system" -t epic -p 0
# Creates bd-2
2

Create subtasks

tracer create "Design auth database schema" -t task -p 1
# Creates bd-3

tracer create "Implement login endpoint" -t task -p 1
# Creates bd-4

tracer create "Add session management" -t task -p 1
# Creates bd-5
3

Link subtasks to epic

tracer dep add bd-3 bd-2 --type parent-child
tracer dep add bd-4 bd-2 --type parent-child
tracer dep add bd-5 bd-2 --type parent-child
4

Add blocking dependencies

The login endpoint and session management both depend on the schema being designed first:
tracer dep add bd-4 bd-3 --type blocks
tracer dep add bd-5 bd-3 --type blocks

​
Step 4: Find Ready Work

Now let’s see what’s ready to work on: 
tracer ready
Output: 
✓ Ready work: 2 issue(s)

bd-1 Implement user authentication [P1, feature]
  Status: open
  Created: 2026-03-04 10:00 | Updated: 2026-03-04 10:00

bd-3 Design auth database schema [P1, task]
  Status: open
  Created: 2026-03-04 10:05 | Updated: 2026-03-04 10:05
Issues bd-4 and bd-5 don’t show up because they’re blocked by bd-3. Tracer automatically analyzes the dependency graph.

​
Step 5: Start Working

Pick an issue and mark it as in progress: 
tracer update bd-3 --status in_progress
When you set status to in_progress, Tracer auto-assigns the issue to your actor name (from TRACE_ACTOR env var or system username).
Check the status: 
tracer show bd-3
Output: 
bd-3: Design auth database schema

  Status:       in_progress
  Type:         task
  Priority:     1
  Assignee:     your-username
  Created:      2026-03-04 10:05:00
  Updated:      2026-03-04 10:10:00

  Dependencies:
    • bd-3 blocks bd-4 (Implement login endpoint)
    • bd-3 blocks bd-5 (Add session management)
    • bd-3 is child of bd-2 (User authentication system)

​
Step 6: Track Discovered Work

While working on bd-3, you discover a bug. File it immediately: 
tracer create "Fix null handling in user table" -t bug -p 0
# Creates bd-6

tracer dep add bd-6 bd-3 --type discovered-from
This links the bug back to the task where you found it, maintaining context.

​
Step 7: Add Comments

Leave notes for yourself or other agents: 
tracer comment bd-3 "Using PostgreSQL schema with UUID primary keys"
Comments appear when you tracer show bd-3.

​
Step 8: Complete Work

Once you’re done, close the issue: 
tracer close bd-3 --reason "Schema designed and tested"
Now check ready work again: 
tracer ready
Output: 
✓ Ready work: 4 issue(s)

bd-1 Implement user authentication [P1, feature]
bd-4 Implement login endpoint [P1, task]
bd-5 Add session management [P1, task]
bd-6 Fix null handling in user table [P0, bug]
Issues bd-4 and bd-5 are now ready because their blocker (bd-3) is closed!

​
Step 9: Check Progress

View overall statistics: 
tracer stats
Output: 
Issue Statistics

  Total Issues:      6
  Open:              4
  In Progress:       0
  Blocked:           0
  Closed:            1

  Ready to Work:     4

  Avg Lead Time:     5 minutes

​
Step 10: Commit to Git

Tracer auto-exports changes to .trace/issues.jsonl. Commit it: 
git add .trace/issues.jsonl
git commit -m "Add authentication feature tasks"
Add .trace/*.db to your .gitignore. Only commit the .jsonl file, not the SQLite database.

​
Multi-Agent Workflow

If multiple AI agents work on the same project, use the --actor flag to identify who’s doing what: 
# Agent 1 claims work
tracer --actor agent-1 update bd-4 --status in_progress
tracer --actor agent-1 comment bd-4 "Working on login endpoint"
Set export TRACE_ACTOR=agent-name in your environment to avoid typing --actor every time.

​
JSON Output for AI Agents

All commands support --json for programmatic parsing: 
tracer ready --json | jq '.[0].id'
# Output: "bd-1"

tracer ready --json | jq 'length'
# Output: 4
Example JSON structure: 
[
  {
    "id": "bd-1",
    "title": "Implement user authentication",
    "status": "open",
    "priority": 1,
    "issue_type": "feature",
    "assignee": "",
    "created_at": "2026-03-04T10:00:00Z",
    "updated_at": "2026-03-04T10:00:00Z",
    "dependencies": []
  }
]

​
Common Commands Reference

# Basic task
tracer create "Fix bug in parser"

# With all options
tracer create "Add feature X" -p 0 -t feature -l backend,api

# With dependencies
tracer create "Test feature X" --deps blocks:bd-10

​
Dependency Types Explained

blocks

Issue A blocks Issue BB cannot start until A is complete. Use for sequential work.Example: Schema design blocks API implementation

parent-child

Issue B is child of Issue AB is a subtask of epic A. Use for breaking down large features.Example: “Login endpoint” is child of “Auth system”

discovered-from

Issue B was discovered while working on Issue ATracks where bugs/tasks were found. Maintains context.Example: Found a null pointer bug while implementing a feature

related

Issues A and B are relatedConnected but don’t block. Use for cross-references.Example: Two features that share code

​
Next Steps

You now know the basics! Here’s what to explore next:

Advanced Features

  • Dependency tree visualization with tracer dep tree
  • Export/import for backup and migration
  • Custom ID prefixes for multiple projects
  • Label management and filtering

Integration Tips

  • Use --json flag for script integration
  • Set TRACE_ACTOR for multi-agent setups
  • Commit .jsonl files, ignore .db files
  • Auto-discover database with parent directory walking
Tracer automatically discovers the database by walking up parent directories, just like git. Run tracer commands from anywhere in your project.

Build docs developers (and LLMs) love

Get started for freeTalk to us