Keeping an agent on the plan

Long agent sessions drift. Twenty minutes in, the thing has stopped doing what you asked, and you find out by scrolling back through a terminal trying to work out where it turned. TwigDo's answer is to make the plan a place rather than a message: your agent has to claim work before it may touch it, break it down before it starts, and say what it did when it finishes — and you watch all of that happen on a board.

This guide is for the person running the agent. It takes about five minutes to set up. For the tool-by-tool reference, see the connector docs.

On this page

Connect your agent
Tell it the house rules
What the protocol actually is
Choose how strict to be
Reading the board while it works
The three kinds of memory
When something goes wrong

1 · Connect your agent

Get a token

In the app, open the profile menu → Agent tokens → New token. Give it the name you want to see on the board — "Claude Code", "Codex on the laptop" — because that name is what appears beside every task it touches. Copy the token; it is shown once.

Point the client at TwigDo

Any MCP-compatible client. If yours only offers a "connector" or "custom integration" box — claude.ai, Claude Desktop, mobile — skip the token and use the sign-in flow instead: give it just https://mcp.twigdo.com/mcp and approve it. The connector docs cover that path. For Claude Code, Kimi, Hermes and anything else that lets you set a header:

{
  "mcpServers": {
    "twigdo": {
      "url": "https://mcp.twigdo.com/mcp",
      "headers": { "Authorization": "Bearer twig_your_token_here" }
    }
  }
}

Check it took

Ask your agent to list your TwigDo projects. If it comes back with names and progress, you are connected. From a terminal:

curl -sS -X POST https://mcp.twigdo.com/mcp \
  -H "Authorization: Bearer twig_your_token_here" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

2 · Tell it the house rules

The connector explains the protocol to an agent the moment it connects — but an agent that has not connected yet cannot be told anything, and something has to make it connect. So put the rules in whatever instructions file your client reads, in your own repository. The name depends on the client:

Client	File it reads
Codex, Cursor, Kimi and most others	`AGENTS.md` — the cross-provider convention, and the one to use if you run more than one agent
Claude Code	`CLAUDE.md`
Gemini CLI	`GEMINI.md`
GitHub Copilot	`.github/copilot-instructions.md`

This is not the same thing as agent.md. TwigDo's agent.md is not a file at all — it is the per-project brief stored in TwigDo, which you edit in the app and which is handed to an agent on every claim. The house rules below are a snippet for a file in your repository, and they are optional: they only cover the moment before an agent has connected. Copy them from Agent → Project Context in the app, or from here:

## TwigDo holds the plan

You are connected to TwigDo over MCP. The board is the plan of record — not
this file, and not your own notes.

1. Do not write code before claiming the work: `twigdo_start_task`. It hands
   you the project brief. Read it and follow it.
2. Break the task down with `twigdo_plan_task` before you start, so the plan
   is visible while it can still be corrected.
3. Finish each piece with `twigdo_complete_task` and one honest sentence on
   what actually changed — as you go, not at the end of the session.
4. Stuck, blocked or stopping? `twigdo_release_task` with the reason. Never
   go quiet while holding a claim.
5. Before you finish, rewrite the brief with `twigdo_write_context`.

You may only change the branch you have claimed.

Keep it this short. Long instruction files get skipped in favour of whatever you actually typed in the prompt — this one works because it is a constitution, not a roadmap. The roadmap belongs on the board.

3 · What the protocol actually is

Four steps, checked by the server rather than merely requested in a tool description.

Step	What happens
Claim `twigdo_start_task`	The agent takes a branch and says in one sentence how it means to tackle it. In return it gets your `agent.md`, the task's place in the tree, the whole branch with its ids, the active sprint and the decisions already taken. There is no separate "remember to read the context" step — claiming is reading it.
Plan `twigdo_plan_task`	It breaks the work into sub-tasks before writing code. They appear on your board immediately, which is the point: you see the plan while you can still change it.
Work	While it holds a claim, that task and everything under it are its to change. Nothing else is. One claim at a time, so an agent cannot wander off into a branch you were not watching.
Report `twigdo_complete_task`	Each piece is finished with a sentence on what was actually built. That sentence is saved onto the task and into the project history — where you look, instead of in a transcript you have to scroll.
Or give up `twigdo_release_task`	Blocked, out of road, or stopping for the night: the branch goes back with the reason attached and shows as blocked on the board. An honest ending beats a silent one.

