Skip to content
/
Tier B A8 Cross-runtime harness

Tracer

tracer-issue-tracker · Abil-Shrestha/tracer · ★ 20 · last commit 2025-10-21

Dependency-aware JSONL issue tracker for AI agents with a ready-queue that surfaces only unblocked work.

Best whenAgents should only be offered work they can complete without conflicts; typed dependency relationships prevent starting blocked tasks.
Skip ifWorking on issues with unresolved blockers
vs seeds
taskmaster-ai(AI-agent-native file-based task tracker with CLI) but differs by using JSONL storage instead of JSON, implementing type…
Primitive shape 11 total
Commands 11
00

Summary

Tracer — Summary

Tracer is a lightweight, dependency-aware issue tracker for AI coding agents, written in Rust and installable via cargo install. It stores issues as JSONL files in a git-friendly format so multiple agents can work on the same project simultaneously without database coordination. The key differentiator is first-class dependency tracking: tasks have blocks, parent-child, related, and discovered-from relationships, and a tracer ready command surfaces only unblocked work — preventing agents from starting tasks they cannot complete. Multi-agent coordination happens through the comment system and auto-assignment when an issue transitions to in_progress, all with --json output for programmatic parsing.

Compared to seeds: most similar to taskmaster-ai (file-based task tracker for AI agents with CLI interface) but differs by using JSONL storage instead of JSON, implementing typed dependency relationships as a first-class feature, and being written in Rust for zero-runtime-dependency installation. Unlike backlog-md, there is no web UI, no MCP server, and no markdown-per-task format.

01

Overview

Tracer — Overview

Origin

Created by Abil Shrestha. 20 GitHub stars, MIT licensed, Rust, last commit 2025-10-21.

Philosophy

"Lightweight issue tracker for AI agents. Tracks dependencies between tasks and coordinates multiple agents working on the same project."

Tracer's philosophy is minimalism: the smallest possible tool that enables multi-agent coordination without requiring any external services. No database, no server, no API keys — just JSONL files in a git repo.

Design Principles

  • Dependency-first: the tracer ready command is the primary workflow primitive — it tells agents what they can start right now without conflicts
  • Git-native: JSONL files are diff-friendly and merge-safe
  • AI-first output: --json flag on every command for programmatic parsing by agents
  • Auto-discovery: finds the database by traversing directories upward (like git)
  • Minimal coordination surface: agents coordinate through task state (status, assignee, comments) rather than a central scheduler

Documents

  • AGENTS.md — AI agent integration guide
  • MULTI_AGENT.md — multi-agent coordination patterns
02

Architecture

Tracer — Architecture

Distribution

Rust binary installed via cargo:

cargo install --git https://github.com/Abil-Shrestha/tracer

Requires Rust toolchain (rustup.rs).

Install Complexity

Multi-step (requires Rust toolchain; cargo install compiles from source)

Required Runtime

  • Rust toolchain (via rustup)
  • Git (recommended)

Directory Tree (after tracer init)

<project-root>/
├── .tracer/
│   └── issues.jsonl      # All issues + comments in JSONL format
├── AGENTS.md             # AI agent integration guide
└── MULTI_AGENT.md        # Multi-agent coordination docs

JSONL Storage Format

Each line is a JSON object representing an issue or comment. Auto-discovered by walking up the directory tree.

Target AI Tools

Any AI agent that can execute bash commands (Claude, GPT, Cursor, etc.)

Source Layout

src/
├── main.rs        # CLI entry point + command dispatch
Cargo.toml         # Rust project config
03

Components

Tracer — Components

CLI Binary: tracer

Command Purpose
tracer init Initialize .tracer/ database in current project
tracer create "Title" [-p priority] [-t type] Create a new issue
tracer list [--status STATUS] List issues with optional status filter
tracer show <id> Show full issue details including comments
tracer update <id> --status STATUS Update issue status (auto-assigns when → in_progress)
tracer close <id> Close an issue
tracer comment <id> "message" Add comment to issue
tracer dep add <from> <to> --type TYPE Add typed dependency between issues
tracer ready Show only unblocked, ready-to-start issues
tracer stats Show project statistics
tracer blocked Show blocked issues

All commands support --json flag for machine-readable output.

Actor Flag

--actor <name> — specify which agent is performing the action (used for auto-assignment and audit trail)

Dependency Types

Type Meaning
blocks Issue A blocks issue B (B cannot start until A is closed)
parent-child Hierarchical relationship (epic → task)
related Informational relationship
discovered-from Issue was created while working on another issue

No MCP Server, No Skills, No Hooks

Tracer is a pure CLI tool. No MCP server, no skill files, no hook events. Integration with AI agents happens via AGENTS.md instruction file and JSON output parsing.

05

Prompts

Tracer — Prompt Files

Verbatim Excerpt 1: AGENTS.md — Core Workflow Section

Prompting technique: Numbered step scaffolding with concrete command examples

## Core Workflow for AI Agents

### 1. Find Ready Work

At the start of any session, check for ready work:

```bash
# Get unblocked work in JSON format
tracer ready --json

# Filter by priority
tracer ready --priority 1 --json

# Limit results
tracer ready --limit 5 --json

2. Claim and Start Work

# Update issue to in_progress
tracer update <issue-id> --status in_progress --json

3. Create Issues During Work

As you discover new work, file it immediately:

# Create a bug you found
tracer create "Fix edge case in validation" -t bug -p 0 --json

# Link it back to parent work with discovered-from
tracer dep add <new-issue-id> <parent-issue-id> --type discovered-from


## Verbatim Excerpt 2: AGENTS.md — JSON Output Format

**Prompting technique**: Schema documentation for structured output parsing

```markdown
## JSON Output Format

