# A shared task list for Claude Code

> Give Claude Code a task list you can see and edit in a browser. One claude mcp add command, a CLAUDE.md snippet, and every change marked human or agent.

Source: https://taskhold.com/for/claude-code
Last updated: 2026-10-26

> Short answer: Taskhold is a hosted task list Claude Code reads and updates over MCP. Add it with one claude mcp add command or by pasting a setup URL. You queue tasks in a browser; Claude Code plans each one into steps, reports progress you watch on a live board, asks blocking questions there, and finishes with a summary.

Claude Code's own task list lives in a folder on your machine and shows in the terminal. On recent models it stays empty unless you turn the task tools back on, and you can't see it from your phone or from Cursor.

Taskhold is a hosted task list that you and Claude Code both use. You add and reorder tasks in the web app. Claude Code reads the same list through MCP tools, breaks a task into steps, reports progress you watch on the [live board](https://taskhold.com/demo/live), blocks with a question when it needs you, and completes it with a summary. Every change is marked as made by you or by an agent. To also see the running step inside the terminal, one command sets up the status line (taskhold-mcp statusline --install, after the [one-line install](https://taskhold.com/install)), or use the [status line script](https://taskhold.com/docs/claude-code-status-line) or the [status line generator](https://taskhold.com/tools/claude-code-statusline).

## Setup in one paste

- Start the 7-day trial and open Settings. Click to make a setup URL. It looks like https://taskhold.com/setup/<token>.md and expires after 3 days.
- Paste it into your agent with the words "set this up". The agent fetches the markdown, which contains a fresh API key, the config for its own client and the task workflow snippet.
- The agent adds the server, then calls taskhold_list to check it works. Settings shows "Connected" when the first call arrives.

If you'd rather add it yourself, this is the command the setup file gives Claude Code. It registers a remote (Streamable HTTP) server for your user, so every project sees it:

```bash
claude mcp add --transport http --scope user taskhold https://taskhold.com/api/mcp --header "Authorization: Bearer <your atd_sk_ key>"
```

Run in a terminal. Check with claude mcp list. Docs: code.claude.com/docs/en/mcp

## Or install the Claude Code plugin

The plugin bundles the server config and the Taskhold agent skill, which teaches Claude Code the claim, note, block and complete workflow. Run these inside Claude Code and paste your atd_sk_ key when asked:

```text
/plugin marketplace add gettaskhold/taskhold-plugin
/plugin install taskhold@taskhold
```

Source: github.com/gettaskhold/taskhold-plugin (skill and config only, MIT).

Any agent that reads Agent Skills can add the skill on its own. You still connect the server with the command above:

```bash
npx skills add gettaskhold/taskhold-plugin
```

## Optional: status line and terminal board

The Taskhold CLI puts the task in progress, its bar and the running step in Claude Code's status line, and shows the live board in a terminal. It comes from taskhold.com and installs in ~/.taskhold, no sudo:

```bash
curl -fsSL https://taskhold.com/install.sh | sh
taskhold-mcp login
taskhold-mcp statusline --install
taskhold-mcp watch
```

Needs Node.js 18+ or Bun. Updates: taskhold-mcp update. Details, checksums and uninstall: taskhold.com/install

## Tell Claude Code how to use the list

Add this to the project's CLAUDE.md (or your user-level ~/.claude/CLAUDE.md to use it everywhere). The setup file includes it:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
Pass project: "<repo folder name>" on every call (created on first use, no ids needed).
- Session start: taskhold_get_current and taskhold_updates, both with project. Keep the cursor.
- New request: taskhold_begin with title, project, steps and agent: "Claude Code in <repo>". It files the task, plans the steps and starts the first one. Queued work: taskhold_list (project, status todo), then taskhold_begin with task_id.
- Each step done: taskhold_complete with start_next: true. Steps drive the progress bar.
- Long step: taskhold_progress on the step (N of M, or a percent) with a short message. Every few minutes at most.
- Need a decision: taskhold_block with one specific question, then taskhold_updates with task_id, since and wait: 50 until the reply arrives.
- Done: taskhold_complete on the task with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create with project (or taskhold_create_from_todo with file and line).
```

With that in place, starting a session with "work on the next task" is enough. Claude Code checks for a task in progress first, then takes the highest-priority todo.

## What Claude Code can do with it

- taskhold_get_current: what is already in progress, with its steps and the next one, so a new session picks up where the last one stopped.
- taskhold_list and taskhold_start: take the highest-priority todo and mark it in progress (with an agent label such as "Codex in api"), so a second agent skips it.
- taskhold_plan: break the task into ordered steps. You see a checklist and a progress bar split by step.
- taskhold_progress: report percent, or N of M, plus what it's doing now. The live board updates as it happens.
- taskhold_block: stop with a question. The task jumps to the top of the live board, where you reply or reply and unblock.
- taskhold_updates: read what you changed since it last looked, including your reply, using a cursor.
- taskhold_complete: finish a step or the task with a short summary. Completing a step returns the next one.
- taskhold_create and taskhold_create_from_todo: file new tasks, including a TODO with its file path and line number.

## Watch Claude Code work on the live board

Claude Code plans a task with taskhold_plan, then reports as it goes. Open the live board in a browser or on your phone and you see the task, not the terminal:

- A card per task an agent is working on: which agent, how long it has run, an estimate of time left once there is enough to go on, and the message from its last progress report.
- A progress bar split into one segment per step, so you see which step is running and which one is blocked.
- Blocked tasks at the top under Needs you, with the agent's question and a box to reply, or reply and unblock.
- A status dot: Live if the agent reported in the last two minutes, Quiet after that, and No word, with how long ago, after fifteen minutes. A stalled agent stands out without you reading its terminal.
- Optional desktop notifications when an agent gets blocked or finishes, and a count in the tab title while you're in another tab.

Claude Code passes a label when it starts a task, such as "Claude Code in api-server", so two sessions in different repos show up as two agents. Without a label, Taskhold uses the client name when the client sends one.

Claude Code has its own views too, and they pair well with this. Agent view (claude agents, a research preview) lists the background Claude Code sessions on your machine and which ones need input. Remote Control lets you drive a local session from the Claude app. The live board adds the task-level picture: steps, progress, the question an agent is waiting on, across every repo and every MCP client you connect.

## Why not the built-in task list or a TODO.md

- Claude Code's task list lives in ~/.claude/tasks/ on one machine and shows in the terminal with Ctrl+T. Since v2.1.268 it fills only on Opus 4.7, Sonnet 4.6, Haiku 4.5 and earlier models unless you set CLAUDE_CODE_ENABLE_TODO_TOOLS=1. Taskhold's list is the same on every model, machine and client.
- A TODO.md in the repo works, but you have to open the repo to read it, and two sessions editing it at once can step on each other. Taskhold is one list you read from any browser, with history.
- If a plain file is enough for you, keep using it. Taskhold is for when you want to queue work from anywhere, watch it move and answer questions without opening a terminal.

## What it sends, and how to disconnect

Your agent sends task titles, steps, progress and messages to Taskhold. Taskhold never sends code or commands to your machine; your agent reads your replies only when it asks for them.

To cut an agent off, open Settings > API keys and click Revoke on its key. The agent's next call fails with 401; remove the Taskhold server from the agent's MCP config to stop it trying. Each machine has its own key, so revoking one leaves the others working.

## FAQ

### Does Taskhold read my code?

No. Claude Code sends only the task text, notes, file paths and line numbers it chooses. Taskhold never connects to your repository and makes no AI model calls with your data.

### Do I need to install anything?

No. Claude Code connects to the remote server at https://taskhold.com/api/mcp directly. Nothing to install.

### Can several Claude Code sessions share one list?

Yes. Each session sees tasks already in progress, so a second session takes the next todo instead of the same one. On the live board each session shows under its own label.

### Can I see Claude Code's progress from my phone?

Yes. The live board is a web page, so it works in a phone browser: steps, progress, the current message and any blocked question, with a reply box. Claude Code's Remote Control is the way to drive the session itself from the Claude app.

### What does it cost?

$12 a month or $120 a year per person, after a 7-day trial that starts with a card. Cancel before the trial ends and nothing is charged.

## Sources

- [Claude Code docs: MCP](https://code.claude.com/docs/en/mcp), checked 2026-10-26
- [Claude Code docs: task tool availability](https://code.claude.com/docs/en/tools-reference#task-tool-availability), checked 2026-10-26
- [Claude Code docs: agent view](https://code.claude.com/docs/en/agent-view), checked 2026-10-26
- [Claude Code docs: Remote Control](https://code.claude.com/docs/en/remote-control), checked 2026-10-26

## Related

- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Claude Code task list empty? Why, and the fix](https://taskhold.com/guides/claude-code-task-list-empty.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.md)
- [Taskhold vs Claude Code agent view](https://taskhold.com/vs/claude-code-agent-view.md)
- [Task list MCP server for Cursor](https://taskhold.com/for/cursor.md)

## About Taskhold

Taskhold is a hosted task list shared by a person and their AI coding agents over MCP. Agents break tasks into steps and report progress, and the person watches a live board. $12/month or $120/year per person, 7-day trial with a card, no free plan. Made by Great Work LLC.

- Pricing: https://taskhold.com/pricing.md
- Agent index: https://taskhold.com/llms.txt