Trekoon

Task tracking built for AI agents. You say what you want. Your agent plans it, tracks it and builds it. Nothing gets lost. This framework guides agents reliably creating the plan AND executing it.

Why you need this

AI agents are great at writing code and bad at remembering the plan. Long chats drift. Context runs out. Half-finished work disappears.

Trekoon fixes:

• The plan lives in your repo, not in the chat. Close the chat, come back tomorrow, nothing is lost.
• Agents always know what to do next. Every finished task tells the agent exactly which task is ready now.
• Many agents can work at once without stepping on each other. Each one claims its own task.
• You can watch everything live in a simple board in your browser.
• Zero setup pain. One small database file inside your repo. No server. No account. No cloud.

Other trackers are built for humans clicking around a website. Trekoon is built for agents: every command gives clean, structured output an agent can read cheaply, with no guessing.

Install (under a minute)

bun add -g trekoon

Then, inside your project:

trekoon init            # creates the .trekoon/ folder
trekoon skills install  # teaches your agent how to use it

Done. The skill part matters: it is the instruction set that makes your agent plan and execute the right way.

How to use it

Main commands:

/trekoon plan <what you want built>
/trekoon <epic-id> execute

1. Plan. The agent breaks your idea, from current conversation context, into tasks with clear order: what depends on what, which files to touch, how to verify each step.
2. Execute. The agent works through the tasks until everything is done. Big independent chunks go to parallel sub-agents automatically.

The best way to proceed is to discuss an active idea or problem with the agent. As soon as the agent suggests a concept you like, you can ask it to create a Trekoon plan based on your current discussion and any extra steps you want to include in the process. For instance, you could request a code-review after implementation that would be a part of the plan.

Not sure what you want yet? Start with brainstorm first:

/trekoon brainstorm: <rough idea>

The agent explores options with you and in the end creates a plan that you can exceute in a new session.

Want a second pair of eyes on the code?

/trekoon code-review

The agent reviews the changes, lists problems by severity and fixes them only when you ask. You can always specify what you want to review or how many subagents to use.

If there are many findings, it would be best idea to create a Trekoon plan and later execute it in a new session for best results.

Watch it work

trekoon board open

Opens a live board of latest epic in your browser: what is in progress, what is blocked, what is done. Updates by itself while agents work. Local only, protected with a token.

The commands agents use

You rarely type these yourself, but this is what happens under the hood:

| Step | Command | | --- | --- | | Get oriented | trekoon --toon session --epic <id> | | See the task order | trekoon --toon epic waves <id> | | Take a task | trekoon --toon task claim <id> --owner <name> | | Read the full task | trekoon --toon task show <id> --all | | Hand a task to a sub-agent | trekoon --toon task brief <id> --owner <name> | | Log progress | trekoon --toon task update <id> --append "note" | | Finish a task | trekoon --toon task done <id> |

task done answers with what just became ready, so the agent immediately knows the next move. No polling, no guessing.

Full list: docs/commands.md.

Good to know

• All data sits in one file: .trekoon/trekoon.db (SQLite). Keep it out of git; trekoon init sets that up.
• Statuses follow strict rules (todo → in_progress → done), so agents cannot fake progress. Details in docs/commands.md.
• Working in several git worktrees? trekoon sync pull --from main brings changes over safely.
• Want a backup before anything risky? trekoon migrate backup.
• Machine output is lean by default. Add --verbose if you need envelope metadata, and --json or --toon to pick the format.

Docs

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