Context debt

Every completed task adds to a debt against the project's agent.md, and the debt is cleared when the brief is rewritten. Agents are told how much they owe as they work; on a strict project, an agent that owes too much cannot claim anything new until it writes one. This is what turns "please update the notes" into something that actually happens — the brief stays current because work is what makes it stale.

4 · Choose how strict to be

Set this per project from the Agent menu → Agent protocol, which shows the current level and changes it in one click, or in the Project Context dialog beside the brief it governs. Every project starts on guided, so nothing is being refused anywhere until you say so. Agents can read the setting; no tool changes it — a guardrail an agent can lower is decoration.

Level	What happens	Use it when
Off	Nothing is checked. Agents change what they like, in any order.	A scratch project, or a workflow you already trust and do not want interrupted.
Guided	The default. Nothing is ever refused. A call made out of sequence still succeeds, but the result comes back with the correction attached — and agents generally read that and fall into line.	Almost always, to start. It teaches the agent the protocol without risking a session.
Strict	A write outside the claimed branch is refused outright, and an agent that owes the brief a rewrite cannot claim new work.	Real projects, long sessions, more than one agent, or anything you cannot afford to have quietly reshaped.

Start on guided and watch one session. Move to strict when you have seen the corrections working — by then you will know exactly which of your agent's habits the gate is going to catch.

5 · Reading the board while it works

Everything below updates live. You do not need to refresh, and you do not need the terminal open.

A green pill on a task — an agent is holding this branch right now. Hover it for the sentence the agent wrote about what it is doing and how long it has been at it.
An amber "Blocked" pill — an agent gave up here. Hover for why. This is your queue: it is the list of things only you can unstick.
New sub-tasks appearing under a task — that is the plan being laid out, before the code is written. If it is wrong, now is the cheap moment to say so.
Rings filling — work completing. Open any completed task to read the summary of what was actually built.
The Activity feed — the full history: who did what, in order, with agents labelled and the model they claim to be running.

In Agent → Project Context you also get the live list of what is held and by whom, with a Release button for each — the escape hatch for an agent whose process died while holding a branch.

6 · The three kinds of memory

This is what lets a project's memory live with the project instead of in Obsidian, a scratch file, or a second tool you have to remember to update. They do not overlap:

Where	What belongs in it
agent.md the brief	What you would tell someone over coffee before they started: the stack, the constraints, the conventions, where things live. Agents read it on every claim and rewrite it when they finish. Keep it compact — it is re-sent on every request.
Decisions `twigdo_record_decision`	Why things are the way they are: the library chosen, the schema fixed, the approach tried and rejected — with the reasoning that settled it. Replayed to every agent before it plans anything, which is what stops a settled question being reopened every session.
Activity feed	What happened, in order, permanently. Nobody writes to it deliberately; it is the record.

7 · When something goes wrong

"A task is stuck showing an agent on it"

The agent's process probably died mid-task. Open Agent → Project Context and press Release next to the claim. Another agent can also take over a claim that has been quiet for 45 minutes, but you should never have to wait for that.

"My agent says it was refused"

On a strict project that is the gate doing its job — read the message, it says exactly what the agent should have done. If it is refusing something legitimate, drop the project to guided, finish the session, and tell us what it caught wrongly.

"It keeps working without claiming anything"

Check the house rules are actually in the repo the agent is working in, and that it is the file that client reads. Some agents also need a nudge in the first prompt: "use TwigDo, claim the task before you start." After that the corrections in each tool result usually take over.

"Another agent took my connection"

Solo Pro and Founder Lifetime run one live agent; Team Block runs one per seat. Connecting claims the slot, so the newest agent wins and the previous one is told who took it. Reconnecting takes it back. Note this is separate from claims: the connection is how many agents may talk to TwigDo, a claim is which branch one of them owns.

The connector and everything on this page are included with Solo Pro, Founder Lifetime and Team Block. See pricing →