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 (--json, --toon)
so agents can read and update state without parsing human text. Non-TTY output stays JSON unless --toon is explicit; agents should opt into --toon. 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    # print the quickstart guide

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 waves, using progress/suggest only for focused status checks

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> for diagnostics, sync status, and orientation
2. Runs epic waves <id> to shape lanes from dependencies, owners, ready flags,
   and graph warnings
3. Marks the epic in_progress
4. Spawns sub-agents for independent lanes (auth tasks go to one agent, billing
   tasks to another)
5. Each sub-agent claims a task, reads task show <id> --all, 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:

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.

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 reviewing active agent work
and correcting tracker state. Agents should keep using Trekoon CLI commands and
workflow prompts for planning and execution. 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 grouped active
epic sections, per-epic active task lanes, recently done history, quiet UUID
copy actions, per-item status correction, read-first task details, and
contextual search that includes completed matches. Bulk workflow changes remain
CLI-first. 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

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