> ## Documentation Index
> Fetch the complete documentation index at: https://abil-shrestha-tracer.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Lightweight issue tracker designed for AI agents to coordinate work and track dependencies

## What is Tracer?

Tracer is a lightweight, CLI-based issue tracker specifically designed for AI agents. It helps agents track tasks, manage dependencies between work items, and coordinate when multiple agents work on the same project.

Unlike traditional issue trackers that focus on human collaboration, Tracer is optimized for:

* AI agents that need to maintain context across sessions
* Long-horizon tasks that span multiple conversations
* Multi-agent workflows where different AI agents coordinate on shared work
* Git-based workflows with JSONL storage for easy version control

## Key Features

### Dependency Tracking

Tracer understands relationships between tasks with four dependency types:

* **blocks** - Task A cannot start until Task B is complete
* **parent-child** - Task B is a subtask of epic A
* **discovered-from** - Task B was found while working on Task A
* **related** - Tasks A and B are connected but don't block each other

### Ready Work Detection

Automatically identifies which issues are ready to start by analyzing the dependency graph:

```bash theme={null}
tracer ready
# Shows only issues with no blockers

tracer blocked
# Shows issues that are blocked and what's blocking them
```

### Multi-Agent Coordination

Multiple AI agents can work together on the same project:

* Auto-assignment when agents start work
* Comment threads for agent communication
* Audit trail showing who did what and when
* Actor identification with `--actor` flag

### JSON Output for AI Consumption

Every command supports `--json` flag for programmatic parsing:

```bash theme={null}
tracer ready --json
tracer show bd-1 --json
tracer stats --json
```

### Git-Friendly Storage

Tracer uses SQLite for local operations and JSONL for version control:

* Database stored in `.trace/<prefix>.db`
* Auto-exports to `.trace/issues.jsonl` for git tracking
* Auto-imports changes pulled from remote
* Handles merge conflicts gracefully

## Use Cases for AI Agents

> **Long-Horizon Planning**
>
> Break down complex features into trackable tasks that persist across sessions. AI agents can pick up where they left off.

> **Discovered Work**
>
> File bugs and tasks as you discover them during implementation. Link them back to parent work with `discovered-from` dependencies.

> **Multi-Agent Projects**
>
> Multiple agents coordinate by checking ready work, leaving comments, and tracking who's working on what.

> **Dependency Management**
>
> Understand which tasks block others. Agents can work on unblocked tasks while waiting for dependencies.

## How It Works

**1. Initialize in your project**

Run `tracer init` to create the `.trace` directory with a SQLite database and JSONL file.

**2. Create issues as you work**

Use `tracer create` to file tasks, bugs, features, and epics. Add dependencies to show relationships.

**3. Find ready work**

Run `tracer ready` to see what's unblocked and ready to start. The dependency graph is analyzed automatically.

**4. Update as you progress**

Mark issues as `in_progress`, add comments, and close when complete. All changes sync to JSONL.

**5. Commit to git**

The `.trace/issues.jsonl` file is designed for version control. Commit it alongside your code changes.

## Example Workflow

```bash theme={null}
# Agent starts session - what's ready?
tracer ready --limit 3

# Pick highest priority work
tracer update bd-8 --status in_progress

# Work on it, discover an issue
tracer create "Add tests for validation" -t task -p 1
tracer dep add bd-12 bd-8 --type discovered-from

# Complete the work
tracer close bd-8 --reason "Fixed validation and added tests"

# Check overall progress
tracer stats
```

> [!NOTE]
>
> Tracer's SQLite database is the source of truth during work. Changes automatically export to JSONL for git tracking.

## Architecture

Tracer is built in Rust for performance and reliability:

* **Storage**: SQLite for fast queries, JSONL for git sync
* **CLI**: Clap for argument parsing, colored output for humans
* **Auto-discovery**: Walks parent directories to find `.trace` like git does
* **Actor tracking**: Every change records who made it
* **Dirty tracking**: Only modified issues export to JSONL

## Next Steps

> **[Installation](https://abil-shrestha-tracer.mintlify.site/installation.md)**
>
> Install Tracer using cargo or from source

> **[Quick Start](https://abil-shrestha-tracer.mintlify.site/quickstart.md)**
>
> Get started with your first project in 5 minutes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.