CLI Reference

Install

# Go install (binary includes embedded workflows)
go install github.com/2389-research/tracker/cmd/tracker@latest

# Homebrew
brew install 2389-research/tap/tracker

# Or build from source
git clone https://github.com/2389-research/tracker
cd tracker && make install

# Verify installation
tracker doctor

# Stay current (checks automatically, or run manually)
tracker update

Commands

Running Pipelines

Workflow Management

Validation & Simulation

Headless & Integration

Autopilot

Diagnostics

Setup

Flags

Flags can appear before or after the pipeline argument.

Exit codes v0.35.0

tracker run uses three distinguishable exit codes so CI integrations can branch on terminal status without parsing stdout.

Generic failures dominate --fail-on-override: a run that fails after an override exits 1, not 2. Without the flag, override runs exit 0 — an override is a deliberate operator decision and the default treats it as audit-positive. CI pipelines that should NOT auto-deploy on overrides must opt in:

tracker run --fail-on-override workflow.dip && deploy.sh

Tool safety in pipeline files v0.23.0

The denylist, allowlist, and per-stream output ceiling are enforceable from a pipeline file as well as CLI flags. CLI values and graph attrs union; the denylist always wins.

Example, DOT form:

digraph G {
  // Only git and make commands are allowed in tool nodes.
  graph [tool_commands_allow="git *,make *"];
  Setup [handler="tool", tool_command="git init"];
  Build [handler="tool", tool_command="make build"];
  Setup -> Build;
}

As of dippin-lang v0.23.0+ (tracker ships v0.45.0), both attributes are exposed via a defaults: block in a .dip file (defaults: tool_commands_allow: "git *,make *"). The DOT form above and the library API (graph.Attrs["tool_commands_allow"]) remain equivalent ways to set them.

Name resolution

When you run tracker build_product (bare name, no path, no extension), the resolver checks in this order:

1. Explicit file path

   If the name contains / or ends in .dip/.dot/.dipx, treat as a filesystem path. No further resolution.

2. Local .dip file

   Check if build_product.dip exists in the current directory. Local files always win.

3. Bare file

   Check if build_product exists as a file in the current directory.

4. Embedded workflow

   Look up build_product in the built-in workflow catalog. If found, load from go:embed.

5. Error

   Print "unknown pipeline" with a list of available built-in workflows.

This applies uniformly to tracker run, tracker validate, and tracker simulate.

Environment variables

Provider keys

Keys are loaded from three sources in order: shell environment (highest priority), ~/.config/tracker/.env (XDG config), then .env in the working directory. Shell env vars are never overwritten.

Tracker runtime knobs

Autopilot mode

Run pipelines fully autonomous. Human gates are answered by an LLM judge with a configurable decision-making persona.

# Balanced judgment (default persona)
tracker --autopilot mid build_product

# Move fast, approve everything reasonable
tracker --autopilot lax build_product

# High quality bar — pushes back on gaps
tracker --autopilot hard build_product

# Approves but writes detailed feedback
tracker --autopilot mentor build_product

# Deterministic auto-approve — no LLM, for CI
tracker --auto-approve build_product

Personas

How It Works

1. Gate Reached

   Pipeline hits a human gate (ApprovePlan, EscalateMilestone, etc.)

2. LLM Consulted

   The autopilot sends the gate's prompt, context, and available options to the LLM with the persona's system prompt.

3. Structured Response

   LLM returns {"choice": "approve", "reasoning": "..."}. Choice is matched against edge labels.

4. Fallback on Error

   If the LLM fails or returns an unmatchable choice, the default edge is taken with a warning.

Agent backends

Three backends, one pipeline. Native is the default and works with every provider. Claude Code gives agents file editing, terminal access, and MCP tool servers (subscription auth, no API key needed). ACP bridges tracker to third-party coding agents like claude-agent-acp, codex-acp, and gemini --acp via JSON-RPC over stdio.

Side-by-Side Comparison

When to Use Which

Usage

# Global: every agent node uses Claude Code
tracker --backend claude-code build_product

# The killer combo: autonomous + Claude Code
tracker --backend claude-code --autopilot mid build_product

# Native is the default — no flag needed
tracker build_product

Per-Node Selection in .dip

Mix backends within a single pipeline. Use Claude Code for implementation, native for everything else. Per-node backend: attrs always override the global --backend flag.

agent Implement
  label: "Build the feature"
  model: claude-sonnet-4-6
  backend: claude-code
  prompt: |
    Implement milestone ${ctx.current_milestone} following SPEC.md.

agent Review
  label: "Review the implementation"
  model: gpt-5.4
  provider: openai
  # No backend attr — uses native (default)
  prompt: |
    Review the implementation for correctness and style.

The acp backend (v0.16.0+) spawns ACP-compatible coding agents as subprocesses via JSON-RPC over stdio (claude-agent-acp, codex-acp, gemini --acp). Override the chosen binary per-node via the acp_agent node attribute.

tracker-swebench companion binary v0.18.0+

Evaluates tracker's agent against the SWE-bench dataset. Orchestrates per-instance Docker containers, a dataset JSONL parser, a resumable results writer, and an in-container agent-runner that captures changes via git diff.

# Analyze a completed run, pretty-printed
tracker-swebench analyze ./swebench-results/

# Structured JSON for downstream tooling
tracker-swebench analyze ./swebench-results/ --json > report.json

# Evaluate predictions against a specific ID file
tracker-swebench analyze ./swebench-results/ --predictions preds.jsonl

Troubleshooting

Diagnose intelligence

tracker diagnose doesn't just dump errors — it analyzes failure patterns and generates actionable suggestions.

Deterministic Failure Detection

When a tool node fails multiple retries with identical errors, diagnose recognizes it as a deterministic bug in the command — not a transient issue that retrying might fix. This saves users from wading through 5 identical stack traces to realize the command itself is wrong.

  ✗ T1Init
    Handler:  tool
    Duration: 3.2s
    Attempts: 5 failures (all identical — deterministic)
    Output:
      The workspace name "." is invalid.
      Workspace names must start with a letter.

─── Suggestions ───────────────────────────────────────────
  → T1Init: Failed 5 times with identical errors — this is a
    deterministic bug in the command, not a transient failure.
    Retrying won't help. Fix the tool command in the .dip file
    and re-run.

All Detection Patterns

Quick reference

The commands you'll use most, at a glance.

# First time
tracker doctor                          # check API keys + tools
tracker setup                           # configure providers interactively

# Run pipelines
tracker build_product                   # built-in workflow, no file needed
tracker my_pipeline.dip                 # local file
tracker --autopilot mid build_product   # fully autonomous
tracker --backend claude-code my.dip    # agents use claude CLI

# Full YOLO — Claude Code agents, autopilot gates, TUI dashboard
tracker --backend claude-code --autopilot lax build_product

# After a run
tracker diagnose                        # analyze most recent failure
tracker audit <runID>                   # full audit trail
tracker list                            # recent runs

# Manage pipelines
tracker workflows                       # list built-in workflows
tracker init build_product              # copy to cwd for editing
tracker validate my.dip                 # lint + structure check
tracker simulate my.dip                 # dry-run all paths

# Maintenance
tracker update                          # self-update to latest release
tracker version                         # version + configured providers