Trekoon

AI-first issue tracking for humans and agents.

Trekoon is a local-first CLI for planning and execution inside a repository. It keeps work in a shared epic → task → subtask graph so humans and agents can work against the same state, from the terminal, with deterministic machine output when automation needs it.

What it is for

• Fast issue tracking for day-to-day terminal use
• One repo-scoped task graph that works across branches and worktrees
• Stable machine-readable output for AI workflows (--toon, --json)
• Minimal command surface with strong planning and execution primitives

Why it exists

Trekoon exists to make task tracking cheap enough to use while coding, and structured enough that agents can read, update, and complete work without guessing.

Install

Recommended (global install with Bun):

bun add -g trekoon

Alternative (npm global install — Bun must still be installed as the runtime):

npm i -g trekoon

Verify the install:

trekoon --help
trekoon quickstart

Commands

These are the commands most people need to recognize quickly:

Goal	Commands
Initialize a repo	trekoon init
Install/open/update the local board	trekoon board open, trekoon board update
Learn the CLI	trekoon help [command], trekoon quickstart
Plan work	trekoon epic ..., trekoon task ..., trekoon subtask ..., trekoon dep ...
Start an execution session	trekoon session
Keep worktrees in sync	trekoon sync ...
Install or refresh the AI skill	trekoon skills install, trekoon skills update
Maintenance	trekoon events prune ..., trekoon migrate ..., trekoon wipe --yes

Machine output modes:

• --toon for true TOON-encoded payloads
• --json for JSON output
• --compat <mode> for explicit compatibility behavior
• --help and --version at the root or command level

For the full command surface, flags, filters, and bulk update rules, read the command reference.

Local board workflow

Trekoon ships a no-extra-install local board for browsing and updating work in a browser.

• trekoon init creates the shared .trekoon storage, database, and board runtime under .trekoon/board
• trekoon board open ensures those bundled board assets are installed, starts a token-gated loopback server on 127.0.0.1, and launches the browser
• trekoon board update refreshes the board runtime assets only; it does not start the server or open a browser

Keep the operator path simple:

trekoon board open

Use trekoon board update only when you want to refresh the copied runtime assets without opening a session.

The browser flow is local-only by design:

• Trekoon copies the board shell and app files into repo-shared storage, so the board still starts with one CLI command and no separate frontend build step
• the board server binds only to 127.0.0.1
• every board open session uses a per-session token in the URL/API requests
• command output always includes a manual fallback URL if the browser launch fails

Current runtime expectations:

• the local runtime is served from .trekoon/board
• all assets are self-hosted: the board ships its own CSS, fonts (Inter, Material Symbols), and vanilla JS with no framework or CDN dependencies
• the board works fully offline once trekoon board open copies the runtime assets into .trekoon/board

Current board behavior to expect:

• the topbar is a compact single-row navbar showing the Trekoon brand, Epics and Board navigation, search, theme toggle, and a workspace info popover; selecting an epic adds the active epic context to the topbar
• the board toggles between an epics overview and a task workspace view; task detail opens as a modal overlay; responsive breakpoints adjust kanban column counts and component spacing
• the page scrolls naturally as a single SPA surface; modal overlays (task detail, subtask editor) lock body scroll while open
• overview cards are the primary entry point into an epic; clicking a card opens that epic's board workspace
• task cards show truncated descriptions; clicking anywhere on a card opens the task detail modal with the full description
• search is debounced and filters client-side across titles, descriptions, statuses, and subtask content

For the full lifecycle and examples, read Quickstart and Command reference.

AI skill

Trekoon ships with a bundled trekoon skill for AI agents. It teaches the agent to:

• use --toon by default
• prefer the smallest sufficient read
• use transactional bulk planning commands when possible
• append progress and blocker notes instead of rewriting full descriptions
• preview scoped replace before --apply
• treat .trekoon as shared repo-scoped operational state

Read AI agents and the Trekoon skill for installation, editor linking, recommended skill combinations, and example prompts.

Read next

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

Implementation principles

• Minimal, composable modules
• Strict validation at command boundaries
• Stable automation envelopes for JSON and TOON modes
• No unnecessary feature sprawl