Trekker

Trekker

Overview

Trekker is a CLI-based issue tracker designed for AI coding agents. It stores data locally in SQLite (.trekker/trekker.db) and supports epics, tasks, subtasks, dependencies, comments, full-text search, and an audit history log. Use --toon on any command for token-efficient output.

When to use: Agent work session tracking, local task management, kanban-style workflows, dependency-aware task ordering, checkpoint comments for context persistence across sessions.

When NOT to use: Team-wide project management (use GitHub Issues/Linear), real-time collaboration, remote-first workflows, CI/CD-integrated issue tracking.

Essential Commands

trekker init
trekker --toon ready
trekker --toon task list --status in_progress
trekker --toon task list --status todo
trekker --toon task list --epic EPIC-1
trekker --toon task show TREK-1
trekker --toon epic list
trekker --toon epic show EPIC-1
trekker --toon comment list TREK-1
trekker --toon search "query" --type task
trekker --toon list --status in_progress
trekker --toon history --entity TREK-1
trekker epic create -t "Title" -d "description" -p 2
trekker task create -t "Title" -d "description" -e EPIC-1 -p 2 --tags "a,b"
trekker subtask create TREK-1 -t "Title" -d "description" -p 2
trekker task update TREK-1 -s in_progress
trekker task update TREK-1 -s completed
trekker epic complete EPIC-1
trekker dep add TREK-2 TREK-1
trekker comment add TREK-1 -a "agent" -c "Summary: what was done and which files changed"

Statuses — Tasks/Subtasks: todo, in_progress, completed, wont_fix, archived | Epics: todo, in_progress, completed, archived

Priority — 0 critical, 1 high, 2 medium (default), 3 low, 4 backlog, 5 someday

Valid Flags by Command

Only use flags listed here. Do NOT guess or invent flags.

Flags that do NOT exist (agents commonly hallucinate these):

• --offset — use --page and --limit instead
• --assignee — trekker has no assignee field
• --label — use --tags on task create/update instead
• --verbose / --json / --quiet — use --toon for compact output, default is verbose
• --filter — use --status, --type, --priority as separate flags
• --sort on task list — only available on trekker list
• --all — not a flag on any command
• --force / -f — only wipe accepts -y
• --name / -n — use -t / --title instead

When unsure about flags, run --help on any command:

trekker --help
trekker task --help
trekker task create --help

Common Mistakes

Delegation

• Task discovery and prioritization: Use Explore agent to scan codebase and identify work
• Multi-task execution: Use Task agent for parallel subtask completion

References

• Agent workflow and session management
• Commands and CLI usage

Agent Workflow

Session Start

Check for in-progress work before picking new tasks:

trekker --toon task list --status in_progress

If a task is found, read its comments for context recovery:

trekker --toon comment list TREK-1
trekker --toon history --entity TREK-1

If no in-progress tasks, find unblocked work:

trekker --toon ready

Search Before Creating

Always search before creating a task to avoid duplicates:

trekker --toon search "auth middleware" --type task

If no match, create the task. Use single keywords for broader matches:

trekker --toon search "auth" --type task
trekker --toon search "middleware" --type task

Planning Before Coding

For multi-step work, create an epic and break it into tasks before writing code:

