oakoss 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.
| Command | Valid flags |
|---|---|
epic create |
-t -d -p -s |
epic list |
--status |
epic update |
-t -d -p -s |
epic show/complete/delete |
(no flags, just ID) |
task create |
-t -d -p -s -e --tags |
task list |
--status --epic |
task update |
-t -d -p -s -e --tags --no-epic |
task show/delete |
(no flags, just ID) |
subtask create |
-t -d -p -s |
subtask update |
-t -d -p -s |
subtask list/delete |
(no flags, just ID) |
comment add |
-a -c (both required) |
comment update |
-c |
comment list/delete |
(no flags, just ID) |
dep add/remove |
(no flags, two IDs) |
dep list |
(no flags, just ID) |
search |
--type --status --limit --page --rebuild-index |
history |
--entity --type --action --since --until --limit --page |
list |
--type --status --priority --since --until --sort --limit --page |
ready |
(no flags) |
wipe |
-y |
Flags that do NOT exist (agents commonly hallucinate these):
--offset— use--pageand--limitinstead--assignee— trekker has no assignee field--label— use--tagson task create/update instead--verbose/--json/--quiet— use--toonfor compact output, default is verbose--filter— use--status,--type,--priorityas separate flags--sortontask list— only available ontrekker list--all— not a flag on any command--force/-f— onlywipeaccepts-y--name/-n— use-t/--titleinstead
When unsure about flags, run --help on any command:
trekker --help
trekker task --help
trekker task create --help
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| Creating task without searching first | Always trekker search "keyword" before creating to avoid duplicates |
| Completing task without summary comment | Add Summary: comment with what was done and which files changed |
Not using --toon flag |
Always use --toon to reduce token usage in agent contexts |
Forgetting to set in_progress before working |
Set status before starting so other agents know the task is claimed |
Using epic delete instead of epic complete |
epic delete silently orphans tasks; use epic complete to archive them |
| Dependency direction reversed | dep add TREK-2 TREK-1 means TREK-2 depends on TREK-1 (TREK-1 blocks TREK-2) |
| Not adding checkpoint comments before context reset | Add Checkpoint: comment with done items, next steps, and affected files |
| Coding before planning | Create epic and break into tasks with dependencies before writing code |
| Vague task descriptions | Include implementation steps, files to modify, and acceptance criteria |
| Searching without type filter | Use --type task or --status in_progress to narrow results |
Empty search query trekker search "" |
FTS5 rejects empty strings; always provide a search term |
Using wont_fix when task is just deferred |
wont_fix = will never do; use archived for deferred or superseded work |
comment add missing -a or -c |
Both -a (author) and -c (content) are required |
Running trekker init twice |
Not idempotent; errors if .trekker/ already exists |
Forgetting to gitignore .trekker/ |
Add .trekker/ to .gitignore after init unless sharing task state |
Delegation
- Task discovery and prioritization: Use
Exploreagent to scan codebase and identify work - Multi-task execution: Use
Taskagent for parallel subtask completion
References
- Agent workflow and session management
- Commands and CLI usage