Claude Code task board: a real two-minute setup with MCP

To give Claude Code a task board, run one command, claude mcp add --transport http weft https://letsweft.com/api/mcp, then sign in to Weft in the browser the first time Claude Code connects. There is no key to copy and nothing to paste into a config file. After that, a short block in CLAUDE.md makes Claude Code claim a task before it edits code, report while it works, and leave a receipt when it finishes.

We make Weft. Facts about other products come from their official pages, checked on 27 October 2026.

What does a board give Claude Code that the terminal doesn't?

Claude Code knows the repository in front of it, not who else is working or which task a crashed session had started. A board holds that state outside any one session, so a person, a second Claude Code window and a ChatGPT chat see the same thing.

You do not need one for every repo. One person, one short session and a TODO list is often enough. The board starts paying off when work spans several sessions or several agents, or when a person has to look at results before they count.

How do I connect Claude Code to Weft in two minutes?

1. Create a free account at letsweft.com. A new board starts with four columns: Backlog, Todo, Doing and Done.
2. In your terminal, run claude mcp add --transport http weft https://letsweft.com/api/mcp. Claude Code saves the server for the current project; add --scope user if you want it in every project (see Anthropic's Claude Code MCP docs).
3. Start claude. The first time Weft is used, a browser window opens for OAuth. If it does not, type /mcp, pick weft and authenticate from there.
4. On the Weft consent screen, choose what this connection may do: full, write (everything except the three destructive tools) or read. You can change it later in Settings → Connected AI clients.
5. Back in Claude Code, ask: "What's on my board?"

The endpoint speaks MCP over Streamable HTTP and exposes 32 tools. Weft issues refresh tokens, so the client renews the sign-in itself. If you use a client that cannot do OAuth, a personal access token works too, but Claude Code does not need one. The full setup page is at letsweft.com/claude-code.

How do I check it works without letting it change anything?

Make the first prompt read-only. That tells you the tools are loaded and the sign-in reached the right workspace, and nothing on the board moves:

List my Weft board: columns, what is in Doing, and what is waiting on me.
Change nothing.

Claude Code should call get_board_state or get_my_work. Both are read-only tools. If you want a safety margin while you get used to it, set the connection to read on the consent screen: write calls are then refused, and refused calls do not count against your monthly quota.

One honest cost: the 32 tool definitions take roughly 18,000 tokens of Claude Code's context.

What does one claimed task look like?

Put a small, real task in Todo, for example "fix the flaky date test", and ask Claude Code to take it. A good run goes like this:

1. get_my_work returns what is already this client's, what is waiting on you, and whether there is room to start anything.
2. start_task claims the task, moves it to Doing and returns a runId and leaseToken. The response also tells the agent to renew every 300 seconds.
3. Claude Code works in the repo as usual. Every few minutes it calls report_progress, which renews the lease.
4. If it hits a decision only you can make, it calls request_input with options. Claude Code shows the question as its native option cards; the answer goes back through submit_answer.
5. complete_task closes the run with an outcome, artifacts such as the commit hash and test output, and what it did not do.

By default a completed task goes straight to Done. It stops in your Inbox instead when the task needs review or a verification check fails. There you choose Accept, Rework, Later or Drop. If the agent passed a nextStep, such as "merge PR #12", Accept approves exactly that step and it comes back to the agent to carry out.

The full loop, with every refusal and field, is in the claim-loop guide.

What should I put in CLAUDE.md?

The tool descriptions already carry these rules; a few lines in CLAUDE.md make them the repo's habit. Paste and adjust:

## Weft task board

Weft (MCP server "weft") is the shared board for this repo. Other AI clients
and people read it too, so keep it true.

- At the start of a session, call get_my_work. Work on what it returns;
  do not pick tasks from memory.
- Before you change any file for a task, call start_task with its id.
  Keep the runId and leaseToken it returns.
  - already_claimed: someone else holds it. Do not duplicate; pick another.
  - attention_queue_full: do not retry. Do what the response suggests
    (finish or clarify existing work).
- While working, call report_progress with runId and leaseToken about every
  5 minutes, and at each real checkpoint (tests green, PR opened).
- Call request_input only for decisions the person must make: anything
  irreversible (production, money, publishing, deleting data) or a real fork
  with no sensible default. Give options. Never ask permission to continue.
- When done, call complete_task with:
  - outcome: one or two sentences on what changed
  - artifacts: commit hash, PR URL, test command and its result
  - notDone: what you skipped or left for later
  - unknowns: what you could not verify
  - nextStep: the one step you would take if the person accepts
- If you stop without finishing, say so and leave the task in Doing.

Artifacts turn "done" into something you can check. The call never fails for missing evidence, because losing finished work is worse than recording it unverified.

What happens when a Claude Code session dies mid-task?

