telos

Self-hosted todos

A self-hostable todo app that is just todos.

Projects hold todos. A todo can wait on other todos, and one you are waiting on cannot be ticked off yet. Labels and due dates, and that is the app. A board and AI agents are there if you want them, and stay out of your way if you don't.

Get started View on GitHub ↗

A project in telos with AI off: todos with due dates, one overdue, labels, and a blocked todo naming the two it waits on.
Telos with AI off: a project's todos, with due dates, labels and what is blocked.

Just todos

This is the whole app for a lot of people. A project opens as a list, and AI is off until you switch it on, so there is nothing to set up or turn off first.

✅

Type it, Enter, done

Add a todo in a sentence. Press n to add, / to filter, and Ctrl K to search every project.

🔗

What waits on what

A blocked todo sits in its own section with its blockers named and its checkbox disabled. Cycles are rejected when you try to make them.

🏷️

Labels and due dates

Labels attach to projects and todos alike. A due date flags the todo when it is late, and a project can sort by them.

Nice extras, when you want them

None of these are needed to use telos. Each is off, or simply unused, until you reach for it.

🗂️

A board

The same todos as lanes you name yourself, one of which means done. Drag a card there and it is ticked off; tick the box and the card moves.

🤖

Agents on lanes

An agent is a model and its instructions. Put one on a lane and each todo there becomes a run that passes or fails and follows the lane's route.

🔌

Your own tools, over MCP

Point Claude Code or any MCP client at /mcp with an API key. Each key has a switch per tool, so a read-only key is one with its writing tools off.

AI is off on the instance, the account and the project until you switch it on, and a todo can say "AI ignores this". Set AI_ENABLED=false to remove it outright.

See it in action

With the extras on: a website relaunch with a Planner, a Worker and a Reviewer on its lanes. Click a screenshot to enlarge it.

The board: Inbox, Plan, Build, Review and Done lanes. Two todos are being worked by the Planner and the Reviewer, one waits on four others, and one has a failed attempt.
The board. Agents work the Plan, Build and Review lanes; the launch waits on what is still open.
A todo's thread: a note from you, then the Worker's PASS, the Reviewer's FAIL with its reason, and the Worker's second PASS.
A todo's thread. The Reviewer sent the work back, and said why.
The project's runs: two running now, 13 runs and their tokens in 30 days, and a list of runs with their verdicts.
Every run, its verdict and what it cost.
The same project as a list, each todo marked with its lane, and a blocked section at the bottom.
The same todos as a list, with what is blocked set apart.
Activity: what needs you, runs and tokens by project and by agent, and recent runs.
Activity: what needs you, and spend by project and agent.

How it works

A todo Added by you or an MCP client.
→
A lane with an agent When the todo is ready there, the runner starts a run: the agent's model, its instructions, its MCP servers.
→
A run Logs every tool call and records what it made. It can split the todo into new ones it then waits on.
→
The lane's route PASS moves the todo along the success route, or archives it. FAIL sends it along the failure route.

Chain lanes and you have a pipeline: a Planner splits a request into todos, a Worker does each one, and a Reviewer rules PASS or FAIL, sending the work back when it is not done. With auto-run off, nothing starts until you press Run now.

Run it yourself

One container plus Postgres: a compose file, two secrets, and docker compose up. Nothing to clone, nothing to build.

Get started Read the docs