Trekoon

AI-first task tracking that lives in your repo. You describe what to build, your agent plans it as a dependency graph, then executes it task by task.

Trekoon stores work as epics > tasks > subtasks with dependency edges in a local SQLite database. Every command has structured output (--toon, --json) so agents can read and update state without parsing human text. No server, no accounts. The database lives in .trekoon/ inside your repo.

Install

bun add -g trekoon

trekoon init          # set up .trekoon/ in your repo
trekoon quickstart    # walkthrough of the basics

The three workflows

Trekoon gives agents three modes: brainstorm, plan, and execute. Brainstorming is design-only. Planning writes the Trekoon graph. Execution works through that graph.

For a human driving the workflow, the recommended path is:

/trekoon brainstorm: <topic>   # optional, design only
/trekoon plan <goal>
/trekoon <epic-id>
/trekoon <epic-id> execute

• Use brainstorm: when the shape of the work is still fuzzy. The agent should explore options and ask for acceptance before creating Trekoon items.
• Use plan after you already have enough context from discussion, brainstorming, or research.
• Use trekoon <epic-id> to inspect the created epic, review the next ready work, and decide whether anything needs refinement.
• Use execute when you want the agent to keep working through the epic until it is done, all remaining work is blocked, or it needs your input.

Brainstorm

Use brainstorm mode before planning when the architecture, UX, scope, or tradeoff is not clear yet.

/trekoon brainstorm: <topic>

In brainstorming mode, the agent investigates the repo and docs, explores a few approaches, recommends the simplest viable design, and asks focused questions. It should not create or update epics, tasks, subtasks, dependencies, or status until you accept the design. After acceptance, it can switch to plan and turn the accepted design into a Trekoon graph.

Plan

Tell the agent what you want to build or what problem you want fixed. If you already did brainstorming or research, Trekoon should use that context instead of starting from zero. Planning decomposes the work into an epic with tasks, subtasks, and dependency edges, then writes the whole graph into Trekoon.

trekoon plan <description>

What the agent does during planning:

1. Reuses the current conversation, prior research, and existing constraints
2. Asks clarifying questions if requirements are ambiguous
3. Creates an epic with outcome-oriented title and scoped description
4. Breaks it into tasks grouped by subsystem (auth, billing, UI, etc.)
5. Adds subtasks with concrete file paths, acceptance criteria, and test commands
6. Wires dependency edges so the execution order is explicit
7. Assigns lane owners when multiple agents will work in parallel
8. Validates the graph with epic progress and suggest before handing off

For humans: use plan when you want Trekoon to turn a feature request or bug investigation into a tracked, execution-ready backlog.

Each task description includes target files, read-first files, do-not-touch paths, and verification commands. Another agent (or a human) can pick up any task and execute it without re-reading the codebase to figure out what to do.

Execute

Point the agent at an epic and it works through the dependency graph automatically. It is recommended to do it with clean context window.

trekoon <id> execute

What the agent does during execution:

1. Runs session --epic <id> to get diagnostics, sync status, and the first ready task
2. Marks the epic in_progress
3. Groups ready tasks into lanes by subsystem to minimize redundant codebase exploration
4. Spawns sub-agents for parallel lanes (auth tasks go to one agent, billing tasks to another)
5. Each sub-agent claims a task, does the work, appends progress notes, and calls task done
6. task done returns which downstream tasks just became unblocked, so the orchestrator knows what to dispatch next
7. After all tasks complete: review agent or review skill for non-trivial changes, tests, manual verification, then marks the epic done

The orchestrator uses task done responses to drive the whole loop. No polling, no guessing. When a task finishes, Trekoon tells you exactly what's ready next.

For humans: use execute when the plan looks good and you want the agent to own the epic end to end. It should keep going until the epic is complete, all remaining work is blocked with recorded reasons, or it needs a product or technical decision from you.

Install the skill

The trekoon skill is what teaches agents the planning methodology, execution orchestration, status machine rules, and command reference. Without the skill, agents don't know how to use Trekoon properly.

trekoon skills install          # repo-local (.agents/skills/trekoon/)
trekoon skills install -g       # global (~/.agents/skills/trekoon)
trekoon skills install --link --editor codex    # editor link (.codex/skills/trekoon)
trekoon update                  # refresh all installed skills

The skill bundles reference documents that agents load on demand:

Agent needs to...	Skill reads	What it covers
Coordinate across harnesses	reference/harness-primitives.md	Universal subagent, question, local task display, review, and evidence-recording guidance
Brainstorm before planning	reference/brainstorming.md	Design-only exploration, tradeoffs, focused questions, and acceptance before Trekoon items are created
Plan a feature	reference/planning.md	Decomposition, writing standard, dependency modeling, validation
Execute an epic	reference/execution.md	Graph building, lane grouping, sub-agent dispatch, verification (universal)
Execute with Agent Teams	reference/execution-with-team.md	TeamCreate/SendMessage, parallel Claude Code instances in tmux

Invoke the skill

/trekoon                     → load the skill
/trekoon brainstorm: <topic> → explore design only; create no Trekoon items yet
/trekoon plan                → decompose into tasks/subtasks/deps
/trekoon <id>                → show status and next steps for an entity
/trekoon <id> execute        → start the execution loop
/trekoon <id> analyze        → run progress + suggest, report findings