All commands support `--json` for programmatic parsing:

### Ready Work Response

```json
[
  {
    "id": "bd-1",
    "title": "Implement user authentication",
    "status": "todo",
    "priority": 1,
    "type": "feature",
    "dependencies": [],
    "assignee": null
  }
]


## Verbatim Excerpt 3: Multi-agent coordination README

**Prompting technique**: Concrete scenario walkthrough with sequential commands

```markdown
## Multi-Agent Coordination

```bash
# Agent 1 starts work
tracer --actor agent-1 update bd-1 --status in_progress
tracer comment bd-1 "Working on auth API"

# Agent 2 sees it
tracer show bd-1  # Shows assignee and comments
tracer comment bd-1 "I'll test it when ready"

# Agent 1 finishes
tracer close bd-1

Auto-assigns agent when status changes to in_progress. Comments show up in tracer show.
09

Uniqueness

Tracer — Uniqueness & Positioning

Differs from Seeds

Tracer is most similar to taskmaster-ai in the seeds — both are AI-agent-native task trackers with CLI interfaces. The architectural delta: taskmaster-ai is JavaScript/JSON with an MCP server and complex nested task schemas, while Tracer is Rust/JSONL with zero runtime dependencies and a focus on dependency-graph navigation as the primary multi-agent primitive. Tracer's tracer ready command (surfacing only unblocked work) is not found in taskmaster-ai or any seed. Unlike backlog-md (which stores each task as a separate .md file and ships a web UI), Tracer uses a single append-only JSONL file and has no UI. The Rust implementation means cargo install produces a standalone binary with no Node.js/Python runtime requirement.

Distinctive Positioning

  • Typed dependency relationships (blocks, parent-child, related, discovered-from) as first-class schema — unique in this batch
  • tracer ready — dependency-aware work queue surfacing only unblocked items
  • Zero runtime dependency: single Rust binary
  • JSONL append-only format: safe for concurrent writes without locking

Observable Failure Modes

  • High installation friction: requires Rust toolchain (cargo install)
  • No conflict detection: if two agents update the same issue simultaneously, last writer wins
  • No search: only filter by status/priority — no full-text search across issue descriptions
  • No web UI or MCP interface — requires shell access, limiting use in sandboxed environments
  • Low adoption (20 stars) — limited community feedback on edge cases
04

Workflow

Tracer — Workflow

Core Agent Workflow

Step 1 — Find Ready Work

tracer ready --json          # Unblocked issues
tracer ready --priority 1    # Filter by priority

Step 2 — Claim Work

tracer update bd-1 --status in_progress    # Auto-assigns to actor

Step 3 — Create Issues During Work

tracer create "Fix edge case in validation" -t bug -p 0
tracer dep add <new-id> <parent-id> --type discovered-from

Step 4 — Add Dependencies

tracer dep add bd-2 bd-1 --type blocks    # bd-2 blocked by bd-1
tracer dep add bd-3 bd-1 --type parent-child

Step 5 — Complete

tracer close bd-1 --reason "Implemented and tested"

Multi-Agent Coordination Flow

Agent 1: tracer --actor agent-1 update bd-1 --status in_progress
Agent 1: tracer comment bd-1 "Working on auth API"
Agent 2: tracer show bd-1              # Sees assignee + comments
Agent 2: tracer comment bd-1 "I'll test it when ready"
Agent 1: tracer close bd-1
Agent 2: tracer ready --json           # bd-1 removed from ready list; its dependents now appear

Approval Gates

None. Tracer is fully autonomous — no human approval gates built in.

Artifacts

Artifact Location
Issue database .tracer/issues.jsonl
Agent instructions AGENTS.md, MULTI_AGENT.md
06

Memory Context

Tracer — Memory & Context

State Storage

  • Format: JSONL (newline-delimited JSON)
  • Location: .tracer/issues.jsonl
  • Discovery: Auto-discovery like git — walks up directory tree to find .tracer/

Persistence

  • Scope: Project-scoped
  • Git integration: JSONL format is diff-friendly; each issue update appends a line

Cross-Session Handoff

Issue state (status, assignee, comments) persists between sessions. Agent 2 can pick up where Agent 1 left off by reading tracer show <id> --json.

Memory Type

File-based (JSONL). No search mechanism beyond status/priority filters.

No Compaction

Append-only log format. No explicit compaction mechanism described.

07

Orchestration

Tracer — Orchestration

Multi-Agent Support

Yes. tracer ready is the core multi-agent primitive — it returns only unblocked issues, preventing duplicate work pickup. The --actor flag identifies which agent is performing actions.

Orchestration Pattern

Task-decomposition-tree: Parent-child and dependency relationships define a task DAG; tracer ready surfaces the frontier (unblocked leaves).

Isolation Mechanism

None. Agents share the same working tree. Coordination is through JSONL state only.

Execution Mode

One-shot per command. No continuous daemon.

Multi-Model

No. Tracer is model-agnostic.

Consensus Mechanism

None. First agent to update status wins. No conflict detection.

Prompt Chaining

No explicit prompt chaining. Tracer is a data store, not an orchestrator.

08

Ui Cli Surface

Tracer — UI & CLI Surface

CLI Binary

Binary name: tracer Language: Rust Installation: cargo install --git https://github.com/Abil-Shrestha/tracer

Subcommands: init, create, list, show, update, close, comment, dep add, ready, stats, blocked

All commands: --json flag for machine-readable output

Local UI

None.

IDE Integration

None explicitly. Works with any IDE/agent that can execute bash commands.

Observability

  • tracer stats --json — project-level statistics
  • Comments on issues serve as audit trail
  • JSONL file is human-readable and git-diffable

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.