Nothing has to clean up after it. The claim is a lease, not a flag. start_task grants 20 minutes, and each report_progress renews it. A session that crashes, loses its network or gets closed cannot report, so silence is the signal.

• After 20 minutes with no heartbeat, the run is marked stale, the lease token is cleared and the task goes back to unassigned.
• A sweep runs every 10 minutes, and the task is also freed at once when another client tries to claim it.
• A run that is waiting on your answer keeps its claim for 60 minutes. After that the lease drops but the question stays open in your Inbox.
• Claims are decided by the database, so two Claude Code windows racing for the same task cannot both win. The loser gets already_claimed with the task's id and title.

Running several agents at once is covered in multiple AI agents on one board.

Can I see the same board from ChatGPT or my phone?

Yes. It is one board behind one endpoint. Weft is a published app in ChatGPT on every plan, including Free (setup), so you can ask ChatGPT what Claude Code finished overnight. Cursor installs with one click (setup) and Codex uses a config entry plus codex mcp login weft (setup). On claude.ai and Claude Desktop, Weft is added as a custom connector.

Weft also has iOS and Android apps. When a task lands in your queue, the phone gets a push, at most one per workspace every 10 minutes, so a question from Claude Code reaches you away from the desk. Each OAuth client is its own actor, and the board shows the name it registered with.

For reading back what an agent did, see what did my AI agent do?

What goes wrong, and how do I fix it?

Not signed in

If Claude Code reports that weft needs authentication, type /mcp, select weft and authenticate. If you disconnected the client in Weft's Settings → Connected AI clients, its old tokens are refused on the next call, so sign in again the same way.

Weft tools are not listed

Run claude mcp list and check that weft is there with the URL https://letsweft.com/api/mcp. The server is per project unless you added it with --scope user, so a different folder may not have it.

already_claimed

This is an answer, not an error. Another client holds a live lease on that task. The agent should pick different work. If you know the other session is dead, wait: the lease lapses within 20 minutes and the task is freed.

attention_queue_full

Too much finished or blocked work is waiting on you: 5 items in a one-person workspace or 10 in a team, or 45 minutes of estimated review, whichever comes first. Questions count too. start_task refuses until you clear some of the Inbox. The response lists what the agent can still do (report_progress, get_my_work, get_board_state, search), so it can finish or tidy instead of starting more.

Calls stop on the Free plan

Free includes 200 AI calls a month, and the first 48 hours after signup are not counted. A long session with a heartbeat every five minutes uses calls steadily. Pro removes the cap; see pricing.

How does this compare with a TODO.md, GitHub Issues or Hypertask?

GitHub facts link to GitHub's docs and pricing page; Hypertask facts link to their docs. For a wider table, see MCP task managers compared.

A TODO.md is the right answer for one developer on one repo: versioned with the code, no account, no auth. It breaks down when two sessions edit it, or when you want to answer a question from your phone.

GitHub Issues is the natural home when your work already is issues and pull requests and everyone on the team lives on GitHub. Weft has no GitHub integration, so commit and PR links travel as artifacts on the receipt rather than through sync.

Hypertask is the better pick if you want a CLI for hooks and CI, a REST API, agents as service accounts with their own identity, built-in AI features, time tracking or a keyboard-first app. Weft has no CLI, no public API and no time tracking. Where Weft differs is that the claim, the heartbeat and the question to the person are MCP tools Claude Code calls directly, the sign-in is OAuth with refresh, and the same board is in ChatGPT and on both phone stores. More in our Hypertask comparison.

Do I need an API key for Claude Code?

No. Claude Code signs in with OAuth in the browser, and Weft issues refresh tokens so the client renews the sign-in itself. Personal access tokens exist for clients that cannot do OAuth, but Claude Code does not need one.

Will Claude Code mark my tasks Done without me?

By default, yes: complete_task moves the task to Done with its receipt. A task that needs review, or whose verification check fails, stops in your Inbox for Accept, Rework, Later or Drop instead.

Can I stop Claude Code from deleting things?

Set the connection to write on the consent screen, or later in Settings → Connected AI clients. Write allows everything except the three destructive tools (trash_task, archive_done_tasks, complete_sprint). Read allows only the 11 read-only tools. Agents cannot delete tasks for good in any case; trash keeps them for 30 days, and restoring from trash is a Pro feature.

Does Weft charge for AI on top of Claude?

No. Weft has no AI credits: the thinking happens in Claude Code under your own Claude plan. Weft counts tool calls: 200 a month on Free, unlimited on Pro at $7 per seat a month or $60 a year. See pricing.

What if I already keep tasks in Linear, Jira, Notion or Trello?

Import is free on every plan: CSV exports from Linear, Jira or Notion, or a Trello board as JSON. Claude Code can also create many tasks at once with bulk_create_tasks.

Does Weft work with other coding agents besides Claude Code?

Yes. There are 33 client setup pages, including Cursor, Codex and ChatGPT. They all reach the same board through the same endpoint.