Example prompts

Plan only:

/trekoon — plan this feature as one epic with tasks, subtasks, and dependencies

Execute only:

/trekoon <epic-id> execute

When you execute an epic, use subagents by default for any meaningful work that can run independently. Keep small or tightly coupled tasks in the parent agent. Use the main context for orchestration, dependency decisions, user communication, and final synthesis while Trekoon remains the durable source of truth.

If a harness has a higher-priority rule requiring explicit permission before subagents, surface that immediately instead of silently doing broad work yourself.

Plan and execute end to end:

/trekoon — plan this feature, create the backlog, then execute the tasks in
dependency order until the epic is complete

Agent Teams

For larger epics, use the current harness's native subagent mechanism for meaningful work that can run independently. Claude Code Agent Teams are one runtime-specific option: instead of sequential sub-agents, you get real parallel Claude Code instances coordinated through TeamCreate and SendMessage, each running in its own tmux pane.

Requires Claude Code env variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true.

The team lead orchestrator creates a team, populates a shared task list, spawns 3-5 teammates per lane, and coordinates via messages. Teammates claim tasks, report completions and blockers, and the lead dispatches new work as tasks get unblocked.

Status machine

Trekoon enforces valid transitions. You can't skip straight from todo to done.

From	Allowed targets
todo	in_progress, blocked
in_progress	done, blocked
blocked	in_progress, todo
done	in_progress

Exception: task done auto-transitions through in_progress, so agents can call it from any non-done status.

Storage and durability

Trekoon stores all state in .trekoon/trekoon.db (SQLite, WAL mode). The database file lives outside the git object store; never commit it. Open-time PRAGMAs are tuned for read+write throughput:

• journal_mode = WAL — required for concurrent readers + a single writer.
• synchronous = NORMAL — paired with WAL per the SQLite recommendation. On a hard kernel/OS crash, the last few unfsynced transactions may be lost, but the database file itself never corrupts. To restore the pre-tuning behaviour (synchronous = FULL), set TREKOON_SQLITE_DURABILITY=full before invoking any trekoon command.
• temp_store = MEMORY, mmap_size = 256 MiB, wal_autocheckpoint = 1000 — keep hot reads in-process and bound the WAL size under sustained writes.
• cache_size — defaults to 64 MiB per connection. Override with TREKOON_SQLITE_CACHE_MIB=<N> (non-negative integer). In daemon mode (trekoon serve) up to 16 connections may be cached simultaneously, so peak page-cache usage approaches CACHED_DATABASES_CAPACITY × cache_size (e.g. 16 × 64 MiB = 1 GiB at the default). Lower TREKOON_SQLITE_CACHE_MIB when memory is constrained (e.g. TREKOON_SQLITE_CACHE_MIB=16 → 256 MiB total for a 16-handle daemon).

These pragmas apply per open connection. Recovery path on suspected corruption: trekoon migrate backup, then copy a known-good backup over .trekoon/trekoon.db.

Local board

Trekoon includes a browser-based board for humans who like having a visual overview. No build step, no framework dependencies, works offline.

trekoon board open      # starts a local server, opens browser

Board code (HTML, JS, CSS, fonts) comes from the running Trekoon install. Board data comes from the repo where trekoon board open is invoked. Updating Trekoon updates the board bundle; no per-repo asset copy is needed. Repos with an old ignored .trekoon/board directory keep those files on disk, but Trekoon no longer reads or refreshes them.

Binds to 127.0.0.1 only with a per-session token. Gives you an epics overview, kanban workspace per epic, task detail modals, and search. The board client subscribes to /api/snapshot/stream (SSE), so mutations from another shell, worktree, or browser tab show up live without a manual refresh.

Commands

What you want to do	How
Set up a repo	trekoon init
Open the local board	trekoon board open
Plan work	trekoon --toon epic create ..., trekoon --toon epic expand ...
Create tasks in bulk	trekoon task create-many ...
Add dependencies	trekoon dep add-many ...
Start an agent session	trekoon session --epic <id>
Resolve any epic/task/subtask id	trekoon session --item <id>
Get next-action suggestions	trekoon suggest --epic <id>
Check epic progress	trekoon epic progress <id>
Export epic to Markdown	trekoon epic export <id>
Claim a task atomically	trekoon task claim <id> --owner <owner>
Claim a subtask atomically	trekoon subtask claim <id> --owner <owner>
Mark a task done	trekoon task done <id>
Sync across worktrees	trekoon sync pull --from main
Back up the DB before migrations	trekoon migrate backup
Reveal full board token	trekoon board open --reveal-token
Run experimental daemon	trekoon serve (experimental)
Get help	trekoon [command] -h

Every command supports --toon, --json, --compact for structured output.

Trekoon accepts a few forgiving aliases (--desc for --description, and common dependency aliases such as --deps for --dep). Prefer canonical --description and --dep in docs, prompts, and scripts.

Full flag reference in docs/commands.md.

Docs

• Quickstart
• Command reference
• AI agents and the Trekoon skill
• Machine contracts
• Contributing
• Changelog