Takomo
A task tracker you host, that every AI agent, orchestrator, and human on a project talks to over HTTP — one source of truth for work, instead of a todo list trapped in a single checkout.
Power your agent
Install from the publisher. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
No packaged release in the registry yet. Follow the repository README.
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
A task tracker you host, that every AI agent, orchestrator, and human on a project talks to over HTTP — one source of truth for work, instead of a todo list trapped in a single checkout.
A hosted, single-source-of-truth task tracker for AI agent fleets — configurable enforced workflows, atomic claims/leases, epics & dependency graphs, with an MCP server, CLI, and web board.
Repo-embedded trackers keep a nice trail inside one repository, but parallel work across many orchestrators, machines, and checkouts needs one authority everyone can reach. Takomo is that authority: hierarchical tickets, a real per-project state machine, atomic claim/lease so exactly one worker owns a ticket, and an append-only event log — with errors written to teach an LLM what to do next.

There is no public Takomo instance — you run your own. It's a single Rust + SQLite binary; standing one up is a click or a container (below). Once it's running, the Claude Code plugin and the
takomoCLI point at your host.
Takomo is a server you run yourself. Pick one:
Option A — Deploy to Render (one click):
The render.yaml Blueprint provisions a web service with a persistent disk (SQLite durability), TLS, and a /healthz check, and gives you a https://<name>.onrender.com URL.
Option B — Docker (anywhere):
docker build -t takomo .
docker run -d --restart unless-stopped -p 8080:8080 -v takomo-data:/var/data --name takomo takomo
The image includes diagram rendering (Mermaid, PlantUML/Salt and D2): one container, one port and one data volume. See runtime sizing and permissions.
Put TLS in front of it — Takomo terminates plain HTTP and refuses non-loopback binds unless TAKOMO_ALLOW_PUBLIC_BIND=1.
Then mint the first admin token with shell access to the server (the root of trust) — render ssh on Render, docker exec --user takomo -it takomo sh locally:
takomo --db /var/data/takomo.db token create \
--actor human:me --scopes read,write,human,admin --projects '*'
It prints a tk_... token once. Everything below points at https://<your-host>/v1 with a token. Local builds, TLS, and off-box backups: docs/hosting.md.
Takomo hosts an MCP server inside the binary (streamable HTTP at /mcp), so any MCP-capable client connects directly — no local process to run.
Claude Code (two lines) — this repo doubles as the plugin marketplace:
/plugin marketplace add ChristianKohlberg/Takomo
/plugin install takomo
That installs the takomo skill (teaches the agent to use the store as its source of truth) plus the remote MCP server. Set your host + token before launching Claude Code — nothing is baked into the plugin:
export TAKOMO_MCP_URL="https://<your-host>/mcp" # the MCP endpoint — note /mcp, not /v1
export TAKOMO_TOKEN="tk_<your read/write token>"
/mcp, not/v1. The MCP server lives athttps://<your-host>/mcp, while the CLI'sTAKOMO_URLpoints at the REST basehttps://<your-host>/v1. The plugin's bundled MCP server reads${TAKOMO_MCP_URL}, so set that (distinct fromTAKOMO_URL) — otherwise the server has no host to reach and shows up as failed to connect. If you also use the CLI, export both.
Any other MCP client (Codex, Cursor, …) — point it at the endpoint with a bearer token, e.g. adding it to Claude Code by hand:
claude mcp add --transport http \
--header "Authorization: Bearer tk_<token>" \
takomo https://<your-host>/mcp
The default --scope local keeps this in ~/.claude.json. --scope project instead writes it
into .mcp.json at the repo root, bearer token included — fine to share with a team, but only
after checking that file is gitignored (Takomo's own is).
The agent then gets native takomo_new / ready / next / start / done / comment / link / dep / roadmap / … tools. See plugins/takomo/README.md and clients/mcp/README.md.
Hosted clients (claude.ai, ChatGPT, the Gemini app) can only be handed a URL — there is nowhere
to put a bearer token — so they connect over OAuth instead. Set TAKOMO_PUBLIC_URL to your public
origin and takomo runs the authorization server itself:
TAKOMO_PUBLIC_URL=https://<your-host> # no path, no trailing slash
Then add https://<your-host>/mcp as a custom connector and approve the consent screen by pasting a
takomo token. The client never receives that token: it gets a separate, expiring one derived from it,
narrowed to the scopes you leave checked — and never carrying admin. Revoking that derived token
ends exactly that connection; revoking the one you pasted ends every connection approved with it.
Full per-product wiring in docs/hosted-mcp-clients.md.
takomo is a self-contained bash + curl + python3 script — for humans, and for agents/harnesses without MCP. One line:
curl -fsSL https://raw.githubusercontent.com/ChristianKohlberg/Takomo/main/clients/cli/install.sh | sh
takomo help
The installer checks curl/python3 and puts takomo (and a short tk alias) on your PATH. Reference: clients/cli/README.md.
Onboard a repo — one command. From the root of any git repo, with an admin token:
export TAKOMO_URL="https://<your-host>/v1" # note the /v1
export TAKOMO_TOKEN="tk_<admin token>" # used only to provision
takomo init # or: takomo init myproject --workflow simple
takomo init creates the project (named after the repo), applies the simple workflow, mints a read,write token scoped to just that project, and writes .takomo/config (url + project, safe to commit) and .takomo/token (mode 600, auto-gitignored). After that takomo auto-loads .takomo/ by walking up from your cwd — no env setup inside the repo.
Work the queue:
takomo whoami # who am I: actor, scopes, projects
takomo new "Wire up the frobnicator" # create a ticket (warns about likely duplicates)
takomo ready # what's claimable right now
takomo roadmap # epic progress per epic, plus work under no epic
ID=$(takomo next | awk '{print $2}') # atomically claim the next ready ticket
takomo start "$ID" # -> in_progress (the lease fence is remembered for you)
takomo comment "$ID" "opened PR, waiting on CI"
takomo link "$ID" --pr https://github.com/org/repo/pull/42
takomo done "$ID" # -> done (claim auto-releases)
Every rejection teaches: an illegal move returns the allowed transitions and a remedy, and takomo prints them. Never retry a rejected call unchanged.
409 (current state, allowed transitions, remedy) written for an LLM.epic → task/bug/subtask trees, blocked_by edges (reverse + transitive views), labels, roadmaps, and free-form namespaced JSON metadata.?since=<seq> cursor plus an SSE stream — the audit trail and the wake feed in one./board, with scoped, expiring share links. Narrow it
to one epic or one ticket (subtasks included) and group cards by epic, so a big
project stays readable. An open ticket is in the URL
(/board?project=<p>#t=<id>), so a detail view can be shared.takomo ask / takomo_ask: a blocking question parks the ticket and releases the lease (the ticket resumes once all its open questions are answered), while an advisory question records a routed decision without changing state — for epic-level or strategic calls. Questions land on a dedicated email-style /inbox (folder rail, list, reading/answer pane) routed by expertise tag — or the board's quick Ask a human drawer, or the API. For an outside expert with no takomo token, mint a per-question answer link — a scoped, expiring, single-use URL that lets them answer just that one question. A human can also bounce a question back for more research before answering — a clear follow-up thread with the asking agent (takomo_reply), with the ticket parked until they finally answer. Optional email/Slack push (off unless configured). See docs/ask-a-human.md.takomo project style <p> "Two sentences max…" / takomo project language <p> German. Both are handed to the agent before it writes, on every work-loop call (style_hint / language_hint), so they reach every client instead of one checkout. Advisory, never enforced. Editable from the CLI or the admin-only Settings sheet on /board. See docs/ask-a-human.md.takomo promote TKM-1 production / takomo_promote. Free-form target (staging, production, published, delivered, …), so it fits any workflow, not just software; append-only history, latest badged on the board. See docs/promotions.md./bugs: every bug is an ordinary type: bug ticket with the same ID on the board, plus a triage disposition and severity reviewed independently of workflow. A button, takomo bug research, or takomo_bug_research explicitly sends Codex to research the codebase at a pinned Git revision through the local agent service — never on intake. See docs/bugs.md.takomo project archive <p>, or the button on /settings. A gate, not a delete: every write under the project is refused with a teaching 409 project.archived (tickets, claims, transitions, comments, questions, tags, schedules, behaviors and runs, and the project's own settings), its tickets leave the ready queue so no agent is offered work there, and its schedules and question deadlines stop firing. Reads are untouched — the board, the history and the export all still answer — and because nothing is moved or removed, takomo project unarchive <p> restores it exactly as it stood. This is what to reach for instead of DELETE /v1/projects/{id}, which cascades everything away irreversibly. Refuses while a worker holds a lease unless you force it, in which case those leases are released with the fence bumped, so the displaced worker gets a fencing 409 rather than a ticket frozen mid-claim.The default simple workflow is a drop-in for beads/beans: draft → todo → in_progress → done, with blocked/cancelled escape hatches, todo claimable, and no human-approval gates — so one person or a fleet of agents just works the queue. Richer per-project workflows (approval gates, autoland) are data you upload: spec/workflow-format.md.
Bearer tokens (tk_...), scoped (read/write/human/autoland/admin), hashed at rest, shown in plaintext once. One token per actor — never shared. Tokens are the whole perimeter: keep them out of git (takomo init gitignores .takomo/token), rotate by revoke-and-remint, and scope narrowly so a leak is contained. Share links are read-only and expiring but unauthenticated — treat any link as public for its lifetime. Full model: spec/auth.md.
services/agent/README.md — connect a standalone Codex service for read-only section conversations, explicit bug research, and GitHub-backed specification extraction.
docs/github-extraction.md — creating a project from the nav rail, connecting a deployment-owned GitHub App, and queuing one bounded extraction that drafts an empty specification for review in the Document and Map.
docs/bugs.md — the /bugs page, triage, and explicitly requested codebase research (CLI, MCP, REST).
docs/ask-a-human.md — the ask-a-human board: raising questions, the follow-up thread, expertise routing, and email/Slack notifications.
docs/promotions.md — recording that a ticket's work reached a stage (staging/production/published/…), domain-agnostic.
docs/hosting.md — self-hosting depth: local build, TLS, and off-box backups (Litestream).
docs/development.md — building, testing, linting, and the backlot dev loop.
docs/diagrams.md — diagram and wireframe blocks, plus private Kroki setup.
docs/document-search.md — the Document search modal (Cmd+S): keyword search always, related meaning once an admin configures an embedding provider in Settings; the ribbon embedding-status icon and its Embed now dialog; indexing delays, manual sync, and what the database then holds.
spec/openapi.yaml — the full v1 HTTP API (tickets, workflows, claims/leases, tokens, event log, /mcp).
spec/workflow-format.md — the per-project state-machine format.
spec/auth.md — tokens, scopes, and the auth model.
clients/cli/README.md · clients/mcp/README.md · plugins/takomo/README.md — the client surfaces.
docs/design/ — historical design records from July 2026: the adopt-vs-build evaluation, the third-party surveys behind it, and the build plan. Kept as the reasoning behind the shape of this thing; deliberately not kept in sync, so read the docs above for what Takomo does today.
A hosted, single-source-of-truth task tracker for AI agent fleets — configurable enforced workflows, atomic claims/leases, epics & dependency graphs, with an MCP server, CLI, and web board.
Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
Takomo runs locally over stdio.
Last checked 2026-10-28. A hosted, single-source-of-truth task tracker for AI agent fleets — configurable enforced workflows, atomic claims/leases, epics & dependency graphs, with an MCP server, CLI, and web board.