trekker epic create -t "Implement JWT Authentication" -d "Goal: Secure all API endpoints with JWT tokens.
Success: All /api/* routes require valid token.
Approach: Add auth middleware, login/logout endpoints, bcrypt password hashing.
Files: src/middleware/, src/routes/auth/, src/models/user.ts" -p 1

Break down into tasks with detailed descriptions and dependencies:

trekker task create -t "Create user model" -d "Define User schema with email and password hash" -e EPIC-1 -p 1
trekker task create -t "Add auth middleware" -d "Create JWT verification middleware.
Steps:
1. Create src/middleware/auth.ts
2. Verify token from Authorization header
3. Attach decoded user to request
4. Return 401 for invalid/missing tokens
Accept: All /api/* routes protected, tests pass" -e EPIC-1 -p 1 --tags "auth,middleware"
trekker task create -t "Add login endpoint" -d "POST /auth/login with bcrypt verification" -e EPIC-1 -p 1
trekker dep add TREK-3 TREK-1
trekker dep add TREK-2 TREK-1

Task descriptions should include implementation steps, files to modify, and acceptance criteria. Epic descriptions should include goal, success criteria, approach, and key files.

Then use trekker ready to work tasks in dependency order.

Working on a Task

Claim the task, then add analysis comments as you work:

trekker task update TREK-1 -s in_progress
trekker comment add TREK-1 -a "agent" -c "Analysis: found root cause in src/auth.ts line 42"

Comment Prefixes

Use structured prefixes for consistent, parseable comments:

trekker comment add TREK-1 -a "agent" -c "Analysis: the rate limiter reads user tier from req.user, so auth middleware must run first"
trekker comment add TREK-1 -a "agent" -c "Progress: auth middleware done, starting tests"
trekker comment add TREK-1 -a "agent" -c "Blocked: waiting on TREK-4 (database migration) before integration tests"

Completing a Task

Always add a Summary: comment before marking complete:

trekker comment add TREK-1 -a "agent" -c "Summary: implemented JWT validation in src/middleware/auth.ts, added tests in tests/auth.test.ts"
trekker task update TREK-1 -s completed

Check if all epic tasks are done:

trekker --toon epic show EPIC-1

If all tasks complete, close the epic:

trekker epic complete EPIC-1

Checkpoint Comments

Before a context reset or session end, persist your progress:

trekker comment add TREK-1 -a "agent" -c "Checkpoint: completed auth middleware and unit tests. Next: integration tests for /api/login endpoint. Files: src/middleware/auth.ts, tests/auth.test.ts"

Include in every checkpoint:

• What was completed
• What comes next
• Which files were touched or need changes

Status Guide

Multi-Agent Handoff

When handing work to another agent, leave a comment with full context:

trekker comment add TREK-1 -a "agent-1" -c "Handoff: auth middleware done and tested. Remaining: rate limiting (see TREK-3), CORS config needs update in src/server.ts. Blocked by: TREK-4 (database migration)."

Commands

Initialization

trekker init

Creates .trekker/trekker.db in the current directory.

trekker wipe -y

Destroys all data. Use -y to skip confirmation.

Epics

trekker epic create -t "Title" [-d "description"] [-p 0-5] [-s <status>]
trekker epic list [--status <status>]
trekker epic show EPIC-1
trekker epic update EPIC-1 [-t "Title"] [-d "desc"] [-p 0-5] [-s <status>]
trekker epic complete EPIC-1
trekker epic delete EPIC-1

epic complete sets the epic to completed and archives all child tasks and subtasks.

Epic statuses: todo, in_progress, completed, archived

Common usage:

trekker epic create -t "Implement user auth" -d "JWT-based auth for all API endpoints" -p 1
trekker --toon epic list
trekker --toon epic list --status in_progress
trekker --toon epic show EPIC-1
trekker epic update EPIC-1 -s in_progress
trekker epic update EPIC-1 -d "Updated scope: OAuth2 + JWT for API endpoints"
trekker epic complete EPIC-1

Tasks

trekker task create -t "Title" [-d "desc"] [-p 0-5] [-s <status>] [-e EPIC-1] [--tags "a,b"]
trekker task list [--status <status>] [--epic EPIC-1]
trekker task show TREK-1
trekker task update TREK-1 [-t "Title"] [-d "desc"] [-p 0-5] [-s <status>] [--tags "a,b"] [-e EPIC-1] [--no-epic]
trekker task delete TREK-1

Task statuses: todo, in_progress, completed, wont_fix, archived

Use --no-epic to unlink a task from its epic.

Common usage:

trekker task create -t "Add login endpoint" -d "POST /auth/login with bcrypt" -e EPIC-1 -p 1 --tags "auth,api"
trekker --toon task list
trekker --toon task list --status todo
trekker --toon task list --status in_progress
trekker --toon task list --epic EPIC-1
trekker --toon task show TREK-1
trekker task update TREK-1 -s in_progress
trekker task update TREK-1 -s completed
trekker task update TREK-1 -p 0 --tags "auth,api,urgent"
trekker task update TREK-1 -d "Updated: also handle refresh tokens"
trekker task update TREK-1 -e EPIC-2
trekker task update TREK-1 --no-epic
trekker task update TREK-1 -s wont_fix
trekker task update TREK-1 -s archived

Subtasks

trekker subtask create TREK-1 -t "Title" [-d "desc"] [-p 0-5] [-s <status>]
trekker subtask list TREK-1
trekker subtask update TREK-2 [-t "Title"] [-d "desc"] [-p 0-5] [-s <status>]
trekker subtask delete TREK-2

Subtasks share the same status values and ID namespace (TREK-n) as tasks.

Common usage:

trekker subtask create TREK-1 -t "Write unit tests" -d "Cover login and logout flows" -p 2
trekker subtask create TREK-1 -t "Add input validation" -p 1
trekker --toon subtask list TREK-1
trekker subtask update TREK-3 -s in_progress
trekker subtask update TREK-3 -s completed

Comments

Comments serve as external memory for agents across sessions:

trekker comment add TREK-1 -a "agent" -c "Analysis: found the root cause in auth.ts"
trekker comment list TREK-1
trekker comment update CMT-1 -c "Updated analysis"
trekker comment delete CMT-1

The -a flag sets the author name. Use it to identify which agent or user wrote the comment.

Common usage:

trekker comment add TREK-1 -a "agent" -c "Analysis: login fails because token expiry is not checked"
trekker comment add TREK-1 -a "agent" -c "Progress: added token validation, working on refresh flow"
trekker comment add TREK-1 -a "agent" -c "Blocked: waiting on TREK-2 (user model) before integration tests"
trekker comment add TREK-1 -a "agent" -c "Summary: implemented login endpoint in src/routes/auth.ts, tests in tests/auth.test.ts"
trekker comment add TREK-1 -a "agent" -c "Checkpoint: done login/logout. Next: refresh tokens. Files: src/routes/auth.ts"
trekker comment add TREK-1 -a "agent" -c "Handoff: auth middleware complete. Remaining: rate limiting (TREK-5)"
trekker --toon comment list TREK-1

Dependencies

trekker dep add TREK-2 TREK-1
trekker dep remove TREK-2 TREK-1
trekker dep list TREK-1

dep add TREK-2 TREK-1 means "TREK-2 depends on TREK-1" — TREK-1 must complete before TREK-2 can start.

Common usage:

trekker dep add TREK-3 TREK-1
trekker dep add TREK-3 TREK-2
trekker --toon dep list TREK-3
trekker dep remove TREK-3 TREK-2

Search

Full-text search across all entity types using FTS5:

trekker search "auth" [--type epic,task,subtask,comment] [--status <status>] [--limit 20] [--page 1]

Supports FTS5 query syntax for advanced matching.

Use --rebuild-index to rebuild the search index if results seem stale.

Common usage:

trekker --toon search "auth"
trekker --toon search "auth" --type task
trekker --toon search "auth" --type task --status todo
trekker --toon search "login" --type task,subtask
trekker --toon search "middleware" --type comment
trekker --toon search "auth" --limit 10 --page 1
trekker search --rebuild-index "auth"

History

Audit log of all creates, updates, and deletes:

trekker history [--entity TREK-1] [--type task] [--action create,update,delete] [--since 2025-01-01] [--until 2025-12-31] [--limit 50] [--page 1]

Common usage:

trekker --toon history
trekker --toon history --entity TREK-1
trekker --toon history --entity EPIC-1
trekker --toon history --type task
trekker --toon history --type task --action update
trekker --toon history --action create --since 2025-01-15
trekker --toon history --type comment --entity TREK-1
trekker --toon history --limit 20 --page 1

Unified List

View epics, tasks, and subtasks in a single output:

trekker list [--type epic,task,subtask] [--status <statuses>] [--priority 0,1] [--since <date>] [--until <date>] [--sort priority:asc,created:desc] [--limit 50] [--page 1]

Common usage:

trekker --toon list
trekker --toon list --status in_progress
trekker --toon list --status todo,in_progress
trekker --toon list --type task --status todo
trekker --toon list --type epic
trekker --toon list --priority 0,1
trekker --toon list --type task --priority 0 --status todo
trekker --toon list --sort priority:asc
trekker --toon list --sort created:desc --limit 10
trekker --toon list --since 2025-01-01 --until 2025-02-01
trekker --toon list --type task,subtask --status completed

Ready Tasks

Show unblocked tasks with todo status, ready to pick up:

trekker ready

Equivalent to filtering for tasks that have no incomplete dependencies and are in todo status.

Common usage:

trekker --toon ready

Global Options

`--toon` — Add immediately after trekker for compact, token-efficient output suitable for LLM contexts:

trekker --toon task list --status in_progress
trekker --toon epic show EPIC-1
trekker --toon search "auth"
trekker --toon list --status todo
trekker --toon history --entity TREK-1
trekker --toon comment list TREK-1
trekker --toon ready

Pagination — Commands that return lists (list, search, history) support --limit and --page. There is no --offset flag.

trekker list --limit 20 --page 1
trekker list --limit 20 --page 2
trekker search "auth" --limit 10 --page 3
trekker history --limit 20 --page 2