For AI Agents

track is built to be driven by AI coding assistants (Claude Code, Cursor, and others) as well as humans. This page summarizes the agent-friendly features. For the exhaustive guide, see docs/agent_guide.md in the repository.

JSON output

Every command supports machine-readable JSON via -o json (or --format json). Use it whenever a program — or an agent — needs to parse the result:

track -o json PROJ-123
track -o json i s "project: PROJ #Unresolved" --all

Context aggregation

track context returns everything an agent needs to reason about a tracker in a single call: projects, custom fields (with enum values), assignable users, query templates, workflow hints (valid state transitions), issue counts, and recently accessed issues.

track context                  # Aggregated context
track context --project PROJ   # Scope to one project
track -o json context          # JSON for parsing
track context --include-issues # Include unresolved issues

A local cache backs this for fast, low-API-cost lookups:

track cache refresh --if-stale 1h
track cache status

Capability audit

Run track doctor at session start when you need to know which backend operations are trustworthy. It audits the effective backend, or every configured backend with --all-backends, and reports per-check statuses in text or JSON.

track doctor -o json
track doctor --all-backends -o json
track doctor --all-backends --strict

config test is only a single connectivity probe. doctor checks practical capabilities such as issue search/read, comments, links, field schema, field admin, articles, and local write validation. It never mutates remote trackers; --write-check validates payloads against fetched schema only.

Batch operations

Operate on many issues in one command — ideal for agents applying a plan:

track i u PROJ-1,PROJ-2,PROJ-3 --field "Priority=Major"  # Batch update
track i start PROJ-1,PROJ-2,PROJ-3                        # Batch start
track i done PROJ-1,PROJ-2 --state Done                   # Batch complete
track i del PROJ-1,PROJ-2,PROJ-3                          # Batch delete

Batch inspect before acting

Use track issue inspect when an agent needs reliable context for many issues before making decisions. It is intended for backlog audits, phase summaries, parent/subtask verification, recent-comment review, and preflight checks before bulk updates.

# Capture specific issues with comments and links
track i ix PROJ-1,PROJ-2,PROJ-3 --include comments,links -o json

# Inspect a query-selected backlog slice
track i ix --query "project: PROJ #Unresolved" --all --include comments,links -o json

# Stream issue context generated by another tool
track i ix --ids - --include all --jsonl < ids.txt

Unlike a shell loop around track issue get --full, inspect returns one stable report with total, succeeded, failed, issues, and errors. Individual issue failures do not abort the run unless --strict is passed, so agents can report partial results without losing successful context. Requested include context is explicit via --include comments,links,subtasks,history,all; unsupported include capabilities are warnings, while real include fetch failures are per-issue errors.

Declarative apply

For larger changes, track apply runs a declarative plan describing the desired end state, rather than imperative commands. See the agent guide for the plan format and examples.

Avoiding shell-escaping issues

When content is complex (multi-line, special characters), read it from a file or stdin instead of inlining it:

track i new -p PROJ -s "Title" --body-file ./body.md   # "-" reads from stdin
track i cmt PROJ-123 --body-file ./comment.md

Agent skills

track ships installable agent skills that teach assistants how to use the CLI:

track init --skills           # Install skills only; no tracker config change
track init --skills --url ... # Combine with configuration initialization

The command installs the same track skill reference for these agents:

Agent	Installed path
Claude Code	~/.claude/skills/track/SKILL.md
GitHub Copilot	~/.copilot/skills/track/SKILL.md
Cursor	~/.cursor/skills/track/SKILL.md
Gemini CLI	~/.gemini/skills/track/SKILL.md

The installed skill is guidance only. It teaches agents the command surface, JSON mode, context/cache workflow, backend differences, and batch-operation patterns; credentials stay in .track.toml or environment variables.

Workflow hints

State transitions differ per backend. track context reports valid transitions as workflow hints so an agent can move an issue through its lifecycle correctly without hardcoding state names.