Skip to main content

How Timon works

Three diagrams give the overall picture: what runs where, what happens when an agent works, and how a Kanban task travels from code to documentation. Each one is followed by the same information as text. The terms are defined in Concepts.

The building blocks​

The desktop app, the web app and the timon CLI talk to the Timon daemon. The daemon runs agents, the Kanban dispatcher, triggers and plugins, serves the timon and timon_ask MCP servers, and starts the CLI of each agent, which reaches its model provider with your subscription.

  • Clients. The desktop app (Windows, macOS, Linux) bundles the daemon and the web app. The web app is the same interface in a browser, locally or through remote access; plugins add widgets and pages to it. The timon CLI gives the same daemon commands in a terminal and in scripts. Every client talks to the daemon over its HTTP API and receives live updates; closing a client does not stop the daemon.
  • The daemon is the heart of Timon. It runs in the background under your system's service manager (Running in the background) and listens on loopback by default. It:
    • starts each agent, follows its missions and keeps their history (Missions);
    • dispatches Kanban tasks once their dependencies and schedule allow;
    • fires triggers: schedules, webhooks, events and routines;
    • runs the host half of each plugin; the browser half runs in the client (Create a plugin);
    • serves the two built-in MCP servers, timon and timon_ask (Tools Timon gives agents);
    • keeps its configuration, database, agents, skills and plugins in the Timon home (Where Timon keeps its files).
  • Agent processes. For each mission, the daemon starts the agent's CLI (Claude Code, Codex, opencode, Copilot and others) in the agent's working folder and follows its events. The agent acts on Timon by calling the tools of the built-in MCP servers.
  • Model providers. Each CLI reaches its own provider with the account you signed it in with (Subscription accounts).

The life of a mission​

Six steps: a mission starts, Timon prepares the agent, the CLI of the agent starts, the agent works through a turn, the turn ends, the mission closes. A follow-up message after step 5 starts a new turn at step 4.

  1. A mission starts from your message in the chat, timon spawn, a Kanban task, a trigger, or another agent that delegates work with mission_spawn. The Missions table shows who started it.
  2. Timon prepares the agent: its instructions, identity docs, skills and memory rules, with the backend and model it runs on (Agents).
  3. The agent's CLI starts in the agent's working folder, or in a dedicated Git worktree for a code task, with the timon and timon_ask MCP servers.
  4. The agent works through a turn. Its output and tool activity appear live in the chat. Its questions and permission requests open as cards and wait for your answer.
  5. The turn ends. The answer is recorded and the agent waits for a next message: the mission stays open (Turn done badge). A follow-up message, from the chat or with timon send, starts a new turn at step 4.
  6. The mission closes. An agent working on a Kanban task closes its task, and the result returns to the orchestrator that created it. Timon stops an idle agent process; the mission's history stays available. See What state a mission is in.

The Kanban pipeline​

Full pipeline: code, then review when the code has a diff, then merge on a pass verdict, then doc when an agent holds the librarian role. Changes requested return to another code round, three rounds at most, then the task is blocked. code-self and code-group have no automatic review.

A code task chooses its pipeline when it is created (Choose the pipeline). With the default full pipeline, Timon chains the next stages itself:

  1. code: the coder works on its own branch, in a dedicated worktree, and closes the task.
  2. review: when the branch holds changes, a review task goes to the project's reviewer, who reads the diff and gives a verdict.
  3. Changes requested send the work back to another code round, which is reviewed again: three code rounds at most, the first one included. When the third is still not approved, or when Timon cannot read the verdict, the task moves to Blocked and waits for your decision.
  4. merge: a pass verdict creates a merge task for the project's merger, which integrates the branch.
  5. doc: once the work is merged, a doc task records the change, if an agent of the project holds the librarian role.

Each stage goes to the agent that holds the role on the project, or to a <project>.<role> agent Timon creates (Which agent and model run a task). A project folder that is not a Git repository has no merge stage: the doc task follows the review.

The two other pipelines skip the automatic review:

  • code-self: the coder merges its own branch and closes the task with the full merge SHA. No doc task follows.
  • code-group: several code tasks form a group, and one final merge task integrates them all.