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 --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+, 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

Variables come from three sources with different trust, and each source may set only the names its trust allows (v0.78.0, env trust policy):

• Shell environment — may set anything; a shell value is never overwritten by a file.
• ~/.config/tracker/.env (XDG config; written by tracker setup) — provider *_API_KEYs, per-provider *_BASE_URLs, TRACKER_GATEWAY_URL/TRACKER_GATEWAY_KIND, TRACKER_OPENAI_AUTH, and the cost / UX knobs (TRACKER_ACP_CACHE_READ_RATIO, TRACKER_DEBUG, TRACKER_NO_NOTIFY, TRACKER_NO_UPDATE_CHECK, TRACKER_HERDR, TRACKER_CODEGEN_*, TRACKER_SPRINT_WRITER_*).
• .env in the working directory — provider *_API_KEYs only. Any committer, a prior unjailed agent, or a model-run command can write this file, so it cannot pick endpoints or flip switches. For a key both files set, the project file wins.

Every other name — TRACKER_PASS_ENV, TRACKER_PASS_API_KEYS, TRACKER_STRIP_ACP_KEYS, TRACKER_CLAUDE_BIN, TRACKER_FAIL_ON_OVERRIDE, TRACKER_AUDIT_DIR, XDG_STATE_HOME, HERDR_*, PATH, HTTPS_PROXY, SSL_CERT_FILE, LD_PRELOAD, and any name tracker does not read — is shell-only: a file that sets one is skipped for that key with a single stderr line naming the file, the key and where it belongs, and tracker doctor lists the attempt. A symlinked .env and a group/world-writable .env (config or project) are skipped whole. tracker version reads the config file only, never the current directory. The full registry is internal/envpolicy in the source tree.

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

# No flag and no API key: the starters use backend: auto (Claude Code if installed)
tracker explain --param question="what does this repo do?"

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. backend: auto picks your Claude subscription when claude is installed (outside the working directory and answering --version), otherwise a configured API key, once per run, and announces the choice; an explicit --backend wins over it, and a resume reuses the recorded choice. With every agent node on auto, claude-code or acp, no API key is needed to start. tool_access: read_only limits a node to reading: read / grep_search / glob on the native backend (secrets and paths outside the workdir refused), --tools Read,Glob,Grep with dontAsk on Claude Code; ACP refuses it.

agent Implement
  label: "Build the feature"
  model: claude-sonnet-5
  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.

Companion binaries

Two binaries ship alongside tracker but are not part of the product CLI — they verify and benchmark the engine. tracker-conformance pins engine behavior against version drift; tracker-swebench evaluates the agent against SWE-bench. For how these fit into tracker's verification story, see How we verify tracker.

tracker-conformance v0.47.0+

Emits a normalized, deterministic golden trace of an example workflow — event sequence, per-node SessionStats, aggregate UsageSummary, and terminal status/class — via a stub completer (no API keys, no wall-clock noise). The committed goldens are versioned in lockstep with the tracker tag, so a downstream port pins a version and diffs for any engine-behavior drift. This binary is a GoReleaser-published release asset for exactly that reason.

tracker-swebench 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 (Claude Code signed in: no API key needed)
tracker explain --param question="what does this repo do?"
tracker quickfix --param change="fix the README typo"
tracker setup                           # configure API keys interactively (no Claude Code)
tracker doctor                          # check setup: keys, claude, tools

# 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
tracker verify-tests . --race           # flag duplicate tests + race check

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