trekker

Task tracking for
AI agents

A CLI-based task manager that keeps AI coding agents on track. Tasks, epics, and dependencies—all in a local SQLite database.

GitHubnpmClaudeClaude Code

Why Trekker

AI coding agents work better when they can track their own progress. A simple CLI-based task manager keeps them on the right path across sessions.

I built this after using Beads for a while. Beads does the job, but its codebase has grown quickly without enough care for what is happening inside. A task tracker is a simple application. It should not need thousands of lines of code.

My concerns about the future and security of that project led me here. Trekker is my simplified alternative.

I built this with AI assistance, but I did it for myself. That means I put enough care into it to make it reliable for my own work.

Prerequisites

You need the Bun runtime. Trekker uses bun:sqlite for database operations. This makes every command respond instantly.

macOS/Linux

curl -fsSL https://bun.sh/install | bash

Windows

powershell -c "irm bun.sh/install.ps1 | iex"

Via npm

npm install -g bun

Installation

Using bun (recommended)

bun install -g @obsfx/trekker

Using npm

npm install -g @obsfx/trekker

Features

  • Tasks, epics, subtasks, and dependencies
  • Full-text search across all items
  • Filter by type, status, or priority
  • Kanban board via separate dashboard package
  • Stores everything in a local .trekker folder
  • TOON output format for AI token efficiency

Claude Code Plugin

Claude

Give Claude Code direct access to Trekker with 25 MCP tools, 13 slash commands, and an autonomous task agent.

Install

claude /plugin marketplace add obsfx/trekker-claude-code
claude /plugin install trekker

Key Features

  • Persistent task memory across sessions via SQLite
  • Search-first workflow to restore context
  • Smart hooks for session start and context preservation
  • Autonomous task agent for discovery and completion
  • Multi-instance safe with conflict handling

Slash Commands

/trekker:prime-Load workflow context
/trekker:create-Create task interactively
/trekker:list-List tasks with filters
/trekker:ready-Find unblocked tasks
/trekker:start-Begin working on a task
/trekker:done-Complete with summary
/trekker:blocked-Mark task as blocked
/trekker:task-agent-Run autonomous agent

Quick Start

Initialize your project

trekker init

Create an epic

trekker epic create -t "User Authentication" -d "JWT-based auth"

Add tasks to the epic

trekker task create -t "Create user model" -e EPIC-1
trekker task create -t "Build login endpoint" -e EPIC-1

Establish dependencies (TREK-2 depends on TREK-1)

trekker dep add TREK-2 TREK-1

Update task status

trekker task update TREK-1 -s in_progress
trekker task update TREK-1 -s completed

Commands

Project Management

trekker init
trekker wipe
trekker quickstart

Epics

trekker epic create -t "Epic title" [-d "description"] [-p 0-5]
trekker epic list [--status todo|in_progress|completed|archived]
trekker epic show EPIC-1
trekker epic update EPIC-1 -s in_progress
trekker epic complete EPIC-1
trekker epic delete EPIC-1

Tasks

trekker task create -t "Task title" [-d "desc"] [-p 0-5] [-e EPIC-1] [--tags "tag1,tag2"]
trekker task list [--status todo|in_progress|completed|wont_fix|archived] [--epic EPIC-1]
trekker task show TREK-1
trekker task update TREK-1 -s in_progress
trekker task delete TREK-1

Subtasks

trekker subtask create TREK-1 -t "Subtask title" [-d "desc"] [-p 0-5]
trekker subtask list TREK-1
trekker subtask update TREK-1-1 -s completed
trekker subtask delete TREK-1-1

Comments

trekker comment add TREK-1 -a "agent" -c "Progress note"
trekker comment list TREK-1
trekker comment update CMT-1 -c "Updated content"
trekker comment delete CMT-1

Dependencies

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

Search

Search across all tasks, epics, subtasks, and comments using FTS5.

trekker search "authentication"
trekker search "bug fix" --type task,subtask
trekker search "login" --type comment --status completed
trekker search "query" [--type types] [--status status] [--limit n] [--page n]

History

View an audit log of all changes.

trekker history
trekker history --entity TREK-1
trekker history --type task,epic --action create,update
trekker history --since 2024-01-01 --until 2024-12-31

Unified List View

trekker list
trekker list --type task,epic
trekker list --status todo,in_progress
trekker list --priority 0,1,2
trekker list --sort priority,created_at

Status & Priority

Priority Scale

PriorityLabel
0Critical
1High
2Medium (default)
3Low
4Backlog
5Someday

Status Values

Tasks: todo, in_progress, completed, wont_fix, archived

Epics: todo, in_progress, completed, archived

ID Formats

  • Epics:EPIC-1, EPIC-2, ...
  • Tasks:TREK-1, TREK-2, ...
  • Comments:CMT-1, CMT-2, ...

TOON Output Format

Use the --toon flag to get structured output that uses fewer tokens.

trekker --toon task list
trekker --toon task show TREK-1

Dashboard

A kanban board that reads from your .trekker database.

npm install -g @obsfx/trekker-dashboard
trekker-dashboard -p 3000
Trekker Dashboard - Kanban View

Trekker Dashboard - Kanban View

Data Storage

Trekker creates a .trekker folder in your project root. Add it to .gitignore if you do not want to track it.

AI Agent Workflow

  1. 1Install the Claude Code plugin
  2. 2Tell the agent to use Trekker in your prompt
  3. 3Point the agent to trekker quickstart for reference
  4. 4Open the dashboard to watch progress

Example prompt:

Use trekker to track your work. Run `trekker quickstart` if you need to learn how it works.