Quick Start

Get started with Tracer in 5 minutes - from initialization to tracking your first issues

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

# 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

Create Issues

# 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 B

B cannot start until A is complete. Use for sequential work.

Example: Schema design blocks API implementation

parent-child

Issue B is child of Issue A

B 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 A

Tracks where bugs/tasks were found. Maintains context.

Example: Found a null pointer bug while implementing a feature

related

Issues A and B are related

Connected 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.