# Taskhold

> Taskhold is a hosted task list shared by a person and their AI coding agents. The person adds tasks in a web app. Agents such as Claude Code, Cursor, Codex, Windsurf, VS Code (Copilot) and Gemini CLI read and update the same list through MCP tools. Every change is recorded as made by the human or by an agent. Made by Great Work LLC.

For developers who hand work to Claude Code, Cursor or Codex, Taskhold is a hosted task list that you and your agents share. Unlike a TODO.md in one repo, it works across repos and machines, shows which tasks each agent started, blocked or finished, and you can add tasks from your phone.

Agents setting a person up: fetch [/SKILL.md](/SKILL.md). It has the prices, prefilled checkout links (/checkout?plan=month or /checkout?plan=year) and the setup steps.

Links in this file are relative to the site this file is served from.

## What it does

- The person adds, edits and prioritizes tasks in the web app, grouped into projects and labels.
- Agents connect to a remote MCP server (Streamable HTTP) at `/api/mcp` with an API key sent as `Authorization: Bearer <key>`.
- Agents pick up the current or highest-priority task, start it, add notes, block it with a reason the person sees, and complete it with a summary.
- Agents can file new tasks, including tasks created from a TODO in code with a file path and line number.
- Agents break work into ordered steps (subtasks) and report progress (a percent, or N of M, plus what they're doing now). The person watches it on a live board: one card per task in progress with a progress bar split by step, which agent is on it, how long it has run and an estimate of time left, updating as it happens (Server-Sent Events).
- Blocked tasks show up at the top of the live board with the agent's question; the person replies (and unblocks) from there, and the agent reads the reply with `taskhold_updates`.
- Optional desktop notifications when an agent gets blocked or finishes a task.
- Every change keeps a history entry that says whether a human or an agent made it, and which agent.

## Live progress (added 2026-10-25)

Can you watch a coding agent's progress on a task? With Taskhold, yes. The agent splits the task into ordered steps with `taskhold_plan`, then reports progress with `taskhold_progress` (a percent, or N of M, plus a short message about what it is doing now). The person's live board at `/dashboard/live` shows one card per task in progress: a progress bar split by step, which agent is on it, how long it has run, an estimate of time left and the current step. It updates as it happens over Server-Sent Events. When the agent is stuck it blocks the task with a question; the card moves to the top, the person replies from the board, and the agent reads the reply with `taskhold_updates`. Optional desktop notifications fire on blocked and finished tasks. Works with any MCP client, including Claude Code, Cursor, Codex, Windsurf, VS Code and Gemini CLI. Changelog entry: [2026-10-25](/changelog).

## MCP tools

- `taskhold_get_current`: the task in progress, with its steps and the next one
- `taskhold_list`: tasks grouped by status (filters: status, priority, project_id, limit)
- `taskhold_get`: one task with its steps and notes
- `taskhold_search`: text search across tasks
- `taskhold_create`: new task (title, description, priority, project_id, labels)
- `taskhold_create_from_todo`: new task from a code TODO (file_path, line_number)
- `taskhold_plan`: break a task into ordered steps (subtasks); `replace` re-plans steps not started yet
- `taskhold_start`, `taskhold_complete`: start a task or step, finish it with a summary (completing a step returns the next one)
- `taskhold_progress`: report percent, or current and total, plus a short message about what's happening now
- `taskhold_updates`: what the human changed since a cursor (replies, new tasks, priority changes)
- `taskhold_block`, `taskhold_unblock`: block with a reason, unblock
- `taskhold_add_note`: add a note to a task
- `taskhold_update`, `taskhold_set_priority`: edit a task
- `taskhold_list_projects`, `taskhold_list_labels`, `taskhold_get_summary`: context

## Setup

1. Sign in with an email link (no passwords) and start the 7-day trial.
2. In Settings, create a setup URL. It ends in `.md` and expires after 3 days.
3. Paste the URL into the agent and say "set this up". The markdown it returns contains a new API key, the MCP config for Claude Code (`claude mcp add --transport http ...`), Cursor and Windsurf (JSON), and Codex (TOML), plus a short CLAUDE.md snippet describing the workflow.

## Claude Code plugin and agent skill

- Public repo (skill + MCP config, MIT): https://github.com/gettaskhold/taskhold-plugin
- Claude Code plugin: `/plugin marketplace add gettaskhold/taskhold-plugin`, then `/plugin install taskhold@taskhold` and paste the atd_sk_ key when asked
- Skill only (any agent that reads skills): `npx skills add gettaskhold/taskhold-plugin`
- skills.sh listing: https://skills.sh/gettaskhold/taskhold-plugin/taskhold
- Official MCP Registry name: `com.taskhold/taskhold`

## Pricing

- One plan, Pro: $12 per month or $120 per year, per person.
- Includes unlimited projects and tasks (fair use) and every agent the person runs.
- 7-day trial with a card up front. Cancel before it ends and nothing is charged.
- No free plan. Cancel any time from Billing (Stripe customer portal).
- Details: [Pricing](/pricing.md)

## Data and privacy

- Data is stored in SQLite on the company's own server at DigitalOcean in the US.
- Agents send only the task text, notes, file paths and line numbers they choose. The service does not read code repositories and makes no AI model calls with user data.
- API keys are stored as SHA-256 hashes.
- Payments by Stripe, email by Resend.

## Limits

- Shared team workspaces are not available; each person subscribes and has their own list.
- Export: Download my data in Settings saves everything as one JSON file (tasks with steps, notes and history, events, projects, labels); `GET /api/account/export` with an API key returns the same file (see /docs/rest-api). Delete my account in Settings deletes everything and cancels the subscription.
- Shutdown: extremely unlikely; if it happened, every account gets email at least 90 days before and can export from Settings until the last day.
- Progress reports are capped at 120 per minute per account; fair-use ceilings of 500 projects, 100,000 tasks and 50 API keys. Nothing past a limit is charged.

## Not a fit if

- You want one workspace for a whole team.
- You want it free: a TODO.md in the repo or Claude Code's built-in task list costs nothing.
- Your tasks should sit next to pull requests: GitHub Issues does that better.
- You need a sync with Jira or Linear.

## API and discovery

- [llms-full.txt](/llms-full.txt): this file plus every setup page, guide, comparison, developer doc and the changelog as markdown, in one fetch
- Markdown twins: add `.md` to any /for, /guides or /vs page (for example [/guides/claude-md-task-workflow.md](/guides/claude-md-task-workflow.md)), or send `Accept: text/markdown` to the page URL
- [OpenAPI 3.1 spec](/openapi.json): the REST API (tasks, steps, progress, notes, projects, labels, summary, events), Bearer atd_sk_ key
- Live events: `GET /api/events/stream` (Server-Sent Events, resumes from Last-Event-ID), `GET /api/events?since=<cursor>` (polling), `GET /api/live` (everything the live board shows)
- [Agent setup file](/SKILL.md): prices, checkout links, setup steps for an agent
- [ARD catalog](/.well-known/ai-catalog.json) and [MCP server card](/api/mcp/server-card)
- [Changelog RSS](/changelog.xml): subscribe to tool and API changes
- [Changelog](/changelog): dated changes; renamed or removed MCP tools are listed there before they ship
- Errors: 401 responses carry a `reason` (missing_key, bad_header, not_a_taskhold_key, unknown_key), a `message` with the next step, and a `url`; 402 means no active subscription and links to Billing

## Try it without an account

- [Live board demo](/demo/live): a scripted agent plans five steps, reports progress and stops to ask a question the visitor answers on the board. No sign-in, runs in the browser.

## Pages

- [Home](/): product overview, pricing and FAQ
- [Developer docs](/docs): connect an agent, report live progress over MCP or REST, stream events, recipes
- [Integrations](/integrations): Taskhold with other coding agents, multi-agent runners, status lines, notifications, hooks and CI
- [Press kit](/press): product description, boilerplates, screenshots, demo video, contact
- [Changelog](/changelog)
- [Privacy Policy](/privacy)
- [Terms of Service](/terms)

## Contact

- hello@greatwork.company

## Setup by agent

- [Task list MCP server for Claude Code](/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.
- [Task list MCP server for Cursor](/for/cursor): Connect Cursor's agent to a task list you share: one ~/.cursor/mcp.json entry, a rules snippet, and every task it starts, blocks or finishes in view.
- [Task list MCP server for Codex CLI](/for/codex): Add a shared task list to OpenAI's Codex CLI: one block in ~/.codex/config.toml, an AGENTS.md snippet, and a web app where you queue and review its work.
- [Task list MCP for Windsurf and Devin Desktop](/for/windsurf): Connect Windsurf, now called Devin Desktop, to a task list you share. Where mcp_config.json lives, the JSON for a remote server, and the workflow snippet.
- [Task list MCP server for VS Code and Copilot](/for/vs-code): Connect Copilot's agent mode in VS Code to a task list you share: one .vscode/mcp.json entry, a password input for the key, and the workflow snippet.
- [Task list MCP server for Gemini CLI](/for/gemini-cli): Give Gemini CLI a task list you share: one gemini mcp add command or a settings.json entry, a GEMINI.md snippet, and every change marked human or agent.
- [Task list MCP server for OpenCode](/for/opencode): Give OpenCode a task list you share with your other agents: one remote entry in opencode.json, an AGENTS.md snippet, and a live board for its progress.

## Guides

- [A shared todo list for Claude Code and Cursor](/guides/shared-todo-list-for-claude-code-and-cursor): Run Claude Code and Cursor on the same backlog without them starting the same task. How to connect both to one list, and how to read what each one did.
- [How to hand tasks to your coding agent](/guides/hand-tasks-to-your-coding-agent): Queue work for Claude Code, Cursor or Codex from anywhere, have the agent pick it up in priority order, and get a summary or a question back on each task.
- [Run several coding agents on one task list](/guides/run-multiple-coding-agents-on-one-task-list): Parallel Claude Code sessions, Cursor and Codex on one backlog: how agents claim tasks, what happens when one gets stuck, and the limits to know about.
- [A CLAUDE.md task workflow that survives sessions](/guides/claude-md-task-workflow): A short CLAUDE.md or AGENTS.md snippet that makes an agent resume work in progress, claim the next task, block with a reason and finish with a summary.
- [Turn TODO comments into tasks your agent can do](/guides/turn-code-todos-into-tasks): Have your coding agent file TODO comments and bugs it notices as tasks with file path and line, so they land on a list instead of rotting in code.
- [What your coding agent did while you were away](/guides/review-what-your-agent-did): Check one page for what your agents finished, what is blocked on you, and what they filed, instead of scrolling terminal history after a long run.
- [Watch Claude Code agent teams on a live board](/guides/claude-code-agent-teams-live-board): Claude Code agent teams share a task list you only see from the lead's terminal. Give every teammate Taskhold's tools and follow the team on one board.
- [Break a spec into tasks for your coding agent](/guides/break-a-spec-into-agent-tasks): Turn a spec or PRD into a prioritized task list your coding agent works through one task at a time, with notes and a summary on each, in a list you edit.
- [One task list for coding agents across repos](/guides/one-task-list-across-repos): One backlog for every repo your coding agents work in, grouped by project, so a session in any repo picks up its own tasks and you see them all at once.
- [See what your coding agent is doing right now](/guides/monitor-coding-agent-progress): What Claude Code, Codex and Cursor show about a running agent, what they can't, and how to get step-by-step progress for every agent on one live board.
- [Get notified when your coding agent is blocked](/guides/answer-a-blocked-coding-agent): Desktop alerts for Claude Code and Codex when they need input, and a way to answer an agent's blocking question from your phone without its terminal.
- [Claude Code task list empty? Why, and the fix](/guides/claude-code-task-list-empty): Ctrl+T shows nothing on newer Claude models because the task tools are off by default. The environment variable that brings them back, and other causes.
- [AI coding statistics: adoption, trust and agents](/guides/ai-coding-statistics): Sourced AI coding statistics from Stack Overflow, JetBrains, DORA, METR and Anthropic: who uses AI and agents, who trusts it, and what agents write.

## Comparisons

Each comparison says when the other tool is the better pick.

- [Taskhold vs Claude Code's built-in task list](/vs/claude-code-tasks): Claude Code's own task list is free and built in. When it is enough, and when a hosted list shared with Cursor, Codex and your phone is worth $12 a month.
- [A Vibe Kanban alternative for your agent backlog](/vs/vibe-kanban): Vibe Kanban is sunsetting and its hosted features were removed. What it still does well, what Taskhold covers instead, and what it doesn't.
- [Taskhold vs Taskmaster AI for coding agents](/vs/taskmaster-ai): Taskmaster AI breaks a PRD into dependent tasks inside your repo, for free. Taskhold is a hosted list you and your agents share. Which fits which workflow.
- [Taskhold vs Backlog.md for AI coding agents](/vs/backlog-md): Backlog.md keeps tasks as markdown files in your git repo, free and offline. Taskhold is a hosted list across repos. A fair look at when each one wins.
- [Taskhold vs Linear MCP for personal agent tasks](/vs/linear): Linear's MCP server puts agents into a team's issue tracker. Taskhold is a lighter list for one developer and their agents. Prices, setup and fit compared.
- [Taskhold vs GitHub Issues as an agent task board](/vs/github-issues): GitHub Issues with the GitHub MCP server is free and sits next to your code. When it makes a good agent board, and when a separate list fits better.
- [Taskhold vs a TODO.md file for coding agents](/vs/todo-md): A TODO.md in the repo is free, versioned and readable by any agent. When it is enough, and when a hosted list shared with your agents is worth $12 a month.
- [Taskhold vs Todoist MCP for coding agent tasks](/vs/todoist): Todoist has an official hosted MCP server and a free plan. When Todoist is the right list for your agents, and when a list built for coding agents fits.
- [Taskhold vs Claude Code agent view](/vs/claude-code-agent-view): Agent view lists your background Claude Code sessions and which need you. How it differs from a task-level live board shared by every agent you run.
- [Taskhold vs Beads (bd) for coding agent tasks](/vs/beads): Beads is a free, Dolt-backed issue graph your agents claim work from on the command line. Taskhold is a hosted list with a live board. When each one fits.
- [Task managers for AI coding agents, compared](/vs/ai-coding-agent-task-managers): Claude Code tasks, Taskmaster, Backlog.md, Beads, Linear, GitHub Issues, Todoist, Vibe Kanban and Taskhold side by side, with prices checked October 2026.

## Integrations

Taskhold with other tools: coding agents, multi-agent runners, status lines, notifications, hooks and CI.

- [Use Taskhold with Cline](/integrations/cline): Connect Cline to a task list you share: one cline_mcp_settings.json entry, a .clinerules file, and a live board of what it plans, runs and asks.
- [Use Taskhold with Kilo Code](/integrations/kilo-code): Add Taskhold to Kilo Code as a remote MCP server in kilo.jsonc, keep the key in an env var, and watch each task's steps on a live board.
- [Taskhold for Roo Code users: Kilo Code or Cline](/integrations/roo-code-users): Roo Code's repository is archived. Here is how to keep a shared task list and live board when you move to Kilo Code or Cline, with the config for each.
- [Use Taskhold with Zed's agent](/integrations/zed): Add Taskhold to Zed as a remote context server with a bearer header, give the agent the workflow in AGENTS.md, and follow it on a live board.
- [Use Taskhold with JetBrains Junie](/integrations/junie): Connect Junie in JetBrains IDEs or the Junie CLI to Taskhold with one mcp.json entry, add the workflow to AGENTS.md, and watch tasks on a live board.
- [Use Taskhold with Augment Code and Auggie](/integrations/augment-code): Add Taskhold to the Auggie CLI with one auggie mcp add command or settings.json entry, share the rules with the Augment extension, and watch a live board.
- [Use Taskhold with the Trae IDE](/integrations/trae): Add Taskhold to Trae as an MCP server with a url and an Authorization header, put the workflow in a Trae rule, and see each task's steps on a live board.
- [Use Taskhold with Goose](/integrations/goose): Add Taskhold to Goose as a streamable_http extension in config.yaml, pull the key from an env var, and watch each task's steps on a live board.
- [Use Taskhold with Amp](/integrations/amp): Connect Amp to Taskhold with an amp.mcpServers entry that reads your key from an env var, add the AGENTS.md workflow, and see its progress live.
- [Use Taskhold with Kiro](/integrations/kiro): Add Taskhold to Kiro's mcp.json with an approved env var for the key, steer the agent with AGENTS.md, and follow every task on a live board.
- [Use Taskhold with Warp's agent](/integrations/warp): Add Taskhold to Warp as an MCP server with a bearer header, keep the workflow in AGENTS.md, and watch the agent's steps on a live board.
- [Use Taskhold with Charm's Crush](/integrations/crush): Add Taskhold to Crush with one mcp add line in crushrc, mark it sessionless, and let Crush report steps and questions to a live board.
- [Use Taskhold with Qwen Code](/integrations/qwen-code): Connect Qwen Code to Taskhold with an httpUrl entry in settings.json, read the key from an env var, and watch its plan and progress on a live board.
- [Use Taskhold with Factory Droid](/integrations/factory-droid): Add Taskhold to Factory's Droid with droid mcp add or ~/.factory/mcp.json, expand the key from your shell, and see its steps on a live board.
- [Use Taskhold with GitHub Copilot's cloud agent](/integrations/copilot-coding-agent): Give GitHub Copilot's cloud coding agent your Taskhold list: MCP config in repo settings, a COPILOT_MCP_ secret for the key, and a live board of its runs.
- [Use Taskhold with GitHub Copilot CLI](/integrations/copilot-cli): Add Taskhold to GitHub Copilot CLI in ~/.copilot/mcp-config.json with a bearer header, share the AGENTS.md workflow, and watch its tasks on a live board.
- [Use Taskhold with Claude Desktop and claude.ai](/integrations/claude-desktop): Add Taskhold to Claude Desktop and claude.ai as a custom connector with a request header, or run it locally, then plan and track tasks on a live board.
- [Show your Taskhold task in ccstatusline](/integrations/ccstatusline): Add the running Taskhold task, its progress bar and current step to ccstatusline with a Custom Command widget. Exact settings, timeout and caching.
- [ccusage and Taskhold in one Claude Code status line](/integrations/ccusage): Keep ccusage's cost and burn rate in the Claude Code status line and add the current Taskhold task on a second row, with one short wrapper script.
- [Show your Taskhold task in CCometixLine](/integrations/ccometixline): Add the running Taskhold task and its progress to CCometixLine with a cmd metric in config.toml, cached for 10 seconds and run in the background.
- [Show your Taskhold task in the Starship prompt](/integrations/starship): A Starship custom module that puts the running Taskhold task and its progress bar in your shell prompt, with the timeout setting it needs.
- [Taskhold in tmux: status bar and a live board pane](/integrations/tmux): Show the running Taskhold task in tmux's status bar every 10 seconds, and keep the whole live board in a pane next to your agents with taskhold-mcp watch.
- [Show your Taskhold task in WezTerm's tab bar](/integrations/wezterm): A WezTerm update-status handler that puts the running Taskhold task and its progress bar on the right of the tab bar, refreshed every 10 seconds.
- [Show your Taskhold task in iTerm2's status bar](/integrations/iterm2): Put the running Taskhold task in iTerm2's status bar with a user variable and an Interpolated String component, or a self-refreshing Python one.
- [Taskhold in the Mac menu bar with SwiftBar or xbar](/integrations/swiftbar): A five-line SwiftBar or xbar plugin that shows the running Taskhold task and its progress in the macOS menu bar, with a link to the live board.
- [Show your Taskhold task in Raycast](/integrations/raycast): A Raycast inline Script Command that shows the running Taskhold task and its progress bar in Raycast's root search, refreshed every 10 seconds.
- [Phone alerts from Taskhold with ntfy](/integrations/ntfy): Get an ntfy push on your phone when a coding agent blocks a Taskhold task or finishes one, with a tap-through to the live board. One bash script.
- [Pushover alerts when a coding agent needs you](/integrations/pushover): A bash script that sends a Pushover notification when an agent blocks or finishes a Taskhold task, high priority for questions, linked to the live board.
- [Discord alerts when a coding agent is blocked](/integrations/discord): Post to a Discord channel through a webhook when a coding agent blocks a Taskhold task or finishes one, with the question or summary and a board link.
- [Telegram messages when a coding agent needs you](/integrations/telegram): A Telegram bot message when a coding agent blocks a Taskhold task or finishes one: a bash script on the events stream and the Bot API's sendMessage.
- [Mac notifications when a coding agent is blocked](/integrations/macos-notifications): Native macOS notifications when a coding agent blocks or finishes a Taskhold task, even with the board closed, using terminal-notifier and one bash script.
- [Microsoft Teams alerts for blocked coding agents](/integrations/microsoft-teams): Post an Adaptive Card to a Teams channel through a Workflows webhook when a coding agent blocks or finishes a Taskhold task. One bash script.
- [File a Taskhold task when GitHub Actions fails](/integrations/github-actions): One GitHub Actions step that files a high-priority Taskhold task with the logs link when a workflow fails, so your coding agent picks up the fix.
- [File a Taskhold task when a GitLab pipeline fails](/integrations/gitlab-ci): A GitLab CI job that runs only when the pipeline fails and files a high-priority Taskhold task with the pipeline link for your coding agent to pick up.
- [Use Taskhold with Claude Squad](/integrations/claude-squad): Run several Claude Code or Codex sessions with Claude Squad and see what each is doing on one Taskhold board, labelled by branch, blocked ones first.
- [Use Taskhold with Conductor](/integrations/conductor): Run Claude Code and Codex workspaces in Conductor and track every one on a Taskhold live board, labelled by workspace, with questions that need you first.
- [Use Taskhold with ccmanager's status hooks](/integrations/ccmanager): Run agent sessions in ccmanager and use its status hooks to post "waiting for input" on the Taskhold task, so the live board shows which session needs you.
- [Use Taskhold with Agent Deck](/integrations/agent-deck): Add Taskhold to Agent Deck's MCP catalog once, attach it to any session with one key, and follow every agent's plan and progress on a live board.
- [Use Taskhold alongside container-use](/integrations/container-use): Agents that work in container-use environments can still plan and report to Taskhold: both are MCP servers on the same agent. The one permission to add.
- [Cursor hook: show on the board when the agent stops](/integrations/cursor-hooks): A Cursor stop hook that marks the Taskhold task in progress when Cursor's agent finishes, aborts or errors, so the live board shows it stopped.
- [Codex notify: show each turn's result on the board](/integrations/codex-hooks): Use Codex's notify setting to copy the agent's last message onto the Taskhold task in progress after each turn, so the live board shows what it just did.
- [Gemini CLI hook: show each reply on the board](/integrations/gemini-cli-hooks): An AfterAgent hook for Gemini CLI that copies each reply onto the Taskhold task in progress, so the live board shows what the agent just did.
- [Windsurf Cascade hook: show each reply on the board](/integrations/windsurf-hooks): A post_cascade_response hook for Windsurf (Devin Desktop) that copies Cascade's reply onto the Taskhold task in progress, so the live board stays current.

## Docs

Add .md to any docs URL for markdown ([/docs.md](/docs.md) is the index).

Start here:

- [What Taskhold is: a task list your agents report into](/docs/overview): Taskhold in one page: a hosted task list you share with your coding agents, live progress per step, the MCP and REST surfaces, price, data handling.
- [Quickstart: watch your agent's first plan in 5 minutes](/docs/quickstart): Connect Claude Code, Cursor or any MCP client to Taskhold and watch your agent plan steps and report progress on the live board, in about five minutes.
- [Install the Taskhold CLI: terminal board and status line](/install): Most agents need nothing installed. One command adds the Taskhold terminal board and the Claude Code status line. How updates, pins and uninstall work.

Live progress:

- [How live progress works: steps, bars, ETA and liveness](/docs/live-progress): How Taskhold turns agent reports into a live board: steps as subtasks, progress rollup, the live and quiet markers, the time estimate, blocked questions.
- [How agents should write progress notes and questions](/docs/agent-messages): Write progress messages and blocking questions a person can act on from the live board: headline first, one request, options with a recommendation.

Recipes:

- [Show the current task in the Claude Code status line](/docs/claude-code-status-line): A 24-line script that puts the Taskhold task in progress, its progress bar and the running step in the Claude Code status line. Uses curl and jq.
- [Claude Code hook: start every session with your replies](/docs/claude-code-hooks): A SessionStart hook that tells Claude Code which Taskhold task is in progress and what you changed since, so a new session picks up your replies first.
- [Report CI and deploy progress to Taskhold with curl](/docs/ci-progress): Have a GitHub Actions job open a Taskhold task, plan its stages as steps, tick them off and block with the logs link on failure. Plain curl and jq.
- [Slack alerts for blocked tasks from the events stream](/docs/slack-alerts): A 53-line Bun script that follows the Taskhold event stream and posts to a Slack channel when an agent blocks with a question or finishes a task.
- [Review what each coding agent did this week](/docs/agent-review): A Bun script that reads the Taskhold events API and prints a weekly scorecard per agent, with dated evidence and the CLAUDE.md lines to add.

Reference:

- [Taskhold MCP tools reference (taskhold_*)](/docs/mcp-tools): Every Taskhold MCP tool: what it does, its arguments, what it returns and when an agent should call it. Remote server at taskhold.com/api/mcp.
- [Taskhold REST API: tasks, steps, progress, curl examples](/docs/rest-api): Taskhold REST API reference: authentication, tasks, steps, progress, notes, events and the live snapshot, with curl examples and real responses.
- [Taskhold events API and Server-Sent Events stream](/docs/events): Follow every Taskhold change as it happens: the cursor feed at /api/events, the SSE stream at /api/events/stream, event types and a curl watcher.
- [Troubleshooting Taskhold: errors, missing tools, no progress](/docs/troubleshooting): Fixes for the common Taskhold problems: no taskhold tools in the agent, 401 and 402 responses, a bar that won't move, stale cards and silent streams.
- [Glossary: blocked, steps, progress reports, setup URLs](/docs/glossary): What Taskhold means by blocked, step, progress report, agent label, setup URL, API key and live board, so agents, docs and people mean the same thing.
- [Security and buying questions](/docs/security): Where Taskhold stores data, what leaves your machine, subprocessors, auth, deletion, export, pricing and what isn't built: answers for a security review.

## Free tools

- [Free tools hub](/tools): the three browser tools below on one page, grouped by job. No sign-up.
- [Remote MCP server config generator](/tools/mcp-config): turns one remote MCP server URL and header into the config for Claude Code, Cursor, Codex, Windsurf, VS Code, Gemini CLI, Cline and OpenCode. Runs in the browser.
- [Claude Code status line generator](/tools/claude-code-statusline): pick segments, copy a tested bash+jq script and the statusLine setting. Runs in the browser.
- [Coding agent visibility check](/tools/agent-visibility-check): eight yes/no questions on how well you can see what your coding agents are doing, with the fix for each gap. No sign-up.

---

# Taskhold changelog

> Dated changes to Taskhold, newest first. Renamed or removed MCP tools are listed here before they ship.

Source: https://taskhold.com/changelog

## 2026-10-27: Integrations, your data in Settings, and a monthly changelog email (added)

- 43 integration guides at /integrations: agent clients and editors, tools that run several agents at once, status lines and terminals, notifications (ntfy, Pushover, Discord, Telegram, Teams, macOS) and CI.
- Settings > Your data: download everything in your account as one JSON file, or delete your account (cancels the subscription and removes your data at once).
- Monthly changelog email: subscribe on /changelog. One email a month, only when something shipped.
- Referrals: share your link from the dashboard; when someone you referred pays their first invoice, you both get a month's credit.
- Cancel from Settings > Billing now asks why, so we can fix what made you leave.

## 2026-10-27: Status line colors in menu bars and other tools (fixed)

- taskhold-mcp 1.3.2: `taskhold-mcp statusline` no longer shows raw color codes in SwiftBar, Raycast or ccstatusline after it ran in a terminal.

## 2026-10-26: Read-only share links for a project's live board (added)

- Share a project's live board with a link: open the project (or the live board filtered to it) and choose Share. Anyone with the link sees what agents are working on, their steps and progress, questions they're waiting on, what finished recently and what's next, updating live. No account needed.
- Off until you turn it on, one link per project. Notes and completion summaries stay hidden unless you include them. Your email, keys, task descriptions and other projects are never shown.
- Stop sharing and the link stops working at once; New link replaces it. The dialog shows how many times the link was opened.
- Shared pages are never indexed by search engines.
- The live board can be filtered to one project: /dashboard/live?project=<id>.

## 2026-10-26: Developer docs, a no-account demo and dark mode (added)

- Developer docs at /docs: a quickstart, how live progress works, how to write progress messages for a person, the MCP tools, the REST API, events and Server-Sent Events, troubleshooting, and recipes for a Claude Code status line, Claude Code hooks, CI pipelines and Slack alerts. Add .md to any docs URL for markdown.
- Live board demo at /demo/live: a scripted agent plans steps, reports progress and stops to ask a question you answer on the board. No account needed.
- MCP discovery without a key: /api/mcp answers initialize, tools/list and ping anonymously, so registries and MCP clients can list the tools before you connect. Tool calls still need an API key.
- Dark mode for the web app: follows your system by default, with a Light, System or Dark switch in the sidebar.
- Free Claude Code status line generator at /tools/claude-code-statusline.
- Changelog RSS feed at /changelog.xml.

## 2026-10-25: Live progress: steps, progress bars and a live board (added)

- Live board at /dashboard/live: every task an agent is working on, with a progress bar split by step, which agent is on it, how long it has run, an estimate of time left and what it's doing right now. Updates as it happens.
- Blocked tasks sit at the top of the live board with the agent's question. Reply, or reply and unblock, from there.
- New MCP tools: taskhold_plan (break a task into ordered steps), taskhold_progress (percent, or N of M, plus a message) and taskhold_updates (what the person changed since a cursor).
- taskhold_start takes an optional agent label. Completing a step returns the next one. taskhold_get and taskhold_get_current show the steps.
- Task list rows show steps done and a progress bar; task pages show the steps (tick, add, reorder, delete) and one timeline of notes and activity.
- Optional desktop notifications when an agent gets blocked or finishes a task.
- REST: /api/tasks/{id}/subtasks, /api/tasks/{id}/progress, /api/events, /api/events/stream (Server-Sent Events) and /api/live. See /openapi.json.
- Lists, summaries and taskhold_list now count top-level tasks only; steps appear under their task.
- taskhold_block no longer adds a separate BLOCKED note: the reason is on the task and in the activity.

## 2026-10-09: Clearer errors for agents (changed)

- 401 responses from /api/mcp and the REST API now say which problem it is (no key, wrong header format, not a Taskhold key, revoked or unknown key) and link to Settings.
- 402 responses say why access stopped and link to Billing.
- Task not found and project not found errors name the tool that returns valid ids.

## 2026-10-09: Discovery files for agents (added)

- OpenAPI 3.1 description of the REST API at /openapi.json.
- Agent setup file at /SKILL.md with prices and checkout links.
- ARD catalog at /.well-known/ai-catalog.json and the MCP server card at /api/mcp/server-card.
- Setup pages for VS Code (Copilot agent mode) and Gemini CLI.

## 2026-10-08: Claude Code plugin and agent skill (added)

- Public repo github.com/gettaskhold/taskhold-plugin: /plugin marketplace add gettaskhold/taskhold-plugin, or npx skills add gettaskhold/taskhold-plugin.
- Listed in the official MCP Registry as com.taskhold/taskhold.

## 2026-10-08: Taskhold launches (added)

- Remote MCP server at /api/mcp (Streamable HTTP, Bearer API key) with taskhold_* tools: list, get, search, create, create_from_todo, start, complete, block, unblock, add_note, update, set_priority, list_projects, list_labels, get_summary, get_current.
- Setup URLs that hand an agent a fresh key and the config for its client.
- Agent Activity view and full change history marked human or agent.
- One plan: $12/month or $120/year per person, 7-day trial with a card.

---

# 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.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Claude Code in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (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

---

# A shared task list for Cursor

> Connect Cursor's agent to a task list you share: one ~/.cursor/mcp.json entry, a rules snippet, and every task it starts, blocks or finishes in view.

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

Cursor's agent is good at the task in front of it. What it doesn't have is a backlog that you control from outside the editor and that survives the end of a chat.

Taskhold gives it one. You add tasks in the web app; Cursor reads and updates the same list through MCP tools. The live board shows what it started, how far each task has got step by step, where it got stuck and what it finished, each change marked as yours or the agent's. Running [Claude Code and Cursor on the same backlog](https://taskhold.com/guides/shared-todo-list-for-claude-code-and-cursor) works the same way, and the [live board demo](https://taskhold.com/demo/live) shows it without an account.

## Setup

- 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.

To add it by hand, put this in ~/.cursor/mcp.json for every project, or .cursor/mcp.json in one project:

```json
{
  "mcpServers": {
    "taskhold": {
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

Cursor reads url and headers for remote servers and also accepts ${env:NAME} in headers. Docs: cursor.com/docs/context/mcp

To keep the key out of the file, use "Authorization": "Bearer ${env:TASKHOLD_API_KEY}" and set that variable in your shell. Cursor may need a restart, or a toggle of the server in its MCP settings, to pick it up.

## Tell the agent how to use the list

Put the workflow in a rule (for example .cursor/rules/tasks.mdc) or in AGENTS.md:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## What the agent can do

- 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.

## See what Cursor's agent is doing without watching the editor

Cursor's agent panel shows the run you're looking at. When you queue work and switch to something else, the live board shows where it stands:

- 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.

Ask the agent to pass a label when it starts a task, for example "Cursor in web-app", which the workflow snippet above already does. The label is what the live board shows next to the task.

## Cursor plus another agent

Many people run Cursor next to Claude Code or Codex. All of them can connect to the same Taskhold list, each with its own key. A task one agent has started shows as in progress, so the others take the next one, and the live board shows each agent's tasks side by side.

## 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 it work in Cursor's background agents?

Anything in Cursor that loads your MCP servers can use it. It is a plain remote MCP server with a bearer header, nothing Cursor-specific.

### Is my code sent anywhere?

Only what the agent puts in a task: text, notes, and file paths with line numbers if it files a TODO. Taskhold doesn't read repositories.

### Can I use one key for Cursor and Claude Code?

You can, but making one setup URL per client is cleaner: each gets its own key that you can revoke separately in Settings.

### Will Cursor report progress on its own?

When the workflow snippet is in a rule or AGENTS.md, the agent calls taskhold_plan and taskhold_progress as part of the work. Without the snippet it may only start and complete tasks, and the bar fills by steps done or not at all.

### What does it cost?

$12 a month or $120 a year per person, with a 7-day trial that starts with a card.

## Related

- [A shared todo list for Claude Code and Cursor](https://taskhold.com/guides/shared-todo-list-for-claude-code-and-cursor.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Task list MCP for Windsurf and Devin Desktop](https://taskhold.com/for/windsurf.md)
- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.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

---

# A shared task list for Codex CLI

> Add a shared task list to OpenAI's Codex CLI: one block in ~/.codex/config.toml, an AGENTS.md snippet, and a web app where you queue and review its work.

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

Codex runs long tasks on its own, which makes it more useful to queue work for it and check back later. Taskhold is the queue: you add tasks in the web app, Codex picks them up through MCP tools and reports progress on each one, which you follow on the live board. [Handing tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent) covers the queue habit, and [answering a blocked agent](https://taskhold.com/guides/answer-a-blocked-coding-agent) covers the moments Codex needs you.

## Setup

- 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.

By hand, add this to ~/.codex/config.toml:

```toml
[mcp_servers.taskhold]
url = "https://taskhold.com/api/mcp"
http_headers = { "Authorization" = "Bearer <your atd_sk_ key>" }
```

Codex documents url, http_headers and bearer_token_env_var for remote servers.

To keep the key out of the file, use bearer_token_env_var = "TASKHOLD_API_KEY" instead of http_headers and export that variable.

## AGENTS.md snippet

Codex reads AGENTS.md. Add the workflow there:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## What Codex 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.

## Follow a long Codex run from anywhere

Codex is often left running on its own for a while, which is when a progress view matters most. With the snippet in AGENTS.md, Codex plans the task into steps and reports progress, and the live board shows:

- 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.

Codex's own notifications cover the terminal: in ~/.codex/config.toml, the [tui] notifications setting takes a list such as ["agent-turn-complete", "approval-requested"], and notify runs a program of your choice when a turn completes. Those tell you a turn ended or needs approval on that machine. The live board tells you how far the task got and what Codex asked, from any device.

## 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 Codex need anything installed?

No. It connects to the remote server over HTTPS. Nothing to install.

### Can Codex and Claude Code share the list?

Yes. Connect both. Tasks in progress are visible to every agent, so they don't start the same one.

### How do I reply when Codex gets stuck?

Codex blocks the task with a question. It appears under Needs you on the live board; type a reply and press Reply & unblock. Codex reads the reply with taskhold_updates the next time it checks, so it doesn't have to stop and wait in the terminal.

### What does it cost?

$12 a month or $120 a year per person, with a 7-day trial that starts with a card.

## Sources

- [Codex docs: MCP](https://developers.openai.com/codex/mcp), checked 2026-10-26
- [Codex sample config (notify, tui.notifications)](https://learn.chatgpt.com/docs/config-file/config-sample), checked 2026-10-26

## Related

- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.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

---

# A shared task list for Windsurf (Devin Desktop)

> Connect Windsurf, now called Devin Desktop, to a task list you share. Where mcp_config.json lives, the JSON for a remote server, and the workflow snippet.

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

Cognition renamed Windsurf to Devin Desktop in June 2026. The MCP setup works the same way: a JSON file listing servers, and remote servers with headers are supported.

Taskhold gives its agent a task list you share. You queue tasks in the web app, the agent works through them over MCP, and the live board shows its steps, progress and questions, with notes, blocks and summaries on each task. The [MCP config generator](https://taskhold.com/tools/mcp-config) writes the JSON for you, and the [quickstart](https://taskhold.com/docs/quickstart) walks through the first run.

## Setup

- 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.

By hand: current Devin Desktop docs put the file at ~/.config/devin/mcp_config.json on macOS and Linux (%APPDATA%\devin\mcp_config.json on Windows). Older Windsurf installs use ~/.codeium/windsurf/mcp_config.json. Add:

```json
{
  "mcpServers": {
    "taskhold": {
      "serverUrl": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

The docs accept serverUrl or url for remote servers. Docs: docs.devin.ai/desktop/cascade/mcp

Then turn the server on from the MCPs section of the agent panel's menu.

## Workflow snippet

Add this to your rules or AGENTS.md:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## What the agent can do

- 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 the agent's progress outside the editor

With the snippet in your rules, the agent plans a task into steps and reports as it works. The live board in any browser shows:

- 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.

## How do I keep the key out of mcp_config.json and stay under the tool limit?

Devin Desktop interpolates ${env:VAR} and ${file:path} in serverUrl, url and headers, so the key can live in an environment variable or a file instead of the config:

```json
{
  "mcpServers": {
    "taskhold": {
      "serverUrl": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:TASKHOLD_API_KEY}" }
    }
  }
}
```

An unset variable resolves to an empty string, which Taskhold answers with 401. Docs: docs.devin.ai/desktop/cascade/mcp (Config Interpolation)

Cascade can use at most 100 tools at once across all servers. Taskhold brings 19. If other servers push you over, list the ones you don't need in disabledTools and keep the ones live progress runs on: taskhold_list, taskhold_get_current, taskhold_start, taskhold_plan, taskhold_progress, taskhold_block, taskhold_updates and taskhold_complete.

```json
"disabledTools": ["taskhold_list_labels", "taskhold_set_priority", "taskhold_search"]
```

Inside the taskhold entry. The MCPs section of the Cascade panel shows how many tools each server has enabled.

On a Teams or Enterprise plan, an admin can turn MCP off or allow only approved servers. If Taskhold doesn't appear in the MCPs list, ask them to add https://taskhold.com/api/mcp.

## 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

### Is this the same as Windsurf?

Yes. Cognition renamed Windsurf to Devin Desktop on June 2, 2026. Setup is the same remote MCP server either way.

### Is my code sent to Taskhold?

No. Only the task text, notes, and any file path and line number the agent attaches.

### What does it cost?

$12 a month or $120 a year per person, with a 7-day trial that starts with a card.

## Related

- [Task list MCP server for Cursor](https://taskhold.com/for/cursor.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Task list MCP server for VS Code and Copilot](https://taskhold.com/for/vs-code.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# A shared task list for VS Code (Copilot agent mode)

> Connect Copilot's agent mode in VS Code to a task list you share: one .vscode/mcp.json entry, a password input for the key, and the workflow snippet.

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

Copilot's agent mode in VS Code can call MCP tools. Taskhold gives it a backlog that lives outside the editor: you add tasks in the web app, the agent takes the next one, reports progress you follow on the live board, blocks it with a reason when it needs you, and completes it with a summary. The [MCP config generator](https://taskhold.com/tools/mcp-config) writes the .vscode/mcp.json entry, and the [quickstart](https://taskhold.com/docs/quickstart) shows the first run.

## Setup

- 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.

VS Code reads remote MCP servers from .vscode/mcp.json in a workspace, or from your user mcp.json (Command Palette: MCP: Open User Configuration). An input with password set to true keeps the key out of the file; VS Code asks for it once.

```json
{
  "inputs": [
    { "type": "promptString", "id": "taskhold-key", "description": "Taskhold API key (atd_sk_...)", "password": true }
  ],
  "servers": {
    "taskhold": {
      "type": "http",
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:taskhold-key}" }
    }
  }
}
```

VS Code uses a top-level servers object with type http. Docs: code.visualstudio.com/docs/agents/reference/mcp-configuration

## Tell the agent how to use the list

Copilot reads .github/copilot-instructions.md and AGENTS.md. Put the five-line workflow in either one:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## What the agent can do

- 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.

## Follow agent mode's progress from another window

Agent mode reports its plan and progress through the Taskhold tools, so you don't need the chat panel open to know where it is. The live board shows:

- 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.

## Why don't the live-progress tools show up in VS Code?

VS Code caches each MCP server's tool list. Taskhold added taskhold_plan, taskhold_progress and taskhold_updates on 2026-10-25, so a server you connected before then can still offer the old set. Run MCP: Reset Cached Tools from the Command Palette, then start a new chat.

- MCP: List Servers: start, stop or restart taskhold, and Show Output to see a 401 (wrong or revoked key) or 402 (trial or subscription ended).
- MCP: Open User Configuration: one entry for every workspace. A .vscode/mcp.json entry only applies to that folder and follows its Workspace Trust setting.
- code --add-mcp adds a server to your user profile from a shell, handy in a dotfiles script.

```bash
code --add-mcp '{"name":"taskhold","type":"http","url":"https://taskhold.com/api/mcp","headers":{"Authorization":"Bearer <your atd_sk_ key>"}}'
```

Docs: code.visualstudio.com/docs/agents/reference/mcp-configuration (Command-line installation)

## 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 Copilot need a paid plan for MCP tools?

MCP tools run in Copilot's agent mode. Which Copilot plans and organization policies allow MCP servers is decided by GitHub and your admin, so check your Copilot settings first. Taskhold itself only needs its own subscription.

### Can VS Code and Claude Code share one list?

Yes. Connect both, ideally with one setup URL each so every client has its own key. A task one agent has started shows as in progress, so the other takes the next one.

### What does Taskhold cost?

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

## Related

- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Task list MCP server for Gemini CLI](https://taskhold.com/for/gemini-cli.md)
- [Task list MCP server for OpenCode](https://taskhold.com/for/opencode.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# A shared task list for Gemini CLI

> Give Gemini CLI a task list you share: one gemini mcp add command or a settings.json entry, a GEMINI.md snippet, and every change marked human or agent.

Source: https://taskhold.com/for/gemini-cli
Last updated: 2026-10-26

Gemini CLI connects to remote MCP servers over HTTP. With Taskhold connected, Gemini CLI works from the same list as your other agents: you queue tasks in the web app, Gemini CLI picks one up, reports progress you watch on the live board and closes it with a summary. The [MCP config generator](https://taskhold.com/tools/mcp-config) writes the settings entry, and [one task list across repos](https://taskhold.com/guides/one-task-list-across-repos) shows how it shares the list with your other agents.

## Setup

- 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.

By hand, run this once with your key:

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

gemini mcp add takes --transport http and -H/--header. Docs: geminicli.com/docs/tools/mcp-server

Or add the server to ~/.gemini/settings.json (all projects) or .gemini/settings.json (one project):

```json
{
  "mcpServers": {
    "taskhold": {
      "httpUrl": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

Gemini CLI uses httpUrl for Streamable HTTP servers.

## GEMINI.md snippet

Gemini CLI reads GEMINI.md for project instructions. Add the workflow there:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## What Gemini CLI 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.

## See Gemini CLI's progress next to your other agents

Gemini CLI reports to the same live board as Claude Code, Codex or Cursor, under its own label. For each task you see:

- 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.

## How do I stop Gemini CLI asking before every progress report?

Gemini CLI asks for confirmation before each MCP tool call unless the server is trusted, and an agent reporting progress every few minutes would ask a lot. When the prompt appears, choose Always allow this server. Or set trust in the entry, which skips every confirmation for this server:

```json
"taskhold": {
  "httpUrl": "https://taskhold.com/api/mcp",
  "headers": { "Authorization": "Bearer <your atd_sk_ key>" },
  "trust": true,
  "excludeTools": ["taskhold_set_priority"]
}
```

trust defaults to false; excludeTools hides tools from the model and wins over includeTools. gemini mcp add --trust does the same from the shell. Docs: geminicli.com/docs/tools/mcp-server

Taskhold's tools only touch your task list, never your files, so trusting the server is lower stakes than trusting one that runs commands. If you'd rather keep prompts for edits, leave trust off and use includeTools for the read and report tools only.

Type /mcp inside Gemini CLI to see whether taskhold is connected and which of its tools Gemini CLI loaded.

## 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

### Can I keep the key out of settings.json?

Gemini CLI documents environment variable expansion for the env block of stdio servers, not for headers. For a remote server, keep the key in your user settings file rather than a project file you commit, and revoke it in Taskhold Settings if it leaks.

### Does Gemini CLI see my other agents' tasks?

Yes. All agents connected to your account read and update one list, and each change is marked as made by a person or an agent.

### What does Taskhold cost?

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

## Related

- [Task list MCP server for Codex CLI](https://taskhold.com/for/codex.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Task list MCP server for OpenCode](https://taskhold.com/for/opencode.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# A shared task list for OpenCode

> Give OpenCode a task list you share with your other agents: one remote entry in opencode.json, an AGENTS.md snippet, and a live board for its progress.

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

OpenCode connects to remote MCP servers from its config file. With Taskhold connected, OpenCode works from the same list as your other agents: you add tasks in the web app, OpenCode plans the steps, reports progress you watch on the live board, asks you when it's blocked and closes the task with a summary. The [MCP config generator](https://taskhold.com/tools/mcp-config) writes the entry, and the [quickstart](https://taskhold.com/docs/quickstart) shows the first run.

## Setup

- 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.

By hand, add a remote server to opencode.json in the project root, or to ~/.config/opencode/opencode.json for every project:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "taskhold": {
      "type": "remote",
      "url": "https://taskhold.com/api/mcp",
      "oauth": false,
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

Remote servers take type remote, url and headers. oauth false skips OAuth discovery, which OpenCode's docs suggest for servers that use an API key. Docs: opencode.ai/docs/mcp-servers

To keep the key out of a file you commit, OpenCode substitutes environment variables in its config. Put the key in TASKHOLD_API_KEY and reference it:

```json
"headers": { "Authorization": "Bearer {env:TASKHOLD_API_KEY}" }
```

Docs: opencode.ai/docs/config (Variables)

## AGENTS.md snippet

OpenCode reads AGENTS.md for project instructions, and /init writes one if the repo has none. Add the workflow there:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## What OpenCode 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 OpenCode next to your other agents

OpenCode reports to the same live board as Claude Code, Codex or Cursor, under its own label, so you can leave the terminal and still know where it is. For each task you see:

- 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.

## Check the connection, or switch the tools off

- opencode mcp list lists the MCP servers OpenCode has configured. If taskhold is there but calls fail, a 401 means a wrong or revoked key and a 402 means the trial or subscription ended.
- OpenCode registers each MCP tool with the server name as a prefix, so "taskhold_*": false under tools hides every Taskhold tool without removing the server.
- enabled: false in the taskhold entry stops OpenCode connecting at startup, and keeps the entry for later.

## 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 OpenCode need OAuth to connect to Taskhold?

No. Taskhold uses an API key in the Authorization header. Setting oauth to false tells OpenCode not to try OAuth for this server, which is what its docs suggest for servers that use API keys.

### Can OpenCode and Claude Code share one list?

Yes. Connect both, ideally with one setup URL each so every client has its own key. A task one agent has started shows as in progress, so the other takes the next one.

### What does Taskhold cost?

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

## Sources

- [OpenCode docs: MCP servers](https://opencode.ai/docs/mcp-servers/), checked 2026-10-26
- [OpenCode docs: config (variables)](https://opencode.ai/docs/config/), checked 2026-10-26
- [OpenCode docs: rules (AGENTS.md)](https://opencode.ai/docs/rules/), checked 2026-10-26

## Related

- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Task list MCP server for Gemini CLI](https://taskhold.com/for/gemini-cli.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# One todo list for Claude Code and Cursor

> Run Claude Code and Cursor on the same backlog without them starting the same task. How to connect both to one list, and how to read what each one did.

Source: https://taskhold.com/guides/shared-todo-list-for-claude-code-and-cursor
Last updated: 2026-10-26

If you use Claude Code in the terminal and Cursor in the editor, each has its own idea of what to do next. Their built-in todo lists don't see each other, and neither survives the end of a session.

The fix is one list outside both tools that each of them reads and updates. This guide sets that up with Taskhold, a hosted task list with an MCP server and a live board where you watch both agents' progress, and covers the same idea with a plain file if you'd rather not use a service. Setup details for each tool are on the [Claude Code](https://taskhold.com/for/claude-code) and [Cursor](https://taskhold.com/for/cursor) pages, and [running several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list) covers what happens when more join.

## Option 1: a file in the repo

Free and fine for one repo. Create TASKS.md, tell both agents (CLAUDE.md for Claude Code, a rule or AGENTS.md for Cursor) to read it at the start and tick items off when done.

Where it breaks: you have to open the repo to see or change it, there's no record of which tool changed what beyond git, nothing stops both agents picking the same line, and it doesn't span repos.

## Option 2: one hosted list over MCP

Make two setup URLs in Taskhold's Settings, one per client, and paste each into its agent. Claude Code runs a claude mcp add command; Cursor gets a ~/.cursor/mcp.json entry. Both point at the same list with separate keys.

Then put the same workflow snippet in CLAUDE.md and in Cursor's rules:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## How they avoid doing the same task

- An agent calls taskhold_start before working, which moves the task to in progress.
- The other agent lists todo tasks only, so it takes the next one.
- If an agent stops partway, taskhold_block records why, and the task stays out of the queue until you unblock it.

This is coordination by convention, not a hard lock: two agents that call start on the same task at the same moment can still collide. In practice, with one person running a few agents, the in-progress status is enough.

## Reading what happened

Each task keeps its history and notes, with every change marked as made by you or by an agent. Agent Activity shows the task an agent is on, tasks blocked on you, recent agent notes and tasks agents created. Each agent passes a label when it starts a task, such as "Cursor in web-app", and the live board and each task's timeline show that name next to its changes.

## FAQ

### Can I use it with only one of the two?

Yes. Most people start with one agent. Adding a second later is one more setup URL.

### Does it work across several repos?

Yes. The list is per person, not per repo. Use projects in the web app to group tasks by repo.

### What does it cost?

$12 a month or $120 a year per person, with a 7-day trial that starts with a card.

## Related

- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [Task list MCP server for Cursor](https://taskhold.com/for/cursor.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.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

---

# Hand tasks to your coding agent and get answers back

> Queue work for Claude Code, Cursor or Codex from anywhere, have the agent pick it up in priority order, and get a summary or a question back on each task.

Source: https://taskhold.com/guides/hand-tasks-to-your-coding-agent
Last updated: 2026-10-26

Most of us hand work to an agent by typing it into the chat. That works for the task in front of you. It doesn't work for the five things you thought of on a walk, or for knowing which of yesterday's requests got done.

A better pattern is a queue: you write tasks down when you think of them, the agent takes them in order, and each task comes back with either a summary or a question. With Taskhold, the live board shows the task the agent is on, step by step, while it works. For a big piece of work, [break the spec into tasks](https://taskhold.com/guides/break-a-spec-into-agent-tasks) first; when the run is over, [review what the agent did](https://taskhold.com/guides/review-what-your-agent-did) on the tasks themselves; and if it stops to ask, [answer it from the board](https://taskhold.com/guides/answer-a-blocked-coding-agent).

## Write tasks an agent can finish

- One outcome per task: "Add rate limiting to /api/login (5 per minute per IP)" rather than "security stuff".
- Say when it's done. List the checks you'll run yourself: a test that passes, a curl that returns 429, a page that shows the new column. The agent runs them before it calls the task done.
- Say what's out of scope. "Don't touch the signup flow" saves a diff you'd throw away.
- Point at an example: the file or PR to copy, and one you don't want copied.
- Set priority (the agent takes urgent, then high, then medium, then low), and group by project if you work in several repos.
- End with "If unsure, block with one question." The question shows up on your live board instead of a guess in the code.

A template you can paste into the task description:

```markdown
Why: <one line: what this unblocks or who asked>
Do: <the outcome, one sentence>
Done when:
- <check 1 you can run: a test, a curl, a page that shows X>
- <check 2>
Not in scope: <what to leave alone>
Look at: <files, links, an example to copy>
Don't copy: <an example of what you don't want, if any>
Constraints: <no new dependencies, keep the public API, etc.>
If unsure: block with one question; don't guess.
```

## Let the agent pick up the next one

With Taskhold connected over MCP and this snippet in CLAUDE.md or AGENTS.md, "work on the next task" is the whole prompt:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## Blocked is an answer too

When the agent needs a decision, a credential or a review, it calls taskhold_block with a specific question and moves on. The task goes to the top of the live board under Needs you. Type the answer and press Reply & unblock; the agent reads it with taskhold_updates the next time it checks, instead of you finding the question buried in a terminal.

## Add tasks from anywhere

The web app works on a phone. Add a task while you're away from the desk, and the agent sees it at the start of its next session.

## FAQ

### Which agents work?

Claude Code, Cursor, Codex, Windsurf (Devin Desktop) and any MCP client that supports remote (Streamable HTTP) servers with a header.

### Does the agent run on its own when I add a task?

No. Taskhold is the list, not a runner. The agent sees new tasks the next time it checks, for example at the start of a session.

### What does it cost?

$12 a month or $120 a year per person, with a 7-day trial that starts with a card.

## Related

- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [Break a spec into tasks for your coding agent](https://taskhold.com/guides/break-a-spec-into-agent-tasks.md)
- [What your coding agent did while you were away](https://taskhold.com/guides/review-what-your-agent-did.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.md)
- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.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

---

# Run several coding agents on one task list

> Parallel Claude Code sessions, Cursor and Codex on one backlog: how agents claim tasks, what happens when one gets stuck, and the limits to know about.

Source: https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list
Last updated: 2026-10-26

Running agents in parallel, in separate worktrees or separate tools, is common now. The hard part is not starting them. It's keeping them off each other's work and knowing what each one finished. A shared list with a live board solves both: each agent claims a task before it starts, and the board shows every agent's progress side by side. The [CLAUDE.md task workflow](https://taskhold.com/guides/claude-md-task-workflow) is what makes agents claim tasks, [see what each agent is doing](https://taskhold.com/guides/monitor-coding-agent-progress) covers watching them, and the [live board demo](https://taskhold.com/demo/live) shows it running. How common this has become: [AI coding statistics](https://taskhold.com/guides/ai-coding-statistics).

## The pattern

- One list for all agents, outside any single repo or session.
- Each agent claims a task (status in progress) before it starts.
- Agents only take todo tasks, so a claimed task is skipped.
- Agents block with a reason instead of guessing, and complete with a summary.
- You review blocked tasks and summaries in one place.

## Set it up with Taskhold

Make one setup URL per agent or tool in Settings, so each has its own key you can revoke. Paste each into its agent. Add the workflow snippet to CLAUDE.md or AGENTS.md in each repo:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

If agents work in different repos, put tasks in projects and add a line such as "only take tasks in project <name>" to that repo's snippet.

## Watch the agents side by side

Parallel agents are where a progress view pays off: three terminals tell you little at a glance. On the live board each running task gets a card with the agent's label, a bar split by step, the time it has run and its latest message, and blocked tasks from any agent collect at the top. A card whose dot reads No word has not reported for fifteen minutes, which is usually the one to look at first.

## Limits to know

- Claiming is a status change, not a lock. Two agents that start the same task in the same second can both get it.
- Which agent did something comes from the label it passes to taskhold_start, or the client name its requests carry. Keys are per client, not per session, so give parallel sessions of one client different labels.
- There are no shared team workspaces yet: the list belongs to one person and their agents.

## FAQ

### How many agents can connect?

There is no per-agent limit or charge. The plan is per person and covers every agent that person runs.

### Do agents see each other's notes?

Yes. taskhold_get returns a task with all its notes, so an agent picking up a blocked or half-done task sees what the last one wrote.

### What does it cost?

$12 a month or $120 a year per person, with a 7-day trial that starts with a card.

## Related

- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [A shared todo list for Claude Code and Cursor](https://taskhold.com/guides/shared-todo-list-for-claude-code-and-cursor.md)
- [Watch Claude Code agent teams on a live board](https://taskhold.com/guides/claude-code-agent-teams-live-board.md)
- [Task list MCP server for Codex CLI](https://taskhold.com/for/codex.md)
- [What your coding agent did while you were away](https://taskhold.com/guides/review-what-your-agent-did.md)
- [A Vibe Kanban alternative for your agent backlog](https://taskhold.com/vs/vibe-kanban.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

---

# A CLAUDE.md task workflow that survives sessions

> A short CLAUDE.md or AGENTS.md snippet that makes an agent resume work in progress, claim the next task, block with a reason and finish with a summary.

Source: https://taskhold.com/guides/claude-md-task-workflow
Last updated: 2026-10-26

Agents follow what's in CLAUDE.md (Claude Code) or AGENTS.md (Codex, Cursor and others). A few lines there decide whether a new session starts from zero or picks up where the last one stopped, and whether it reports steps and progress to a live board you can watch. The snippet below is the one the [quickstart](https://taskhold.com/docs/quickstart) installs; the [agent message patterns](https://taskhold.com/docs/agent-messages) explain how to word progress and questions, and [Claude Code's built-in task list](https://taskhold.com/vs/claude-code-tasks) is compared at the end.

## The snippet

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

It assumes the Taskhold MCP server is connected. The same structure works with any task tool your agent can reach.

## Why each line is there

- get_current first: a session that ended mid-task left it in progress, with its steps. Checking first stops the agent from starting something new and abandoning it, and tells it which step is next.
- updates, keeping the cursor: anything you changed or answered while no session was running reaches the agent before it starts.
- Highest priority todo: you decide order in the web app; the agent doesn't have to guess.
- start with a label: marks the task as claimed, so another agent doesn't take it, and puts a name such as "Codex in api" on the live board.
- plan, then start and complete each step: you get a checklist and a bar that fills step by step, and a session that dies leaves a clear point to resume from.
- progress at milestones: "12 of 40 files" with a short message is what makes the bar and the time estimate useful during a long step. Every few minutes at most is enough.
- block with a specific question, then read updates: turns "I'm not sure what you want" into a question on the board that you answer once, and the agent picks the answer up instead of guessing.
- complete with a summary: what changed, in a sentence, attached to the task.
- create / create_from_todo: things the agent notices but shouldn't fix now become tasks instead of comments nobody reads.

## Variations

- One repo of several: "Only take tasks in project <name>."
- Review gate: "Never complete a task that changes the database schema; block it for review instead."
- Several sessions of one client: "Use a label with the worktree name, such as Claude Code in api-auth."
- Short tasks: "Skip taskhold_plan when the work is one step; start and complete is enough."

## FAQ

### Where does the file go?

CLAUDE.md in the project root (or ~/.claude/CLAUDE.md for all projects) for Claude Code; AGENTS.md in the project root for Codex and other agents that read it; Cursor also reads rules in .cursor/rules.

### Do I have to write it myself?

No. Taskhold's setup URL gives the agent this snippet along with the server config.

### Why does the agent need to be told to report progress?

Agents use the tools they are told about. Without the plan and progress lines, an agent may only start and complete tasks, and the live board can only show that a task is in progress, not how far along it is.

## Related

- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [Turn TODO comments into tasks your agent can do](https://taskhold.com/guides/turn-code-todos-into-tasks.md)
- [Break a spec into tasks for your coding agent](https://taskhold.com/guides/break-a-spec-into-agent-tasks.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

---

# Turn TODO comments into tasks

> Have your coding agent file TODO comments and bugs it notices as tasks with file path and line, so they land on a list instead of rotting in code.

Source: https://taskhold.com/guides/turn-code-todos-into-tasks
Last updated: 2026-10-08

Agents leave TODO comments, and they notice bugs outside the task they're on. Both tend to vanish: the comment sits in the code, the observation scrolls away in the chat.

Taskhold's taskhold_create_from_todo tool files them as tasks with the file path and line number attached, on the same list you already read, next to the live board where agents report progress on the tasks they pick up. The [MCP tools reference](https://taskhold.com/docs/mcp-tools) lists the arguments, [handing tasks to your agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent) covers working the queue, and [a TODO.md file](https://taskhold.com/vs/todo-md) is compared if you'd rather keep them in the repo.

## Ask for it in the workflow

The last line of the standard snippet does it:

```markdown
- Found a TODO or a bug you aren't fixing now? taskhold_create (or taskhold_create_from_todo with file and line).
```

## Sweep an existing codebase

Ask the agent once: "Find the TODO and FIXME comments in src/, skip the trivial ones, and file each real one with taskhold_create_from_todo, priority low unless it looks like a bug." You then sort and prioritize them in the web app.

## What gets stored

The task title, the agent's description, and a "file:line" reference. Not the code itself. Tasks the agent creates are marked as agent-created and listed in Agent Activity for the last 7 days.

## FAQ

### Will the agent then fix them?

Only when you prioritize them and the agent takes them as normal tasks. Filing and fixing stay separate on purpose.

## Related

- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.md)
- [What your coding agent did while you were away](https://taskhold.com/guides/review-what-your-agent-did.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

---

# See what your coding agent did while you were away

> Check one page for what your agents finished, what is blocked on you, and what they filed, instead of scrolling terminal history after a long run.

Source: https://taskhold.com/guides/review-what-your-agent-did
Last updated: 2026-10-26

After a long agent run, the record of what happened is a terminal scrollback or a chat transcript. Finding the one question the agent asked you an hour in is slow.

With the agent working from Taskhold, the record is on the tasks, and while it runs the live board shows each task's steps and progress. If you'd rather watch as it happens, see [what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress); for the questions it asked, see [answering a blocked agent](https://taskhold.com/guides/answer-a-blocked-coding-agent); and to file what it noticed along the way, [turn TODOs into tasks](https://taskhold.com/guides/turn-code-todos-into-tasks).

## What to look at

- The live board: every task an agent is on now with its steps and progress bar, anything blocked on you at the top with the agent's question, tasks finished recently, and a feed of what each agent did, by name.
- Agent Activity: the task an agent is on now, tasks blocked on you, agent notes from the last 24 hours, and tasks agents created in the last 7 days.
- Each task: notes in order, the completion summary, and the full history with each change marked human or agent.
- Blocked tasks: each has the reason the agent gave. Answer in a note and unblock it, and the agent can take it next session.

## Make the summaries worth reading

Add one line to your CLAUDE.md or AGENTS.md: "When completing a task, the summary says what changed, which files, and how you checked it."

To see over a week which agent skips summaries, asks unclear questions or gets its work reopened, run the [weekly agent review](https://taskhold.com/docs/agent-review) script against the events API.

## FAQ

### Does Taskhold see my agent's whole transcript?

No. It sees only what the agent sends through the tools: task changes, notes and summaries.

### What does it cost?

$12 a month or $120 a year per person, with a 7-day trial that starts with a card.

## Related

- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.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

---

# Watch Claude Code agent teams work on a live board

> Claude Code agent teams share a task list you only see from the lead's terminal. Give every teammate Taskhold's tools and follow the team on one board.

Source: https://taskhold.com/guides/claude-code-agent-teams-live-board
Last updated: 2026-10-26

> Short answer: Agent teams are an experimental Claude Code feature: a lead session spawns teammates that share a task list and message each other. Teammates load the same MCP servers as a regular session, so each one can report its plan, progress and questions to Taskhold, and you follow the whole team on one live board instead of switching panes.

An agent team runs several Claude Code sessions at once, and the only view of it is the lead's terminal. This guide connects every teammate to the same Taskhold list, so each one gets a card on the live board with its own label, a progress bar split by step and its questions under Needs you. It builds on [running several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list) and the [Claude Code setup](https://taskhold.com/for/claude-code).

## What agent teams are, and where you can see them

Agent teams are off by default. Setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 turns them on. One session is the lead: it spawns teammates, each a separate Claude Code instance with its own context window, and they coordinate through a shared task list (pending, in progress, completed, with dependencies) and direct messages.

You watch a team from the lead's terminal: an agent panel under the prompt in the default in-process mode, or one pane per teammate with tmux or iTerm2. The team's task list is stored under ~/.claude/tasks/ on that machine. From another room, or from your phone, none of it is visible.

## Why the Taskhold tools work inside a team

Claude Code's docs say a spawned teammate "loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills." So when Taskhold is in your user or project MCP config, every teammate gets the taskhold_* tools and reads the same CLAUDE.md lines telling it to use them.

- Add the server with --scope user, so every session on the machine has it, including teammates started in any repo.
- An in-process teammate ignores the mcpServers field of a subagent definition and loads MCP servers from your project and user settings.
- If you define teammate roles with a subagent definition that has a tools list, Claude Code limits the teammate to that list. Include the Taskhold tools there (in Claude Code, MCP tools are named mcp__<server>__<tool>), or leave tools out.

## Set it up

1. Connect Claude Code with a setup URL from Settings (see the [quickstart](https://taskhold.com/docs/quickstart)). The setup URL uses --scope user.
2. Turn agent teams on in settings.json, as below.
3. Add the team lines below to the project's CLAUDE.md, next to the usual Taskhold workflow snippet. Teammates read CLAUDE.md when they start; they don't see the lead's conversation.
4. Open the live board at taskhold.com/dashboard/live, then ask the lead for a team as usual.

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

Docs: code.claude.com/docs/en/agent-teams (Enable agent teams)

```markdown
## Agent teams and Taskhold
- Lead: before spawning teammates, taskhold_create one task per piece of work you hand out, and put its task id in that teammate's spawn prompt.
- Teammate: taskhold_start your task with agent set to "<your teammate name> (team)", taskhold_plan your steps, report taskhold_progress at milestones, and taskhold_complete with a one-line summary.
- A decision only the person can make: taskhold_block with the question, then check taskhold_updates for the reply. Questions for another teammate go by message, not Taskhold.
```

One Taskhold task per teammate gives each teammate its own card and label on the board.

## What the board shows while the team works

- A card per teammate's task with its label, elapsed time and the message from its last progress report.
- A progress bar split by the teammate's own steps, so you see which part is running.
- Questions under Needs you, answered from the board or your phone. See [answer a blocked coding agent](https://taskhold.com/guides/answer-a-blocked-coding-agent).
- A status dot that turns Quiet after two minutes without a report and No word after fifteen. Claude Code's docs list task status lag as a known limitation of teams, and that dot is where a stalled teammate shows up.

When the session ends, the tasks, notes and summaries stay in Taskhold, which is what [reviewing what your agents did](https://taskhold.com/guides/review-what-your-agent-did) reads from.

## Limits to know before you rely on it

- Agent teams are experimental, and spawning teammates needs an interactive session: with -p, a named subagent runs as an ordinary subagent.
- /resume and /rewind don't restore in-process teammates. The Taskhold tasks remain, so new teammates can pick them up with taskhold_get_current and taskhold_list.
- A session has one team, and teammates can't spawn teams of their own.
- Each teammate is a separate Claude instance, so token use grows with the size of the team.

## FAQ

### Do I need agent teams to watch several Claude Code sessions?

No. Sessions you start yourself in different terminals or repos can share one Taskhold list in the same way, each with its own label on the live board.

### Does Taskhold replace the team's own task list?

No. Teammates still claim work through Claude Code's shared list. Taskhold is the view you follow and answer from away from the terminal, and it keeps the history after the session ends.

### Can a teammate approve something for me through Taskhold?

No. Only you reply on the board. Claude Code also tells a teammate when a message came from another session rather than from you, and a teammate can't approve a permission prompt on your behalf.

## Sources

- [Claude Code docs: agent teams](https://code.claude.com/docs/en/agent-teams), checked 2026-10-26
- [Claude Code docs: MCP](https://code.claude.com/docs/en/mcp), checked 2026-10-26

## Related

- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [Taskhold vs Claude Code agent view](https://taskhold.com/vs/claude-code-agent-view.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

---

# Break a spec into tasks your coding agent can finish

> Turn a spec or PRD into a prioritized task list your coding agent works through one task at a time, with notes and a summary on each, in a list you edit.

Source: https://taskhold.com/guides/break-a-spec-into-agent-tasks
Last updated: 2026-10-09

A long spec pasted into one chat tends to get half-done: the agent runs out of context, skips a step, or reports success on the parts it remembers. Splitting the spec into tasks first, then working them one at a time, gives you a checkpoint after each piece, and a live board shows which piece the agent is on. Each task gets its own steps (see [how live progress works](https://taskhold.com/docs/live-progress)), the [CLAUDE.md task workflow](https://taskhold.com/guides/claude-md-task-workflow) keeps the agent on the list across sessions, and [Taskmaster AI](https://taskhold.com/vs/taskmaster-ai) is the tool to compare if you want the split done for you.

## Have the agent write the tasks, then you edit them

Ask the agent to read the spec and file one Taskhold task per shippable step with taskhold_create: a short title, a description with acceptance criteria, and a priority. You then reorder, merge or delete tasks in the web app before any code is written, which is the cheapest moment to catch a wrong plan.

```markdown
Read SPEC.md. Create one Taskhold task per step that can ship on its own:
title under 80 characters, description with "Done when: ...", priority high for
the first three. Don't start any of them yet.
```

## Work the list one task at a time

Each session starts with taskhold_get_current, takes the highest-priority todo, and marks it started. The agent adds notes as it goes and completes the task with a summary of what changed. A task it can't finish gets blocked with a question for you, and the next session moves on to another task instead of stalling.

## Where a spec-to-tasks tool fits better

- Taskmaster AI parses a PRD into dependent tasks stored in your repo, free and open source. Pick it if you want dependency graphs inside git.
- Backlog.md keeps tasks as markdown files in the repo. Pick it if the whole team works from git.
- Taskhold fits when you want the list in a browser and on your phone, shared by several agents across repos.

## FAQ

### How big should one task be?

Small enough that the agent can finish it in one session and you can review the diff in a few minutes. If a task's summary would need more than a short paragraph, ask the agent to split it into two tasks before starting.

### Can the agent add tasks it discovers along the way?

Yes. taskhold_create files new tasks, and taskhold_create_from_todo records a TODO with its file path and line number. New tasks show up in the web app marked as created by an agent.

## Related

- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [Taskhold vs Taskmaster AI for coding agents](https://taskhold.com/vs/taskmaster-ai.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.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

---

# One task list for your coding agents across every repo

> One backlog for every repo your coding agents work in, grouped by project, so a session in any repo picks up its own tasks and you see them all at once.

Source: https://taskhold.com/guides/one-task-list-across-repos
Last updated: 2026-10-09

A TODO.md or a repo's issue tracker only covers the repo it lives in. If you run Claude Code in one project, Codex in another and Cursor in a third, the work is spread across files and terminals you have to check one by one. One hosted list, grouped by project, with a live board of every agent's progress, puts it in one place. It's the same setup as [several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list), compared with a per-repo [TODO.md](https://taskhold.com/vs/todo-md) and [Backlog.md](https://taskhold.com/vs/backlog-md).

## One project per repo, one list for you

Taskhold groups tasks into projects. Make one project per repo, then tell each repo's agent which project is its own in CLAUDE.md or AGENTS.md. The agent filters with project_id when it lists tasks and files new tasks into that project, while you see every project in one web app.

```markdown
## Tasks (Taskhold)
This repo's project is "api". Use taskhold_list_projects to get its id, then
pass project_id on taskhold_list and taskhold_create.
```

## Work that isn't in any repo

Infrastructure chores, research questions and follow-ups land in the Inbox project. Any agent can pick them up, and you can add them from your phone without opening a terminal.

## Limits to know

- Taskhold doesn't read your repositories or link tasks to commits and pull requests.
- There are no team workspaces: the list belongs to one person and their agents.
- Fair-use ceilings: 500 projects and 100,000 tasks per account.

## FAQ

### Do I need one API key per repo?

No. One key per machine or client is enough, because the project is chosen per task. Separate keys only help when you want to revoke one machine without touching the others.

### Can I move a task between repos?

Yes. Change its project in the web app, or have an agent call taskhold_update with a new project_id. The change is recorded in the task's history.

## Related

- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Taskhold vs a TODO.md file for coding agents](https://taskhold.com/vs/todo-md.md)
- [What your coding agent did while you were away](https://taskhold.com/guides/review-what-your-agent-did.md)
- [Task list MCP server for Gemini CLI](https://taskhold.com/for/gemini-cli.md)
- [Task list MCP server for VS Code and Copilot](https://taskhold.com/for/vs-code.md)
- [Task list MCP for Windsurf and Devin Desktop](https://taskhold.com/for/windsurf.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

---

# How to see what your coding agent is doing right now

> What Claude Code, Codex and Cursor show about a running agent, what they can't, and how to get step-by-step progress for every agent on one live board.

Source: https://taskhold.com/guides/monitor-coding-agent-progress
Last updated: 2026-10-26

> Short answer: Each coding tool shows its own sessions: Claude Code has agent view and Remote Control, Codex sends terminal notifications. None of them can say how far a task has got, because only the agent knows its plan. Have the agent report steps and progress somewhere you can see, such as Taskhold's live board, which any MCP client can update.

You start an agent on a refactor, switch to something else, and twenty minutes later you want four answers: is it still working, how far has it got, is it waiting on me, and what has it finished. The terminal holds all of that, scattered through a long scrollback, on one machine. This guide shows how to monitor your coding agent's progress step by step, whichever tool runs it.

This guide covers what the tools show on their own, what an agent should report, a free way to get more, and how Taskhold's [live board](https://taskhold.com/demo/live) does it for every agent you run. For the numbers behind it, how many developers now run agents and how few trust the output unchecked, see [AI coding statistics](https://taskhold.com/guides/ai-coding-statistics).

Not sure where the gaps are? The [agent visibility check](https://taskhold.com/tools/agent-visibility-check) asks eight yes/no questions and names the fix for each no.

## What the tools show on their own

| Tool | What you can see | Limits |
| --- | --- | --- |
| Claude Code task list (Ctrl+T) | Claude's checklist for the session: pending, in progress, done, up to five items at a time | Fills only on models with the task tools (Opus 4.7, Sonnet 4.6, Haiku 4.5 and earlier by default); terminal only |
| Claude Code agent view (claude agents) | Every background Claude Code session on the machine: working, needs input, completed or failed, with a one-line summary; reply to a question from a peek panel | Research preview; Claude Code sessions on this machine |
| Claude Code Remote Control and the Claude app | Drive a local session from your phone; push notifications when a long task finishes or needs a decision | Needs a claude.ai account; Claude Code sessions only |
| Claude Code status line | Whatever your script prints from session data: model, context used, cost, branch, PR | Session data only, unless the script fetches task progress from elsewhere |
| Codex CLI | Terminal notifications when a turn completes or needs approval ([tui] notifications), and a notify program on turn complete | On the machine running Codex |
| Cursor | The agent panel in the editor window | In the editor you're looking at |

Checked 2026-10-26 against code.claude.com and the Codex sample config. Sources at the end of the page.

## The missing piece: progress the agent reports

Session views know whether a session is working or waiting. They can't tell you "step 3 of 5, 12 of 40 files migrated", because that lives in the agent's plan, not in the session. The agent has to write it down somewhere you can read, at the moments it knows something new: when it plans, between steps, inside a long step, and when it gets stuck.

So you need two things: a line in the agent's instructions, and a place for it to write. The two options below differ in where the progress lands and who can see it.

## What should an agent report?

Four things are enough, at the moments the agent knows them:

1. A plan as ordered steps, before it starts. Three to seven steps is a useful size: enough to show movement, few enough to read at a glance.
2. Progress as it goes: "step 3 of 5" or N of M items, plus one short line about what it is doing now. Agents are far better at counting finished steps than at guessing a percentage.
3. Blocked, with one specific question, when it needs a decision, access or information from you.
4. Done, with a summary of what changed and how it checked the result.

Everything else (diffs, test output, reasoning) stays in the session and the pull request. The [message patterns in the docs](https://taskhold.com/docs/agent-messages) show how to write each report so a person can act on it from a phone.

## Free option: a progress file in the repo

Ask the agent to keep a PROGRESS.md: the plan as a checklist, the current step, and a line per milestone. Add the rule to CLAUDE.md or AGENTS.md so every session does it:

```markdown
## Progress
Before multi-step work, write the plan to PROGRESS.md as a checklist.
Tick each step when done and add one line: what changed, what's next.
If you're blocked, write the question at the top under BLOCKED.
```

Even without a file, three lines in CLAUDE.md or your rules give you most of the habit inside a single session:

```markdown
Before starting a task, write your plan as 3 to 7 numbered steps.
After each step, say "Step N of M done: <one line>".
If you need a decision from me, stop and ask one specific question.
```

Where it falls short: you read it by opening the repo, there is no notification when the agent writes BLOCKED, parallel sessions in one repo edit the same file, and nothing tells you the agent went quiet an hour ago.

## Taskhold: one live board for every agent

Taskhold is a task list your agents reach over MCP. The workflow snippet asks the agent to plan each task into steps with taskhold_plan, start and complete each step, and call taskhold_progress at milestones with percent or N of M and a short message. The live board shows it as it happens:

- 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.

The time estimate is simple on purpose: elapsed time divided by progress so far, shown once the task is at least 5% done and has run for 30 seconds. Steps that take very different times make it rough; the step list tells you more than the number.

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "<client> in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

The workflow snippet the setup URL gives your agent. Put it in CLAUDE.md, AGENTS.md or your rules.

Want the same bar inside Claude Code or a terminal? The [Taskhold CLI](https://taskhold.com/install) sets up the Claude Code status line with one command (taskhold-mcp statusline --install) and runs the board in a terminal (taskhold-mcp watch). A short script does the status line too: see the [status line recipe](https://taskhold.com/docs/claude-code-status-line) or the [status line generator](https://taskhold.com/tools/claude-code-statusline).

## How does the agent get your reply?

The agent asks Taskhold what changed since it last looked, with taskhold_updates. The call takes a cursor and returns only what you changed: replies, new tasks, priority changes. Agents call it at the start of a session and between steps, so you can steer one mid-task without stopping it. [Answering a blocked agent](https://taskhold.com/guides/answer-a-blocked-coding-agent) walks through the full loop, including notifications.

## How do you know an agent stopped?

Liveness tells you, not the bar. Each card shows Live if the agent reported in the last two minutes, Quiet after that, and No word, with how long ago, after fifteen minutes. A card at 90% with No word usually means the session ended and the task needs someone to pick it up again. The bar shows what the agent last said; liveness shows whether it is still saying anything.

## How the live board is built

Every change an agent or a person makes (create, status, progress, note, edit) writes a row to an events table, and the row id is the cursor for everything: the board, taskhold_updates and the REST API. The board streams new rows over Server-Sent Events, with an in-process wake for instant updates, a 3 second poll as a backstop and a 15 second ping so proxies keep the connection open.

One gotcha if you build SSE on Next.js: its compression buffers the stream unless the response sends Cache-Control: no-transform, and nginx needs X-Accel-Buffering: no. The [events reference](https://taskhold.com/docs/events) documents the stream and the polling fallback.

## Checking from your phone

The live board is a web page, so a phone browser shows the same cards, steps and blocked questions, with the reply box. For Claude Code alone, the Claude app with Remote Control lets you drive the session itself; Taskhold is the view across Claude Code, Codex, Cursor and anything else you've connected, without a session open.

## FAQ

### Isn't the progress just what the agent says?

Yes. Progress is self-reported, like a teammate's standup. The board also shows when the agent last reported, so a dead session shows as No word even if its last report said 90%. Use it to know where things stand and what needs you; review still happens in the diff.

### How accurate is the time-left estimate?

Rough on purpose: elapsed time divided by progress so far. The board hides it until the task is at least 5% done and has run for 30 seconds, because before that a number is a guess, and while the task is blocked it shows Waiting on you instead.

### How do I tell if my coding agent is stuck?

Look for silence. On Taskhold's live board each running task has a dot that turns to No word, with how long ago, when the agent hasn't reported for fifteen minutes. In Claude Code's agent view, a session that needs you shows as needs input.

### Does reporting progress slow the agent down?

Each report is one short tool call, and the tool description asks agents to report at milestones, every few minutes at most. On a long task that is a handful of calls.

### Does Taskhold see my code or my terminal?

No. It sees only what the agent sends through the tools: task titles, steps, progress numbers, short messages, notes and summaries.

### Which agents can report to the live board?

[Claude Code](https://taskhold.com/for/claude-code), [Codex](https://taskhold.com/for/codex), [Cursor](https://taskhold.com/for/cursor), [Windsurf (Devin Desktop)](https://taskhold.com/for/windsurf), [VS Code agent mode](https://taskhold.com/for/vs-code), [Gemini CLI](https://taskhold.com/for/gemini-cli) and any MCP client that supports remote servers with a header. Each link is that client's setup page.

## Sources

- [Claude Code docs: task list](https://code.claude.com/docs/en/interactive-mode#task-list), checked 2026-10-26
- [Claude Code docs: agent view](https://code.claude.com/docs/en/agent-view), checked 2026-10-26
- [Claude Code docs: Claude Code on mobile](https://code.claude.com/docs/en/mobile), checked 2026-10-26
- [Claude Code docs: status line](https://code.claude.com/docs/en/statusline), checked 2026-10-26
- [Codex sample config](https://learn.chatgpt.com/docs/config-file/config-sample), checked 2026-10-26

## Related

- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [Claude Code task list empty? Why, and the fix](https://taskhold.com/guides/claude-code-task-list-empty.md)
- [Taskhold vs Claude Code agent view](https://taskhold.com/vs/claude-code-agent-view.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Watch Claude Code agent teams on a live board](https://taskhold.com/guides/claude-code-agent-teams-live-board.md)
- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [Task list MCP server for Codex CLI](https://taskhold.com/for/codex.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

---

# Get notified when your coding agent is blocked, and answer from anywhere

> Desktop alerts for Claude Code and Codex when they need input, and a way to answer an agent's blocking question from your phone without its terminal.

Source: https://taskhold.com/guides/answer-a-blocked-coding-agent
Last updated: 2026-10-26

> Short answer: Claude Code's Notification hook and Codex's tui notifications alert you on the machine running the agent. To answer from anywhere, have the agent block the task with a specific question on a shared board, reply there, and let the agent read the reply when it next checks. Taskhold does this with taskhold_block and taskhold_updates.

An agent that stops to ask something and waits in a terminal you aren't looking at costs you the whole wait. The fix has two halves: something that tells you, and somewhere you can answer that isn't that terminal, such as Taskhold's live board, where a blocked task jumps to the top with the agent's question and a reply box. Try it in the [live board demo](https://taskhold.com/demo/live); the [Slack alerts recipe](https://taskhold.com/docs/slack-alerts) and [Claude Code hooks](https://taskhold.com/docs/claude-code-hooks) cover other ways to get told, and [seeing what your agent is doing](https://taskhold.com/guides/monitor-coding-agent-progress) covers the rest of the board.

## Desktop alerts for Claude Code

Claude Code fires a Notification hook when it needs your input. Add a command to ~/.claude/settings.json; on macOS the documented example uses osascript:

```json
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }
        ]
      }
    ]
  }
}
```

On Linux use notify-send 'Claude Code' 'Claude Code needs your attention'. Docs: code.claude.com/docs/en/hooks-guide

If nothing appears on macOS, check that Script Editor is allowed to send notifications: osascript goes through it and fails silently without permission. Claude Code's agent view also notifies through your preferredNotifChannel setting when a background session needs input, finishes or fails.

## Terminal alerts for Codex

Codex has two settings in ~/.codex/config.toml. The [tui] notifications list chooses which events alert you in the terminal, and notify runs a program of your choice when a turn completes:

```toml
notify = ["notify-send", "Codex"]

[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "auto"
```

notify is a top-level key, so it goes above any [table]. Source: the Codex sample config.

## Answering from somewhere other than the terminal

Both alerts point you at a terminal on one machine. When you're away from it, or running agents in several tools, you need the question somewhere you can read and answer, and the agent needs a way to pick the answer up.

1. The agent calls taskhold_block with a specific question, for example "Keep the v1 endpoints alive, or delete them in this PR?"
2. The task moves to the top of Taskhold's live board under Needs you. With notifications on, the open board tab shows a desktop notification.
3. You type the answer and press Reply, or Reply & unblock to send the task back to the queue. On a phone this is the same page.
4. The agent calls taskhold_updates with its cursor between steps or at the start of the next session, reads your reply, and carries on, or takes another task while it waits.

## Questions an agent can act on

A good blocking question names the choice and the default. Put the rule in CLAUDE.md or AGENTS.md: "Can't continue? taskhold_block with a specific question, then check taskhold_updates for the answer."

- Vague: "Need clarification on the auth changes."
- Answerable: "Sessions expire after 24h today. Change to 7 days as the ticket says, or keep 24h for admin users?"
- Answerable: "STRIPE_TEST_KEY isn't set in .env. Add it, or should I mock Stripe in these tests?"

## Limits to know

- Taskhold doesn't wake a sleeping agent. The agent reads your reply the next time it calls taskhold_updates, which the snippet asks for between steps and at session start.
- Board notifications are browser notifications, shown while the live board is open in a tab. Taskhold doesn't send phone push notifications.
- Permission prompts inside Claude Code or Codex still need an answer in that tool. Taskhold carries questions about the work, not tool approvals.

## FAQ

### Can I answer Claude Code's question from my phone without Taskhold?

Yes, for Claude Code: start the session with Remote Control and answer in the Claude app, which can also send push notifications. Taskhold is for questions from any agent, collected on one board.

### What happens to a blocked task if the session ends?

Taskhold keeps it blocked with the question. Your reply waits on the task, and the next session reads it with taskhold_updates or taskhold_get before it picks up work.

### Does the agent sit idle while it waits?

That's up to your instructions. A common rule is to block the task, then take the next todo, so one question doesn't stop the whole queue.

## Sources

- [Claude Code docs: hooks guide (notifications)](https://code.claude.com/docs/en/hooks-guide), checked 2026-10-26
- [Claude Code docs: agent view](https://code.claude.com/docs/en/agent-view), checked 2026-10-26
- [Claude Code docs: Claude Code on mobile](https://code.claude.com/docs/en/mobile), checked 2026-10-26
- [Codex sample config](https://learn.chatgpt.com/docs/config-file/config-sample), checked 2026-10-26

## Related

- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.md)
- [Task list MCP server for Codex CLI](https://taskhold.com/for/codex.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

---

# Why Claude Code's task list is empty, and how to get it back

> Ctrl+T shows nothing on newer Claude models because the task tools are off by default. The environment variable that brings them back, and other causes.

Source: https://taskhold.com/guides/claude-code-task-list-empty
Last updated: 2026-10-26

> Short answer: Since Claude Code v2.1.268 the task tools (TaskCreate, TaskGet, TaskList, TaskUpdate) are on by default only on Opus 4.7, Sonnet 4.6, Haiku 4.5 and earlier models. On newer models Claude adds nothing to the list, so Ctrl+T shows nothing. Start Claude Code with CLAUDE_CODE_ENABLE_TODO_TOOLS=1 to bring the list back.

If Claude used to show a checklist while it worked and now doesn't, nothing is broken. The list is filled by Claude calling task tools, and on newer models Claude Code no longer gives it those tools unless you ask. If you want progress you can see from outside the terminal, Taskhold's live board shows each task's steps as the agent reports them. More in [Claude Code's tasks compared](https://taskhold.com/vs/claude-code-tasks), [Taskhold for Claude Code](https://taskhold.com/for/claude-code) and [seeing what your agent is doing](https://taskhold.com/guides/monitor-coding-agent-progress).

## The fix

Set the variable when you start Claude Code. The docs say this provides the task tools on every model and every provider:

```bash
CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude

# or for every session, in ~/.zshrc or ~/.bashrc
export CLAUDE_CODE_ENABLE_TODO_TOOLS=1
```

Naming one of the tools also turns them on for that session, for example claude --allowedTools TaskCreate, or listing them in --tools. Background sessions started from agent view and cloud sessions get the tools on every model without any setting.

## Why the default changed

Claude Code's tools reference gives the reason: newer models keep track of multi-step work without a written checklist, and the tools' definitions and reminders take up context on every turn. So the list is off where it adds the least, and you can opt back in when you want to see the plan.

## Other reasons the list looks empty

- Claude hasn't made a checklist yet. Ctrl+T toggles the view, and with nothing in the list the toggle has no visible effect.
- The view shows up to five tasks at a time, so a long plan looks shorter than it is.
- You're looking at /tasks. That lists background shells and subagents, not Claude's checklist.
- A model ID Claude Code doesn't recognize, such as a custom name behind an LLM gateway, is treated like a newer model: no tools unless you opt in.
- Sharing a list across sessions with CLAUDE_CODE_TASK_LIST_ID still needs the tools in each session.

## When you want the plan outside the terminal

The built-in list is a good checklist for the session in front of you. It lives in ~/.claude/tasks/ on one machine and in one terminal. If you want to see the plan from a browser or your phone, across Claude Code and other agents, the agent has to report it somewhere shared.

Taskhold is built for that: Claude Code plans each task into steps with taskhold_plan and reports progress with taskhold_progress, and you watch it on a live board, on any model, alongside Codex or Cursor. Both can run at once: the built-in list for Claude's own short checklist, Taskhold for the tasks you queue and follow.

## FAQ

### Does turning the task tools back on cost anything?

The tool definitions and their reminders use some context on every turn, which is the reason they're off by default on newer models. Nothing else changes.

### Is TodoWrite coming back?

TodoWrite is disabled by default in favor of the four Task tools. Where the task tools are available, setting CLAUDE_CODE_ENABLE_TASKS=0 gives you TodoWrite instead.

### Which Claude Code version changed this?

The tools reference says the default set applies in Claude Code v2.1.268 and later. Run claude --version to check yours.

## Sources

- [Claude Code docs: task tool availability](https://code.claude.com/docs/en/tools-reference#task-tool-availability), checked 2026-10-26
- [Claude Code docs: task list](https://code.claude.com/docs/en/interactive-mode#task-list), checked 2026-10-26

## Related

- [Taskhold vs Claude Code's built-in task list](https://taskhold.com/vs/claude-code-tasks.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [Taskhold vs Claude Code agent view](https://taskhold.com/vs/claude-code-agent-view.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

---

# AI coding statistics: adoption, trust and agents

> Sourced AI coding statistics from Stack Overflow, JetBrains, DORA, METR and Anthropic: who uses AI and agents, who trusts it, and what agents write.

Source: https://taskhold.com/guides/ai-coding-statistics
Last updated: 2026-10-26

> Short answer: Most developers now use AI coding tools: 84% use or plan to use them (Stack Overflow 2025), and by mid-2026 90% of professional developers used AI coding agents at work weekly, 68% daily (JetBrains). Trust lags far behind: 46% distrust the accuracy of AI tools and only 33% trust it.

AI coding statistics get quoted a lot and sourced rarely. This page collects the numbers from five public sources that publish their method: the [Stack Overflow 2025 Developer Survey](https://survey.stackoverflow.co/2025/ai), Google's [2025 DORA report](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report), [METR's 2025 study](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) of experienced open-source developers, [Anthropic's analysis](https://www.anthropic.com/research/impact-software-development) of 500,000 coding conversations and JetBrains' [2026 survey of agent use](https://blog.jetbrains.com/research/2026/08/ai-coding-agent-adoption-2026/).

Each number links to the page it came from, with the wording the source uses. Below: how many developers use AI tools, how many trust what they produce, how far agents have spread, whether AI makes developers faster, and what people hand to an agent like Claude Code. The last section is our read of what it means if you run agents yourself.

## How many developers use AI coding tools?

Nearly all of them. 84% of respondents to the Stack Overflow 2025 Developer Survey use or plan to use AI tools in their development process, up from 76% the year before, and 51% of professional developers use them daily. Google's 2025 DORA report, from nearly 5,000 technology professionals, puts AI use at work at 90%.

| Statistic | Source |
| --- | --- |
| 84% of developers use or plan to use AI tools in their development process (76% a year earlier) | [Stack Overflow Developer Survey 2025](https://survey.stackoverflow.co/2025/ai) |
| 51% of professional developers use AI tools daily | [Stack Overflow Developer Survey 2025](https://survey.stackoverflow.co/2025/ai) |
| 90% of survey respondents report using AI at work | [DORA 2025, Google Cloud](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report) |
| More than 80% believe AI has increased their productivity | [DORA 2025, Google Cloud](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report) |

## How many developers trust AI-generated code?

Far fewer than use it. In the Stack Overflow 2025 survey, more developers actively distrust the accuracy of AI tools (46%) than trust it (33%), and 3% say they highly trust the output. In DORA 2025, 30% report little or no trust in AI-generated code. Use is high and trust is not, so people check the work.

| Statistic | Source |
| --- | --- |
| 46% actively distrust the accuracy of AI tools; 33% trust it | [Stack Overflow Developer Survey 2025](https://survey.stackoverflow.co/2025/ai) |
| 3% report highly trusting AI output | [Stack Overflow Developer Survey 2025](https://survey.stackoverflow.co/2025/ai) |
| 66% name "AI solutions that are almost right, but not quite" as their biggest frustration | [Stack Overflow Developer Survey 2025](https://survey.stackoverflow.co/2025/ai) |
| 30% report little or no trust in the code AI generates | [DORA 2025, Google Cloud](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report) |

## How many developers use AI agents?

Most professional developers, as of mid-2026. JetBrains' Developer Ecosystem Survey 2026 (May to July, more than 15,000 professional developers) found 90% using AI coding agents at work at least weekly and 68% daily. A year earlier, Stack Overflow's 2025 survey said agents were not yet mainstream, with 52% not using them.

| Statistic | Source |
| --- | --- |
| 90% of professional developers used AI coding agents at work at least weekly, 68% daily (May to July 2026) | [JetBrains Research, August 2026](https://blog.jetbrains.com/research/2026/08/ai-coding-agent-adoption-2026/) |
| 39% of professional developers used Claude Code at work, up from 18% in January 2026 (47% in the US) | [JetBrains Research, August 2026](https://blog.jetbrains.com/research/2026/08/ai-coding-agent-adoption-2026/) |
| Codex adoption went from 3% in January 2026 to 16% in May to July 2026 | [JetBrains Research, August 2026](https://blog.jetbrains.com/research/2026/08/ai-coding-agent-adoption-2026/) |
| On average about 47% of developers' code is fully written by agents; 22% have agents write over 80% | [JetBrains Research, August 2026](https://blog.jetbrains.com/research/2026/08/how-much-code-do-developers-really-let-agents-write/) |
| In 2025, 52% didn't use AI agents or stuck to simpler AI tools, and 38% had no plans to adopt them | [Stack Overflow Developer Survey 2025](https://survey.stackoverflow.co/2025/ai) |
| 52% agree AI tools and/or agents have had a positive effect on their productivity | [Stack Overflow Developer Survey 2025](https://survey.stackoverflow.co/2025/ai) |

The two surveys ask different questions of different samples a year apart, so read the change as direction, not an exact growth rate.

## Do AI tools make developers faster?

It depends on who you ask and how you measure. In METR's randomized study, 16 experienced open-source developers working on 246 real issues in their own repositories took 19% longer with AI tools allowed. They expected a 24% speedup beforehand and still believed afterwards that AI had sped them up by 20%.

| Statistic | Source |
| --- | --- |
| Developers took 19% longer to complete issues when AI tools were allowed | [METR, July 2025](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) |
| Before the study they expected a 24% speedup; afterwards they believed they had been 20% faster | [METR, July 2025](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) |
| Sample: 16 experienced developers, 246 issues from large open-source repositories | [METR, July 2025](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) |
| More than 80% of DORA respondents believe AI increased their productivity | [DORA 2025, Google Cloud](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report) |

METR says its 16-developer sample does not let the result generalize to every developer or setting; it measures one group of experienced maintainers on their own codebases in early 2025.

## What do developers hand to an agent like Claude Code?

More of the whole task. Anthropic's analysis of 500,000 coding interactions found 79% of Claude Code conversations were automation, where the AI performs the task directly, against 49% on Claude.ai. Feedback loops, where Claude works on its own and the person sends errors back, made up 35.8% of Claude Code interactions.

| Statistic | Source |
| --- | --- |
| 79% of Claude Code conversations were automation, 21% augmentation | [Anthropic, April 2025](https://www.anthropic.com/research/impact-software-development) |
| 49% of Claude.ai coding conversations were automation | [Anthropic, April 2025](https://www.anthropic.com/research/impact-software-development) |
| Feedback loops: 35.8% of Claude Code interactions vs 21.3% on Claude.ai | [Anthropic, April 2025](https://www.anthropic.com/research/impact-software-development) |
| Directive (task done with minimal interaction): 43.8% on Claude Code vs 27.5% on Claude.ai | [Anthropic, April 2025](https://www.anthropic.com/research/impact-software-development) |
| Startup work was 32.9% of Claude Code conversations; enterprise work 23.8% | [Anthropic, April 2025](https://www.anthropic.com/research/impact-software-development) |

## What these numbers mean if you run coding agents

Put the sources side by side and one pattern stands out: people hand agents whole tasks (79% automation on Claude Code, about 47% of code fully agent-written in 2026) while most don't fully trust the output (46% distrust) and can misjudge their own speed (METR's 19% slower, felt as 20% faster). That is our reading, not a finding of any one study.

- Plan and progress you can see: an agent that writes its plan as steps and reports which step it is on gives you something to check other than the final diff. See [how to see what your coding agent is doing](https://taskhold.com/guides/monitor-coding-agent-progress).
- Questions answered quickly: 66% of developers are frustrated by answers that are almost right. An agent that stops and asks one specific question is cheaper than one that guesses. See [answering a blocked coding agent](https://taskhold.com/guides/answer-a-blocked-coding-agent).
- A review step after the run: a summary per finished task and a list of what the agent filed. See [reviewing what your agent did](https://taskhold.com/guides/review-what-your-agent-did).
- Measure your own speed: METR's gap between felt and measured speed is a reason to time a few tasks with and without an agent before deciding.

Taskhold is a task list built around the first three: agents plan, report progress and ask questions over MCP, and you watch and answer on one [live board](https://taskhold.com/demo/live). The [agent visibility check](https://taskhold.com/tools/agent-visibility-check) is a two-minute way to see which of these you already have.

## FAQ

### What percentage of developers use AI coding tools?

84% use or plan to use AI tools in development and 51% of professional developers use them daily, per the Stack Overflow 2025 Developer Survey. Google's 2025 DORA report puts AI use at work at 90%.

### Do developers trust AI-generated code?

Mostly not fully. In the Stack Overflow 2025 survey 46% distrust the accuracy of AI tools and 33% trust it; only 3% highly trust the output. In DORA 2025, 30% report little or no trust in AI-generated code.

### How many developers use AI coding agents?

By May to July 2026, 90% of professional developers used AI coding agents at work at least weekly and 68% daily, per JetBrains' Developer Ecosystem Survey 2026. About 39% used Claude Code at work.

### Does AI make developers slower?

In one setting, yes: METR's 2025 randomized study found 16 experienced open-source developers took 19% longer with AI tools on 246 issues in their own repositories, while believing they were 20% faster. METR notes the result may not generalize.

### Can I use these statistics?

Yes. Cite and link the original source for each number (linked in every row), and link this page if the collection saved you time. We recheck the sources when new editions come out.

## Sources

- [Stack Overflow Developer Survey 2025: AI](https://survey.stackoverflow.co/2025/ai), checked 2026-10-26
- [Google Cloud: Announcing the 2025 DORA report](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report), checked 2026-10-26
- [METR: Measuring the impact of early-2025 AI on experienced open-source developer productivity](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/), checked 2026-10-26
- [Anthropic: AI's impact on software development](https://www.anthropic.com/research/impact-software-development), checked 2026-10-26
- [JetBrains Research: AI coding agent adoption in 2026](https://blog.jetbrains.com/research/2026/08/ai-coding-agent-adoption-2026/), checked 2026-10-26
- [JetBrains Research: How much code do developers really let agents write?](https://blog.jetbrains.com/research/2026/08/how-much-code-do-developers-really-let-agents-write/), checked 2026-10-26

## Related

- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [What your coding agent did while you were away](https://taskhold.com/guides/review-what-your-agent-did.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Taskhold vs Claude Code's built-in task list

> Claude Code's own task list is free and built in. When it is enough, and when a hosted list shared with Cursor, Codex and your phone is worth $12 a month.

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

> Short answer: Claude Code's built-in task list is free, stored in ~/.claude/tasks/ and shows up to five tasks with Ctrl+T, but only for Claude Code on one machine. Taskhold is a hosted list at $12 a month that Claude Code, Cursor, Codex and other MCP agents share, with a live board of each task's steps you can check from a phone.

Claude Code has its own task tools. Tasks persist across context compactions, and setting CLAUDE_CODE_TASK_LIST_ID lets several sessions share one list stored under ~/.claude/tasks/. It's free and needs no setup on the models that have it. For many people that is enough, and you should use it.

Taskhold is for the cases it doesn't cover: other agents, other machines, and a person who wants to add and review tasks, and watch progress on a live board, without a terminal. If your list shows nothing at all, [why the Claude Code task list is empty](https://taskhold.com/guides/claude-code-task-list-empty) has the fix. Taskhold's own [setup for Claude Code](https://taskhold.com/for/claude-code) is one command, and [agent view](https://taskhold.com/vs/claude-code-agent-view) is compared separately.

## Side by side

|  | Claude Code tasks | Taskhold |
| --- | --- | --- |
| Price | Included with Claude Code | $12/month or $120/year per person, 7-day trial |
| Where tasks live | Local files in ~/.claude/tasks/ | Hosted list, reachable from any machine |
| Agents | Claude Code | Claude Code, Cursor, Codex, Windsurf, any MCP client with remote server support |
| How you see it | Ctrl+T in the terminal, up to five tasks at a time | Web app on desktop or phone, plus Agent Activity |
| Progress while it works | Pending, in progress or done per item; agent view (claude agents, research preview) shows each background session's state | Live board: a bar split by step, percent or N of M, the agent's current message, time elapsed and an estimate |
| When the agent needs you | Needs input state in agent view; push notifications through Remote Control | The question sits under Needs you on the board; reply, or reply and unblock, and the agent reads it with taskhold_updates |
| Sharing between sessions | Yes, with CLAUDE_CODE_TASK_LIST_ID on one machine | Yes, every session and every agent you connect |
| History | Not listed in the docs | Every change kept, marked human or agent |
| Dependencies between tasks | Yes | No |
| Models | On by default for Opus 4.7, Sonnet 4.6, Haiku 4.5 and earlier; newer models need CLAUDE_CODE_ENABLE_TODO_TOOLS=1 | Any model, any client |
| Setup | None on those models | Paste one setup URL into the agent |

Claude Code facts from code.claude.com docs (interactive mode, tools reference, agent view, mobile), checked 2026-10-26.

## When are Claude Code's tasks the better choice?

- You only use Claude Code, on one machine.
- You don't need to add or read tasks away from the terminal.
- You want task dependencies and zero setup.

One thing to know: since Claude Code v2.1.268 the task tools are on by default only on Opus 4.7, Sonnet 4.6, Haiku 4.5 and earlier models. On newer models Claude keeps track of multi-step work without a written list, so Ctrl+T shows nothing unless you start Claude Code with CLAUDE_CODE_ENABLE_TODO_TOOLS=1. Background sessions and cloud sessions get the tools on every model.

## When is Taskhold the better choice?

- You run Claude Code next to Cursor, Codex or Windsurf and want one list for all of them.
- You work from more than one machine, or want to queue tasks from your phone.
- You want a record of what each task went through, with agent changes marked as agent changes.
- You want blocked tasks, with the agent's question, collected in one place you can answer from.
- You want to watch a long task's steps fill in from a phone or another room, whatever model you run.

## Using both

Claude Code's task list and Taskhold don't conflict. Claude Code can keep its own short checklist for the steps of a task while Taskhold holds the backlog: start a Taskhold task, plan the steps with the built-in tools, complete the Taskhold task with a summary.

## Moving tasks over

There's no importer. Claude Code keeps its task list in ~/.claude/tasks/ on your machine, and the session that made it can read it. With Taskhold connected, ask that session to create each open item with taskhold_create and leave the finished ones where they are.

## FAQ

### Is TodoWrite the same thing?

TodoWrite was the earlier checklist tool. The docs list it as disabled by default in favor of TaskCreate, TaskGet, TaskList and TaskUpdate; setting CLAUDE_CODE_ENABLE_TASKS=0 brings it back in sessions that have the task tools.

### Why is my Claude Code task list empty?

On models newer than Opus 4.7, Sonnet 4.6 and Haiku 4.5, Claude Code leaves the task tools out, so nothing is added to the list. Start Claude Code with CLAUDE_CODE_ENABLE_TODO_TOOLS=1 to get them back. The guide on the empty task list covers the other cases.

### Does Taskhold replace CLAUDE.md?

No. CLAUDE.md tells the agent how to use the list; Taskhold holds the list.

## Sources

- [Claude Code docs: task list (interactive mode)](https://code.claude.com/docs/en/interactive-mode#task-list), 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: Claude Code on mobile](https://code.claude.com/docs/en/mobile), checked 2026-10-26

## Related

- [Claude Code task list empty? Why, and the fix](https://taskhold.com/guides/claude-code-task-list-empty.md)
- [Taskhold vs Claude Code agent view](https://taskhold.com/vs/claude-code-agent-view.md)
- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Looking for a Vibe Kanban alternative?

> Vibe Kanban is sunsetting and its hosted features were removed. What it still does well, what Taskhold covers instead, and what it doesn't.

Source: https://taskhold.com/vs/vibe-kanban
Last updated: 2026-10-26

> Short answer: Vibe Kanban is sunsetting: its company shut down in April 2026 and the free local app continues as a community project without its hosted features. It ran agents in parallel workspaces and showed a board of them. Taskhold replaces the board only: a hosted list your existing agents work from, with a live board of their progress, at $12 a month.

Bloop announced on April 10, 2026 that it was shutting down and that Vibe Kanban would continue as a community-maintained open-source project. The remote features (hosted issues, comments, projects and organisations) were removed; the local app still runs with npx vibe-kanban.

Vibe Kanban did two jobs: it ran agents in parallel workspaces, and it gave you a board of what they were working on. Taskhold covers the second job only: a list your agents work from and a live board of their progress. For the first job, see [running several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list); for a wider look, the [roundup of agent task managers](https://taskhold.com/vs/ai-coding-agent-task-managers); and to see the board without an account, the [live board demo](https://taskhold.com/demo/live).

## What changes if you move

|  | Vibe Kanban (now) | Taskhold |
| --- | --- | --- |
| Status | Community-maintained open source, company shut down | Run by Great Work LLC, paid product |
| Price | Free (Apache-2.0) | $12/month or $120/year per person, 7-day trial |
| Where it runs | Local app | Hosted; nothing to keep running |
| Runs agents, worktrees, diffs | Yes | No |
| Board of tasks you add | Yes, local | Yes, web app on any device |
| Agents | 10+ agents it launches | Any MCP client you already use |
| Watching agents work | Per-agent workspace with a terminal, diff review and app preview | Live board: steps, progress bar, current message and time per task; no terminals or diffs |
| Agent asks you something | Inline review comments sent back to the agent | Blocked question on the board; reply, or reply and unblock |
| History, human vs agent | Not listed in the README | Every change, with the agent's name |

Vibe Kanban facts from its README (which opens with "Vibe Kanban is sunsetting") and the shutdown post, checked 2026-10-26.

## When is Vibe Kanban the better choice?

You relied on it to launch agents in isolated worktrees and review their diffs. Taskhold doesn't do that. Keep running the local app, or look at another agent runner.

## When is Taskhold the better choice?

What you miss is the shared board: a place where you queue work, agents pick it up through MCP, and you can see what's in progress, blocked or done from any device without your laptop running a server. Agents break each task into steps and report progress, so the board shows how far along each one is, not only which column it's in. You keep launching agents however you already do; each one connects to the same list.

## Moving tasks over

There's no importer. With few tasks, add them in the web app. With many, ask an agent connected to both to read them and create each one with taskhold_create.

## FAQ

### Can I run Vibe Kanban and Taskhold together?

Yes. Agents launched by Vibe Kanban can use Taskhold's MCP server like any other client.

## Sources

- [Vibe Kanban README](https://github.com/BloopAI/vibe-kanban), checked 2026-10-26

## Related

- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Taskhold vs Backlog.md for AI coding agents](https://taskhold.com/vs/backlog-md.md)
- [What your coding agent did while you were away](https://taskhold.com/guides/review-what-your-agent-did.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Taskhold vs Taskmaster AI

> Taskmaster AI breaks a PRD into dependent tasks inside your repo, for free. Taskhold is a hosted list you and your agents share. Which fits which workflow.

Source: https://taskhold.com/vs/taskmaster-ai
Last updated: 2026-10-26

> Short answer: Taskmaster AI is a free CLI and MCP server that turns a product requirements document into dependent tasks stored in the repo, with 36 tools by default. Taskhold doesn't plan from a PRD. It is a hosted list at $12 a month where agents split your tasks into steps and report progress to a live board you can watch from any device.

Taskmaster AI (claude-task-master) is a free, widely used CLI and MCP server. It parses a product requirements document into tasks with dependencies and complexity estimates, stored in a .taskmaster/ folder in the project. Its hosted companion, Hamster, adds team sync on paid plans.

Taskhold doesn't plan for you. It's a hosted list where you write tasks and agents work through them, report progress to a live board, and file new ones. To turn a spec into tasks by hand or with your agent, see [break a spec into agent tasks](https://taskhold.com/guides/break-a-spec-into-agent-tasks); agents split each task into steps with taskhold_plan, described in [how live progress works](https://taskhold.com/docs/live-progress); and the [roundup](https://taskhold.com/vs/ai-coding-agent-task-managers) puts both next to other options.

## Side by side

|  | Taskmaster AI | Taskhold |
| --- | --- | --- |
| Price | CLI free; Hamster Team $40 per creator/month | $12/month or $120/year per person |
| Where tasks live | Project folder (.taskmaster/), optional Hamster cloud | Hosted list |
| Turns a PRD into tasks | Yes, with dependencies | No |
| Human view | CLI; browser views via Hamster | Web app on any device |
| Across repos | Per project | One list, grouped by project |
| Human vs agent history | Not listed in the README | Every change |
| Setup | claude mcp add ... npx task-master-ai, plus model API keys for AI commands | Paste a setup URL; no model keys |
| Progress view for you | Task status in the CLI; a live view is not described in the README | Live board with a bar split by step, the agent's current message and an estimate |
| Agent asks you something | Not described in the README | Blocked question on the board; the reply reaches the agent through taskhold_updates |
| Tool count | 36 tools by default (about 21,000 tokens); a 7-tool core mode exists | 19 tools |
| Last code change on GitHub | Checked 2026-10-26: last push 2026-04-28 | Changelog updated 2026-10-26 |

Taskmaster facts from its GitHub README and tryhamster.com pricing, checked 2026-10-26.

## When is Taskmaster the better choice?

- You start projects from a PRD and want the agent to break it into dependent tasks.
- You want everything in the repo and free.
- You're one repo at a time.

## When is Taskhold the better choice?

- You write tasks yourself, as they come up, across several repos.
- You want to add and review tasks from a browser or phone, and watch an agent's steps fill in while it works.
- You want blocked tasks and agent summaries in one place, with agent changes marked as such.
- You don't want to manage model API keys for the task tool.

## Moving tasks over

There's no importer. Taskmaster keeps its tasks in .taskmaster/ in the repo. Ask an agent connected to Taskhold to read them and create each pending task with taskhold_create; when it starts one, its subtasks become the steps of a taskhold_plan. Dependencies don't carry over, so set priorities to get the order you want.

## FAQ

### Can I use both?

Yes. Some people plan with Taskmaster inside a repo and keep the cross-project backlog in Taskhold.

## Sources

- [Taskmaster README](https://github.com/eyaltoledano/claude-task-master), checked 2026-10-26
- [Hamster pricing](https://tryhamster.com/pricing), checked 2026-10-26

## Related

- [Taskhold vs Backlog.md for AI coding agents](https://taskhold.com/vs/backlog-md.md)
- [Taskhold vs Claude Code's built-in task list](https://taskhold.com/vs/claude-code-tasks.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Taskhold vs Backlog.md

> Backlog.md keeps tasks as markdown files in your git repo, free and offline. Taskhold is a hosted list across repos. A fair look at when each one wins.

Source: https://taskhold.com/vs/backlog-md
Last updated: 2026-10-26

> Short answer: Backlog.md is a free, MIT-licensed task manager that keeps each task as a markdown file in the repo, with a terminal board, a local web UI and an MCP server. Pick it to version tasks with your code. Taskhold is a hosted list across repos at $12 a month, with a live board of each agent's steps that works from a phone.

Backlog.md is a free, MIT-licensed task manager where every task is a markdown file in the repo, with a terminal board, a local web UI and an MCP server. It's actively maintained and it's good. If you want tasks versioned with your code, use it. Taskhold is a hosted list across repos with a live board of each agent's progress, closer to [one task list across all your repos](https://taskhold.com/guides/one-task-list-across-repos). A [TODO.md file](https://taskhold.com/vs/todo-md) is the even simpler option, and the [roundup](https://taskhold.com/vs/ai-coding-agent-task-managers) compares them all.

## Side by side

|  | Backlog.md | Taskhold |
| --- | --- | --- |
| Price | Free (MIT) | $12/month or $120/year per person |
| Where tasks live | Markdown files in the repo, versioned with git | Hosted list |
| Human view | Terminal board and local web UI with real-time updates, bound to 127.0.0.1 | Web app on any device, including a phone |
| Agent progress inside a task | Task status and acceptance criteria checkboxes | Steps with a progress bar, percent or N of M, and the agent's current message |
| Agent asks you something | Not described in the README | Blocked question on the live board with a reply box |
| Across repos | One backlog per repo (one MCP server can serve them all) | One list, grouped by project |
| Offline | Yes | No |
| History | Git history, comment authors | Every change, marked human or agent |
| Acceptance criteria, milestones, dependencies | Yes | No (description and priority only) |
| Setup | Install the CLI, backlog init per repo | Paste a setup URL |
| Run your own code when a task changes | Not described in the README | Server-sent event stream and REST API; the docs include a Slack alert recipe |

Backlog.md facts from its GitHub README, checked 2026-10-26.

## When is Backlog.md the better choice?

- You want tasks in git next to the code they describe.
- You work offline or don't want a third party holding task data.
- You want acceptance criteria and dependencies.

## When is Taskhold the better choice?

- Your tasks span several repos, or aren't tied to a repo.
- You want to queue and review work from a phone or another machine without running a local server.
- You don't want task files committed alongside code.

## Moving tasks over

There's no importer. Each Backlog.md task is a markdown file in the repo, so an agent connected to Taskhold can read the files and create each open task with taskhold_create, copying the acceptance criteria into the description. The files stay in git if you want the history.

## FAQ

### Can I import my Backlog.md tasks?

There's no importer. An agent connected to Taskhold can read the markdown files and create each task with taskhold_create.

## Sources

- [Backlog.md README](https://github.com/MrLesk/Backlog.md), checked 2026-10-26
- [Taskhold events stream docs](https://taskhold.com/docs/events), checked 2026-10-26

## Related

- [Taskhold vs Taskmaster AI for coding agents](https://taskhold.com/vs/taskmaster-ai.md)
- [Taskhold vs GitHub Issues as an agent task board](https://taskhold.com/vs/github-issues.md)
- [A shared todo list for Claude Code and Cursor](https://taskhold.com/guides/shared-todo-list-for-claude-code-and-cursor.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Taskhold vs Linear (with Linear's MCP server)

> Linear's MCP server puts agents into a team's issue tracker. Taskhold is a lighter list for one developer and their agents. Prices, setup and fit compared.

Source: https://taskhold.com/vs/linear
Last updated: 2026-10-26

> Short answer: Linear is a team issue tracker with a hosted MCP server, a free tier of 250 issues and an agent API for apps built on it. If your team plans in Linear, connect your agents there. Taskhold is one developer's own queue of agent work at $12 a month, where any MCP client reports steps and progress to a live board.

Linear is a mature team issue tracker with a hosted MCP server, a free tier, mobile apps, and an agent platform where agents act as separate app users. If your team already plans in Linear, connecting your agents to it is the natural choice.

Taskhold is for one developer's own queue of agent work, which often doesn't belong in the team tracker, with a live board of each agent's progress. If issues next to your code suit you better, [GitHub Issues](https://taskhold.com/vs/github-issues) is compared too; see [handing tasks to your agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent) for the solo workflow and the [roundup](https://taskhold.com/vs/ai-coding-agent-task-managers) for the full field.

## Side by side

|  | Linear + MCP | Taskhold |
| --- | --- | --- |
| Price | Free (250 issues, 2 teams); Basic $10/user/month and Business $16/user/month, billed yearly | $12/month or $120/year per person |
| Built for | Teams: cycles, projects, assignment, permissions | One person and their agents |
| MCP | Hosted, OAuth or API key, per client | Hosted, one setup URL per client |
| Agent identity | Agents from its directory are separate app users | Every change marked human or agent |
| Live progress | Agents built on Linear's agent API post activities to an agent session and can keep a step checklist (the plan API is a technology preview). An MCP client editing issues works through issues and comments. | Any MCP client plans steps and reports progress; the live board shows a bar split by step, the current message and an estimate |
| Agent asks you something | Agent API has an elicitation activity; you reply in the session | Blocked question at the top of the live board; reply, or reply and unblock |
| Mobile | Native apps | Web app, including the live board |

Linear facts from linear.app/pricing, linear.app/docs/mcp and linear.app/developers/agent-interaction, checked 2026-10-26.

## When is Linear the better choice?

- Your team plans there and agent work should be visible to the team.
- You need assignment, cycles and permissions.
- You want a free tier.

## When is Taskhold the better choice?

- The tasks are yours: side projects, chores for your agents, things that would clutter the team tracker.
- You want a short setup and a view centered on what agents are doing and where they're stuck.

## Moving tasks over

There's no importer. With Linear's MCP server and Taskhold both connected, ask the agent to list the open issues assigned to you and create each one with taskhold_create, keeping the issue link in the description. Team issues can stay in Linear; move only the work that is yours.

## FAQ

### Does Taskhold have team workspaces?

Not yet. Each person subscribes and has their own list.

## Sources

- [Linear pricing](https://linear.app/pricing), checked 2026-10-26
- [Linear MCP docs](https://linear.app/docs/mcp), checked 2026-10-26
- [Linear agent interaction docs](https://linear.app/developers/agent-interaction), checked 2026-10-26

## Related

- [Taskhold vs GitHub Issues as an agent task board](https://taskhold.com/vs/github-issues.md)
- [What your coding agent did while you were away](https://taskhold.com/guides/review-what-your-agent-did.md)
- [Task list MCP server for Cursor](https://taskhold.com/for/cursor.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Taskhold vs GitHub Issues for agent tasks

> GitHub Issues with the GitHub MCP server is free and sits next to your code. When it makes a good agent board, and when a separate list fits better.

Source: https://taskhold.com/vs/github-issues
Last updated: 2026-10-26

> Short answer: GitHub Issues are free, live next to your code and link to pull requests, and GitHub's MCP server lets agents open, update and close them. Progress inside an issue is checkboxes by convention. Taskhold is a separate list across repos at $12 a month, where agents report steps and progress to a live board and every change is marked human or agent.

GitHub's official MCP server lets agents create, update and close issues, hosted by GitHub or run locally. Issues are free, linked to commits and pull requests, and already where your code lives. Plenty of developers use labels for state and one issue per feature as their agent board. Taskhold is a separate list with a live board of each agent's step-by-step progress. [Linear](https://taskhold.com/vs/linear) is the other tracker people connect agents to, [turning code TODOs into tasks](https://taskhold.com/guides/turn-code-todos-into-tasks) shows how agents file work, and the [roundup](https://taskhold.com/vs/ai-coding-agent-task-managers) covers the rest.

## Side by side

|  | GitHub Issues + MCP | Taskhold |
| --- | --- | --- |
| Price | Free; Team $4/user/month (the pricing page shows this for the first 12 months) | $12/month or $120/year per person |
| Scope | Per repo (Projects can span repos) | One list, grouped by project |
| Task states | Open/closed plus labels by convention | todo, in progress, blocked (with reason), done |
| Who made a change | The account the token belongs to | Marked human or agent |
| Access the agent needs | OAuth or a personal access token for GitHub | A key that can only touch your task list |
| Progress inside a task | Task-list checkboxes in the issue body or comments, by convention | Steps with a bar, percent or N of M and the agent's current message, updating live |
| Links to PRs and commits | Yes | No |

GitHub facts from github.com/github/github-mcp-server (checked 2026-10-08) and github.com/pricing (checked 2026-10-26).

## When is GitHub Issues the better choice?

- Tasks belong to one repo and should link to PRs.
- Others on the repo should see them.
- You want it free.

## When is Taskhold the better choice?

- The tasks are personal, span repos, or aren't code.
- You'd rather not give agents a GitHub token to manage their to-do list.
- You want explicit started, blocked and done states with notes, and agent changes marked as agent changes.

## Moving tasks over

There's no importer. gh issue list --assignee @me --json number,title,body,url prints your open issues as JSON. Give that to an agent connected to Taskhold and ask it to create each one with taskhold_create, with the issue URL in the description so the link back survives.

## FAQ

### Can an agent move a Taskhold task to a GitHub issue?

If it has both MCP servers, yes: it can read the task and create the issue. There's no built-in sync.

## Sources

- [GitHub MCP server](https://github.com/github/github-mcp-server), checked 2026-10-26
- [GitHub pricing](https://github.com/pricing), checked 2026-10-26

## Related

- [Taskhold vs Linear MCP for personal agent tasks](https://taskhold.com/vs/linear.md)
- [Taskhold vs Backlog.md for AI coding agents](https://taskhold.com/vs/backlog-md.md)
- [Turn TODO comments into tasks your agent can do](https://taskhold.com/guides/turn-code-todos-into-tasks.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Taskhold vs a TODO.md file

> A TODO.md in the repo is free, versioned and readable by any agent. When it is enough, and when a hosted list shared with your agents is worth $12 a month.

Source: https://taskhold.com/vs/todo-md
Last updated: 2026-10-26

> Short answer: A TODO.md file is free, versioned in git and readable by any agent, and for one repo and one agent it is often enough. It gets hard with two agents editing at once or when you want to check progress from your phone. Taskhold is a hosted list at $12 a month with a live board of each agent's steps.

Most people start by asking their agent to keep a TODO.md or a checklist in CLAUDE.md. That costs nothing, lives in git next to the code, and any agent can read and edit it. For one repo and one agent at a time, a TODO.md is often enough. Taskhold adds what a file can't: a live board of each agent's progress, and a list across repos. See [one task list across repos](https://taskhold.com/guides/one-task-list-across-repos), [Backlog.md](https://taskhold.com/vs/backlog-md) for a richer in-repo option, and [Claude Code's built-in tasks](https://taskhold.com/vs/claude-code-tasks).

## Side by side

|  | TODO.md in the repo | Taskhold |
| --- | --- | --- |
| Price | Free | $12/month or $120/year per person |
| Where tasks live | One file per repo, in git | One hosted list, grouped by project |
| Editing from your phone | Only through a git client | Web app in any browser |
| Two agents at once | Both edit the same file; merge conflicts and duplicate work are on you | A started task shows as in progress, so the next agent takes another |
| Who changed what | git blame, if each change is committed | Every change marked human or agent, with history |
| Blocked work | A line in the file, by convention | Blocked status with the agent's question, at the top of the live board with a reply box |
| Progress while it works | Whatever the agent writes into the file; you see it when you open it | Steps and a progress bar that update live, with the agent's current message |
| Works offline | Yes | No |

Checked 2026-10-26.

## When is the TODO.md the better choice?

- You work in one repo with one agent at a time.
- You want tasks versioned with the code and reviewed in pull requests.
- You need it free or offline.

## When is Taskhold the better choice?

- Several agents or several repos share one backlog.
- You want to add or reorder tasks from your phone while agents run.
- You want to see which tasks an agent started, blocked or finished without reading diffs of a markdown file.

## Moving a TODO.md into Taskhold

Connect your agent, then ask it to read TODO.md and file each open item with taskhold_create, keeping priorities. Delete the file or leave a line pointing to Taskhold so the next session doesn't work from both.

## FAQ

### Can I use both?

Yes. Some people keep a short TODO.md for the current branch and use Taskhold for the backlog across repos. Tell the agent in CLAUDE.md or AGENTS.md which one is the source of truth.

### Does Taskhold read my TODO.md automatically?

No. Taskhold never reads your repository. An agent can copy items over with taskhold_create when you ask it to.

## Related

- [Taskhold vs Claude Code's built-in task list](https://taskhold.com/vs/claude-code-tasks.md)
- [Taskhold vs Backlog.md for AI coding agents](https://taskhold.com/vs/backlog-md.md)
- [One task list for coding agents across repos](https://taskhold.com/guides/one-task-list-across-repos.md)
- [Taskhold vs Todoist MCP for coding agent tasks](https://taskhold.com/vs/todoist.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Taskhold vs Todoist (with Todoist's MCP server)

> Todoist has an official hosted MCP server and a free plan. When Todoist is the right list for your agents, and when a list built for coding agents fits.

Source: https://taskhold.com/vs/todoist
Last updated: 2026-10-26

> Short answer: Todoist is a personal task manager with a free Beginner plan, native apps and an official MCP server that signs in with OAuth. Use it to keep agent to-dos next to the rest of your life. Taskhold is narrower, at $12 a month: a list for work handed to coding agents, with blocked states, a file and line per task, and a live board of their progress.

Todoist is a mature personal task manager with apps on every platform, a free Beginner plan, and an official MCP server from Doist at ai.todoist.net/mcp that signs in with OAuth. If your life already runs in Todoist, letting Claude Code add and complete Todoist tasks keeps everything in one place.

Taskhold is narrower: a list for work you hand to coding agents, with states, records and a live board of their progress built for that. See [handing tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent), [Linear](https://taskhold.com/vs/linear) for the team-tracker option, and the [roundup](https://taskhold.com/vs/ai-coding-agent-task-managers) for everything else.

## Side by side

|  | Todoist + MCP | Taskhold |
| --- | --- | --- |
| Price | Free Beginner plan (5 personal projects); paid Pro and Business plans | $12/month or $120/year per person, no free plan |
| Built for | Personal and team to-dos of every kind | Work handed to coding agents |
| MCP | Official hosted server, OAuth sign-in | Hosted server, API key via a setup URL |
| Task states | Open or completed, plus sections and labels | todo, in progress, blocked (with reason), done |
| Who made a change | Your account | Marked human or agent, with history |
| Code context | None built in | Tasks can carry a file path and line number |
| Agent progress | Sub-tasks you can tick; progress reporting or agent status is not described in the MCP README | Steps, percent or N of M and a current message, on a live board |
| Apps | Native apps on phone, desktop, watch | Web app |

Todoist facts from todoist.com/pricing (checked 2026-10-09) and github.com/Doist/todoist-ai (checked 2026-10-26).

## When is Todoist the better choice?

- You want one list for your whole life, with agent tasks mixed in.
- You want native apps, reminders and a free plan.
- Your agents only need to add and tick off simple to-dos.

## When is Taskhold the better choice?

- You want agent work kept apart from groceries and errands.
- You want started, blocked and done states with notes, so you see where each agent stopped.
- You run several agents and need to know which one did what.

## Moving tasks over

There's no importer. With Todoist's MCP server and Taskhold both connected, ask the agent to read the Todoist project that holds your agent to-dos and file each open item with taskhold_create. Errands can stay in Todoist.

## FAQ

### Can an agent use Todoist and Taskhold together?

Yes, if both MCP servers are connected. The agent can read a Todoist item and file it as a Taskhold task, or the other way round. There is no built-in sync between the two.

## Sources

- [Todoist pricing](https://www.todoist.com/pricing), checked 2026-10-26
- [Doist todoist-ai (MCP)](https://github.com/Doist/todoist-ai), checked 2026-10-26

## Related

- [Taskhold vs Linear MCP for personal agent tasks](https://taskhold.com/vs/linear.md)
- [Taskhold vs a TODO.md file for coding agents](https://taskhold.com/vs/todo-md.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Taskhold vs Claude Code's agent view

> Agent view lists your background Claude Code sessions and which need you. How it differs from a task-level live board shared by every agent you run.

Source: https://taskhold.com/vs/claude-code-agent-view
Last updated: 2026-10-26

> Short answer: Use agent view if you run several Claude Code sessions on one machine: it is free, built in, and shows which session needs you. Taskhold covers tasks rather than sessions: steps and progress the agent reports, from Claude Code and other MCP clients, on a board you can open on any device. Many people will want both.

Agent view (claude agents) is Claude Code's screen for dispatching and watching background sessions. Each row is a session with a state, working, needs input, completed or failed, and a one-line summary a small model writes. You can peek at a waiting session and reply without leaving the screen. It is a research preview.

Taskhold's live board looks similar at a glance and answers a different question: how far each task has got, and what the agent is asking you. Try it in the [live board demo](https://taskhold.com/demo/live), read [how to see what your agent is doing](https://taskhold.com/guides/monitor-coding-agent-progress), or compare [Claude Code's built-in tasks](https://taskhold.com/vs/claude-code-tasks).

## Side by side

|  | Claude Code agent view | Taskhold live board |
| --- | --- | --- |
| Price | Included with Claude Code | $12/month or $120/year per person, 7-day trial |
| Unit | A session | A task, with steps |
| Agents | Claude Code background sessions on this machine | Any MCP client: Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini CLI |
| Where you look | The terminal on that machine | A browser on any device, including a phone |
| Progress | State icon plus a model-written summary, refreshed while it works | Steps, percent or N of M, the agent's own message, elapsed time and an estimate |
| Answering | Peek and reply in the terminal; attach for permission prompts | Reply, or reply and unblock, on the board; the agent reads it with taskhold_updates |
| Starting work | Dispatch a new session from the same screen | Queue a task; the next agent session takes it |
| Backlog and history | Sessions | A task list with projects, priorities and every change marked human or agent |
| Notifications | Through preferredNotifChannel while agent view is open | Browser notifications while the board is open |

Agent view facts from code.claude.com/docs/en/agent-view, checked 2026-10-26.

## When is agent view the better choice?

- You run several Claude Code sessions on one machine and want to see which one needs you.
- You want to start sessions and answer them without leaving the terminal.
- You want it free and built in.

## When is Taskhold the better choice?

- Your agents are spread across Claude Code, Codex, Cursor or more than one machine.
- You want to follow progress and answer questions from a phone or a browser.
- You want a backlog the agents pull from, with the steps and summary kept on each task after the session is gone.

## Using both

Dispatch and supervise Claude Code sessions in agent view, and have each session work from Taskhold: it takes the next task, plans steps and reports progress there. Agent view tells you which session to attach to; the live board tells you, and anyone you share a screen with, where the work stands.

## FAQ

### Does agent view work with Codex or Cursor?

Agent view covers Claude Code sessions. The docs describe it as running sessions on your machine that you dispatch from Claude Code.

### Can Taskhold start or stop my agents?

No. Taskhold is the list and the board. You start agents however you already do, and they connect to Taskhold over MCP.

## Sources

- [Claude Code docs: agent view](https://code.claude.com/docs/en/agent-view), checked 2026-10-26
- [Claude Code docs: run agents in parallel](https://code.claude.com/docs/en/agents), checked 2026-10-26

## Related

- [Taskhold vs Claude Code's built-in task list](https://taskhold.com/vs/claude-code-tasks.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Taskhold vs Beads

> Beads is a free, Dolt-backed issue graph your agents claim work from on the command line. Taskhold is a hosted list with a live board. When each one fits.

Source: https://taskhold.com/vs/beads
Last updated: 2026-10-26

> Short answer: Beads (bd) is a free, MIT-licensed issue tracker for coding agents: a dependency graph stored in Dolt next to your project, where agents run bd ready and claim work atomically. Pick it for many agents working one dependency graph from the terminal. Taskhold is a hosted list at $12 a month with a live board of each agent's steps that you watch and answer from any browser.

Beads is a command-line issue tracker built for coding agents. Tasks live in a Dolt database inside the project, linked into a dependency graph; bd ready lists work with no open blockers and bd update --claim takes a task atomically, so parallel agents don't collide. It's popular and actively developed. Taskhold is a hosted list with a [live board](https://taskhold.com/demo/live) of each agent's progress, closer to [one task list across all your repos](https://taskhold.com/guides/one-task-list-across-repos). [Backlog.md](https://taskhold.com/vs/backlog-md) is the markdown-in-the-repo option, and the [roundup](https://taskhold.com/vs/ai-coding-agent-task-managers) compares them all.

## Side by side

|  | Beads (bd) | Taskhold |
| --- | --- | --- |
| Price | Free (MIT) | $12/month or $120/year per person |
| Where tasks live | A Dolt database in the project (.beads/), synced with bd dolt push / pull | Hosted list |
| Dependencies | Yes: a graph; bd ready shows unblocked work | No (priority and order only) |
| Claiming work | bd update --claim, atomic | taskhold_start marks it in progress with the agent's label |
| Human view | CLI; no built-in UI (community UIs are listed) | Web app and live board on any device, including a phone |
| Progress inside a task | Status and an audit trail per issue; step-by-step progress isn't described in the README | Steps with a bar, percent or N of M and the agent's current message |
| Agent asks you something | Not described in the README | Blocked question on the live board with a reply box |
| Setup | Install the CLI, bd init per project, bd setup for each agent | Paste a setup URL |
| Offline | Yes | No |

Beads facts from its GitHub README, checked 2026-10-26.

## When is Beads the better choice?

- Many agents work one project and need dependencies worked out and atomic claims.
- You want everything local, versioned and free, with sync through your git remote.
- You and your agents live in the terminal.

## When is Taskhold the better choice?

- You want to watch a task's steps fill in and answer an agent's question from a browser or phone.
- Your work spans several repos, or isn't tied to one.
- You'd rather not install and maintain a CLI and database in each project.

## Using both

Beads can hold a project's dependency graph while Taskhold holds what you hand to agents across projects: an agent takes a Taskhold task, works the matching beads in that repo, and reports steps and progress to the live board as it goes.

## Moving tasks over

There's no importer. bd can print issues as JSON, so an agent connected to Taskhold can read them and create each open one with taskhold_create. Dependencies don't carry over; set priorities to get the order you want.

## FAQ

### Does Taskhold have task dependencies like Beads?

No. Taskhold orders work by priority, and an agent breaks each task into ordered steps. If you need a dependency graph, Beads does that.

## Sources

- [Beads README](https://github.com/steveyegge/beads), checked 2026-10-26

## Related

- [Taskhold vs Backlog.md for AI coding agents](https://taskhold.com/vs/backlog-md.md)
- [Taskhold vs Taskmaster AI for coding agents](https://taskhold.com/vs/taskmaster-ai.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Task managers for AI coding agents, compared](https://taskhold.com/vs/ai-coding-agent-task-managers.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

---

# Task managers for AI coding agents, compared (October 2026)

> Claude Code tasks, Taskmaster, Backlog.md, Beads, Linear, GitHub Issues, Todoist, Vibe Kanban and Taskhold side by side, with prices checked October 2026.

Source: https://taskhold.com/vs/ai-coding-agent-task-managers
Last updated: 2026-10-26

> Short answer: For one repo and one agent, a free local tool is enough: Claude Code's own tasks, Backlog.md, Beads or Taskmaster. For team work, connect agents to Linear or GitHub Issues. Taskhold is for one person running several agents across repos and machines who wants to watch their progress and answer their questions from a browser or phone.

We make Taskhold, so read this as a vendor's comparison. Every fact about another tool comes from that tool's own site or README, checked on 2026-10-26, and each has a dedicated page linked below where we go into more detail. Where a tool doesn't describe a feature, the table says so rather than saying it lacks it. Taskhold's own angle is the live board: each agent's progress step by step, across tools. Dedicated comparisons: [Claude Code tasks](https://taskhold.com/vs/claude-code-tasks), [Taskmaster AI](https://taskhold.com/vs/taskmaster-ai), [Backlog.md](https://taskhold.com/vs/backlog-md), [Beads](https://taskhold.com/vs/beads), [Linear](https://taskhold.com/vs/linear), [GitHub Issues](https://taskhold.com/vs/github-issues) and [Todoist](https://taskhold.com/vs/todoist). For how widely developers use these agents in the first place, see [AI coding statistics](https://taskhold.com/guides/ai-coding-statistics).

## At a glance

| Tool | Price | Where tasks live | Live progress for you | Best for |
| --- | --- | --- | --- | --- |
| Claude Code tasks + agent view | Included | ~/.claude/tasks/ on your machine | Ctrl+T checklist; agent view shows each session's state | Claude Code only, one machine |
| Taskmaster AI | CLI free; Hamster Team $40/creator/month | .taskmaster/ in the repo | Not described in the README | Turning a PRD into dependent tasks |
| Backlog.md | Free (MIT) | Markdown files in the repo | Terminal board and local web UI with real-time updates | Tasks versioned with the code |
| Beads | Free (MIT) | A Dolt database with the project | No built-in UI; community UIs listed | Many agents claiming work from a dependency graph |
| Linear + MCP | Free (250 issues); Basic $10/user/month yearly | Linear workspace | Agent API sessions with activities and a step plan (preview) | Teams already planning in Linear |
| GitHub Issues + MCP | Free; Team $4/user/month | Issues in each repo | Comments and checkboxes by convention | Tasks tied to PRs in one repo |
| Todoist + MCP | Free plan; Pro is paid | Todoist account | Not described in the MCP README | One list for life and agent to-dos |
| Vibe Kanban | Free (Apache-2.0), sunsetting | Local app | Per-agent workspace with terminal and diff review | Running agents in parallel worktrees, locally |
| Shrimp Task Manager | Free (MIT) | A local data folder (DATA_DIR) | Optional local web GUI and task viewer | Planning and reflecting on tasks for one project, locally |
| Taskhold | $12/month or $120/year per person | Hosted list, grouped by project | Live board: steps, progress, current message, blocked questions with replies | One person, several agents, any device |

Checked 2026-10-26 from each tool's pricing page, docs or README (sources below). Todoist's pricing page renders prices client-side; see todoist.com/pricing for current Pro pricing.

## How to choose

How we compared, in this order: where the tasks live; whether you can watch progress while an agent works; whether it works across agents and machines; price.

- You use only Claude Code on one machine: start with its built-in tasks and agent view. On newer models, turn the task tools on with CLAUDE_CODE_ENABLE_TODO_TOOLS=1.
- You start from a spec and want dependencies worked out: Taskmaster AI.
- You want tasks reviewed in pull requests next to the code: Backlog.md.
- You run many agents at once and want atomic claims and a ready queue: Beads.
- Your team plans in Linear or GitHub: connect your agents there, so the work stays visible to the team.
- You want one list for groceries and agent work: Todoist.
- You want to queue work for several agents across repos, see each task's steps fill in, and answer blocked questions from your phone: Taskhold.

## What to watch out for with each

- Claude Code tasks + agent view: Claude Code only, on one machine.
- Taskmaster AI: progress while it works isn't described in the README.
- Backlog.md: tasks live in each repo, so several repos means several boards.
- Beads: no built-in UI.
- Linear + MCP: priced per user; agent step plans are a preview.
- GitHub Issues + MCP: progress only by convention (comments, checkboxes).
- Todoist + MCP: progress isn't described in the MCP README.
- Vibe Kanban: sunsetting.
- Shrimp Task Manager: a local data folder per setup; last code change August 2025.
- Taskhold: no free plan, no team workspaces, no task dependencies.

What changed: 2026-10-26, added Shrimp Task Manager and a watch-out per tool.

## What Taskhold doesn't do

- No free plan: a 7-day trial with a card, then $12 a month.
- No team workspaces yet: one person and their agents.
- No task dependencies or PRD breakdown, and it doesn't run agents or show diffs.
- No offline mode: the list is hosted.

## FAQ

### What is the best task manager for Claude Code?

For one machine and Claude Code alone, its built-in tasks and agent view are free and good. If you also run Codex or Cursor, want the list on your phone, or want to watch step-by-step progress, a hosted list over MCP such as Taskhold fits better.

### Do I need a task manager for my coding agent at all?

Not for one-off prompts. A list starts paying off when you queue more work than one session finishes, run agents in parallel, or want to know what happened while you were away.

## Sources

- [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
- [Taskmaster README](https://github.com/eyaltoledano/claude-task-master), checked 2026-10-26
- [Hamster pricing](https://tryhamster.com/pricing), checked 2026-10-26
- [Backlog.md README](https://github.com/MrLesk/Backlog.md), checked 2026-10-26
- [Beads README](https://github.com/steveyegge/beads), checked 2026-10-26
- [Linear pricing](https://linear.app/pricing), checked 2026-10-26
- [Linear agent interaction docs](https://linear.app/developers/agent-interaction), checked 2026-10-26
- [GitHub pricing](https://github.com/pricing), checked 2026-10-26
- [Doist todoist-ai (MCP)](https://github.com/Doist/todoist-ai), checked 2026-10-26
- [Vibe Kanban README](https://github.com/BloopAI/vibe-kanban), checked 2026-10-26
- [Shrimp Task Manager README](https://github.com/cjo4m06/mcp-shrimp-task-manager), checked 2026-10-26

## Related

- [Taskhold vs Claude Code's built-in task list](https://taskhold.com/vs/claude-code-tasks.md)
- [Taskhold vs Taskmaster AI for coding agents](https://taskhold.com/vs/taskmaster-ai.md)
- [Taskhold vs Backlog.md for AI coding agents](https://taskhold.com/vs/backlog-md.md)
- [Taskhold vs Beads (bd) for coding agent tasks](https://taskhold.com/vs/beads.md)
- [Taskhold vs Linear MCP for personal agent tasks](https://taskhold.com/vs/linear.md)
- [Taskhold vs GitHub Issues as an agent task board](https://taskhold.com/vs/github-issues.md)
- [Taskhold vs Todoist MCP for coding agent tasks](https://taskhold.com/vs/todoist.md)
- [A Vibe Kanban alternative for your agent backlog](https://taskhold.com/vs/vibe-kanban.md)
- [Taskhold vs a TODO.md file for coding agents](https://taskhold.com/vs/todo-md.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

---

# Use Taskhold with Cline

> Connect Cline to a task list you share: one cline_mcp_settings.json entry, a .clinerules file, and a live board of what it plans, runs and asks.

Source: https://taskhold.com/integrations/cline
Last updated: 2026-10-26

Cline does careful work inside VS Code, one chat at a time. Taskhold gives it a backlog that outlives the chat: you queue tasks in a browser, Cline takes the next one over MCP, splits it into steps and reports progress to the [live board](https://taskhold.com/demo/live) while you do something else.

The same list works for [Claude Code](https://taskhold.com/for/claude-code) and [Cursor](https://taskhold.com/for/cursor), so a task Cline started shows as taken to every other agent.

## What you get with Cline and Taskhold

- Cline reads your queue with taskhold_list and claims a task with taskhold_start, labelled "Cline in <repo>".
- A plan of steps and a progress bar on the live board while it works, plus its last progress message.
- Questions it can't answer on its own land under Needs you with a reply box, so you can answer from your phone.
- A summary on every finished task of what changed and how it was checked.

## Connect Cline to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. In the Cline panel open MCP Servers > Configure > Configure MCP Servers. That opens cline_mcp_settings.json.
3. Add the entry below and save. Cline connects right away; the server shows a green dot when it's up.

```json
{
  "mcpServers": {
    "taskhold": {
      "type": "streamableHttp",
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

Cline's docs ask for "type": "streamableHttp" on remote servers. Cline CLI reads the same file at ~/.cline/data/settings/cline_mcp_settings.json.

## Tell Cline how to use the list

Cline reads workspace rules from .clinerules/ (or .cline/rules/) and also reads AGENTS.md. Save this as .clinerules/taskhold.md, or put it in AGENTS.md so other agents follow it too:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Cline in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

Rules in ~/Documents/Cline/Rules apply to every workspace, if you want the workflow everywhere. The [CLAUDE.md task workflow guide](https://taskhold.com/guides/claude-md-task-workflow) explains each line.

## One limit to know

Cline asks you to approve each MCP tool call unless you turn on auto-approve for the Taskhold tools in the server's settings. With approvals on, every progress report waits on a click, which defeats the point of watching from the board. Auto-approve the taskhold_* tools only; they can't touch your files.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Cline docs: MCP overview](https://docs.cline.bot/mcp/mcp-overview), checked 2026-10-26
- [Cline docs: Cline rules](https://docs.cline.bot/customization/cline-rules), checked 2026-10-26

## Related

- [Use Taskhold with Kilo Code](https://taskhold.com/integrations/kilo-code.md)
- [Task list MCP server for VS Code and Copilot](https://taskhold.com/for/vs-code.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.md)
- [Taskhold for Roo Code users: Kilo Code or Cline](https://taskhold.com/integrations/roo-code-users.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

---

# Use Taskhold with Kilo Code

> Add Taskhold to Kilo Code as a remote MCP server in kilo.jsonc, keep the key in an env var, and watch each task's steps on a live board.

Source: https://taskhold.com/integrations/kilo-code
Last updated: 2026-10-26

Kilo Code runs agent modes inside VS Code and JetBrains, and from its CLI. Taskhold adds a task list you and Kilo share: you add work in the browser, Kilo plans it into steps over MCP, and the [live board](https://taskhold.com/demo/live) shows how far each task has got and where it is waiting on you.

If you moved to Kilo from Roo Code, the [note for Roo Code users](https://taskhold.com/integrations/roo-code-users) covers what carries over.

## What you get with Kilo Code and Taskhold

- Kilo claims tasks from your list and labels them "Kilo Code in <repo>", so other agents on the same list skip them.
- Steps, a progress bar and the current step on the live board, updated as Kilo reports.
- Blocking questions you answer from the board, which Kilo reads back with taskhold_updates.
- The same list for [Claude Code](https://taskhold.com/for/claude-code), [Codex](https://taskhold.com/for/codex) and any other MCP client you run.

## Connect Kilo Code to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Export it in your shell profile: export TASKHOLD_API_KEY=atd_sk_...
3. Add the server under the top-level mcp key in ~/.config/kilo/kilo.jsonc (every project) or ./kilo.jsonc (one project). The Settings > Agent Behaviour > MCP Servers panel edits the same entry.

```json
{
  "mcp": {
    "taskhold": {
      "type": "remote",
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer {env:TASKHOLD_API_KEY}" },
      "oauth": false,
      "enabled": true
    }
  }
}
```

{env:NAME} is Kilo's documented interpolation. "oauth": false stops Kilo starting an OAuth flow Taskhold doesn't use.

## Tell Kilo Code how to use the list

Kilo reads AGENTS.md at the project root first, and rules from .kilo/rules/. Put the workflow in AGENTS.md:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Kilo Code in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

Kilo picks up a new environment variable only when the editor starts. If the server shows an auth error after you export TASKHOLD_API_KEY, restart VS Code from a terminal that has the variable, or put the key in the header directly in your global kilo.jsonc (never in a project file you commit).

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Kilo docs: using MCP in Kilo Code](https://kilo.ai/docs/automate/mcp/using-in-kilo-code), checked 2026-10-26
- [Kilo docs: AGENTS.md](https://kilo.ai/docs/customize/agents-md), checked 2026-10-26
- [Kilo docs: custom rules](https://kilo.ai/docs/customize/custom-rules), checked 2026-10-26

## Related

- [Use Taskhold with Cline](https://taskhold.com/integrations/cline.md)
- [Taskhold for Roo Code users: Kilo Code or Cline](https://taskhold.com/integrations/roo-code-users.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.md)
- [Task list MCP server for OpenCode](https://taskhold.com/for/opencode.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

---

# Taskhold for Roo Code users

> Roo Code's repository is archived. Here is how to keep a shared task list and live board when you move to Kilo Code or Cline, with the config for each.

Source: https://taskhold.com/integrations/roo-code-users
Last updated: 2026-10-26

Roo Code's GitHub repository was archived in May 2026, so the extension gets no more fixes. Most of its users moved to [Kilo Code](https://taskhold.com/integrations/kilo-code) or [Cline](https://taskhold.com/integrations/cline). Both connect to Taskhold the same way: a remote MCP server with your API key, plus a rules file, and your tasks show on the [live board](https://taskhold.com/demo/live) as they run.

## Which page to follow

| You moved to | Config file | Rules file |
| --- | --- | --- |
| Kilo Code | kilo.jsonc, top-level mcp key, type remote | AGENTS.md or .kilo/rules/ |
| Cline | cline_mcp_settings.json, type streamableHttp | .clinerules/ or AGENTS.md |

Your old .roo/rules files don't load in either. Move the Taskhold workflow lines into AGENTS.md, which both read, and every agent on the repo follows the same instructions.

## One limit to know

Roo Code itself still runs if you keep it installed, and its MCP settings still work for now. Nothing will fix it if a VS Code update breaks it, so we don't write a Roo-specific setup page.

## Sources

- [RooCodeInc/Roo-Code repository (archived)](https://github.com/RooCodeInc/Roo-Code), checked 2026-10-26

## Related

- [Use Taskhold with Kilo Code](https://taskhold.com/integrations/kilo-code.md)
- [Use Taskhold with Cline](https://taskhold.com/integrations/cline.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.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

---

# Use Taskhold with Zed

> Add Taskhold to Zed as a remote context server with a bearer header, give the agent the workflow in AGENTS.md, and follow it on a live board.

Source: https://taskhold.com/integrations/zed
Last updated: 2026-10-26

Zed's agent panel talks to MCP servers it calls context servers. Taskhold is one of them: a hosted task list that Zed's agent reads and updates, and that you watch on the [live board](https://taskhold.com/demo/live) from any browser.

Zed can also run [Claude Code](https://taskhold.com/for/claude-code) and [Gemini CLI](https://taskhold.com/for/gemini-cli) as external agents; those read their own MCP config, so set them up on their own pages.

## What you get with Zed and Taskhold

- Zed's agent takes tasks from your list and marks them in progress as "Zed in <repo>".
- Steps and progress on the live board while it works, and its question under Needs you when it is stuck.
- A finished task carries a summary you can read without opening the thread.

## Connect Zed to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Open settings.json (zed: open settings) or go to Settings > AI > MCP Servers > Add Server > Add Remote Server.
3. Add the entry below. With an Authorization header set, Zed skips its OAuth prompt.

```json
{
  "context_servers": {
    "taskhold": {
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

## Tell Zed how to use the list

Zed loads the first instruction file it finds at the project root, in this order: .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md. Add the workflow to whichever of those your repo already has:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Zed in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

Zed doesn't document environment variable interpolation for context servers, so the key sits in plain text in settings.json. Use the user settings file, not a project .zed/settings.json you commit, and revoke the key in Taskhold if the file is ever shared.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Zed docs: Model Context Protocol](https://zed.dev/docs/ai/mcp), checked 2026-10-26
- [Zed docs: instructions and rules](https://zed.dev/docs/ai/instructions), checked 2026-10-26

## Related

- [Use Taskhold with Cline](https://taskhold.com/integrations/cline.md)
- [Task list MCP server for Gemini CLI](https://taskhold.com/for/gemini-cli.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Use Taskhold with the Trae IDE](https://taskhold.com/integrations/trae.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

---

# Use Taskhold with Junie

> Connect Junie in JetBrains IDEs or the Junie CLI to Taskhold with one mcp.json entry, add the workflow to AGENTS.md, and watch tasks on a live board.

Source: https://taskhold.com/integrations/junie
Last updated: 2026-10-26

Junie is JetBrains' coding agent, in IntelliJ-based IDEs and as a CLI. Both read the same MCP config, so one entry gives Junie your Taskhold list: it plans each task into steps and reports progress you follow on the [live board](https://taskhold.com/demo/live).

Running Junie next to [Claude Code](https://taskhold.com/for/claude-code) or [Codex](https://taskhold.com/for/codex)? Point them all at the same list; see [several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list).

## What you get with Junie and Taskhold

- Junie claims tasks as "Junie in <repo>", plans steps and reports progress.
- The live board shows its current step, elapsed time and last message, and moves blocked questions to the top.
- Finished tasks keep Junie's summary next to your own notes.

## Connect Junie to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Open ~/.junie/mcp/mcp.json (user scope, every project). Create it if it doesn't exist.
3. Add the entry below and restart Junie, or reload MCP servers from its settings.

```json
{
  "mcpServers": {
    "taskhold": {
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

Junie's docs: the CLI uses the same MCP JSON as Junie in JetBrains IDEs.

## Tell Junie how to use the list

Junie reads .junie/AGENTS.md, then AGENTS.md at the root, then .junie/rules/*.md. A global ~/.junie/AGENTS.md applies everywhere:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Junie in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

Junie has no documented environment variable interpolation in mcp.json, so the key is stored in plain text. Keep it in the user file. The project file .junie/mcp/mcp.json is easy to commit by accident, and JetBrains' own docs warn against secrets there. Older Junie plugin versions only ran local servers; update the plugin if the remote entry doesn't connect.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Junie docs: CLI MCP configuration](https://junie.jetbrains.com/docs/junie-cli-mcp-configuration.html), checked 2026-10-26
- [Junie docs: plugin MCP settings](https://junie.jetbrains.com/docs/junie-plugin-mcp-settings.html), checked 2026-10-26
- [Junie docs: guidelines and memory](https://junie.jetbrains.com/docs/guidelines-and-memory.html), checked 2026-10-26

## Related

- [Task list MCP server for Codex CLI](https://taskhold.com/for/codex.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Use Taskhold with Augment Code and Auggie](https://taskhold.com/integrations/augment-code.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

---

# Use Taskhold with Augment Code

> Add Taskhold to the Auggie CLI with one auggie mcp add command or settings.json entry, share the rules with the Augment extension, and watch a live board.

Source: https://taskhold.com/integrations/augment-code
Last updated: 2026-10-26

Augment's agent runs in VS Code, JetBrains IDEs and the Auggie CLI. Connected to Taskhold, it works from a list you control in the browser and reports steps and progress to the [live board](https://taskhold.com/demo/live).

Auggie and the extensions share one rules system, so the workflow snippet you add once applies to both. [Claude Code](https://taskhold.com/for/claude-code) reads CLAUDE.md too, so the same file can serve both agents.

## What you get with Augment Code and Taskhold

- Auggie and the Augment agent take tasks from your queue, labelled "Augment in <repo>".
- Steps, progress and the current step on the live board; questions under Needs you.
- Summaries on finished tasks, next to work other agents did on the same list.

## Connect Augment Code to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Run the command below, or add the same entry under mcpServers in ~/.augment/settings.json.

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

```json
{
  "mcpServers": {
    "taskhold": {
      "type": "http",
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

~/.augment/settings.json. Augment's docs: the headers field accepts any HTTP headers as key-value pairs.

In the VS Code or JetBrains extension, use Settings > MCP > Import from JSON and paste the mcpServers block.

## Tell Augment Code how to use the list

Augment loads CLAUDE.md, AGENTS.md, .augment-guidelines and .augment/rules/ at the workspace root, and ~/.augment/rules/ for every workspace. Add this to AGENTS.md (the [CLAUDE.md task workflow guide](https://taskhold.com/guides/claude-md-task-workflow) explains each line):

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Augment in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

The extension's "Add remote MCP" form only asks for a name and a URL, with no header field, so Taskhold would answer 401. Use Import from JSON with the headers block, or set the server up in Auggie, which documents headers.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Augment docs: Auggie CLI integrations](https://docs.augmentcode.com/cli/integrations), checked 2026-10-26
- [Augment docs: MCP setup](https://docs.augmentcode.com/setup-augment/mcp), checked 2026-10-26
- [Augment docs: Auggie rules](https://docs.augmentcode.com/cli/rules), checked 2026-10-26

## Related

- [Use Taskhold with JetBrains Junie](https://taskhold.com/integrations/junie.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.md)
- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.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

---

# Use Taskhold with Trae

> Add Taskhold to Trae as an MCP server with a url and an Authorization header, put the workflow in a Trae rule, and see each task's steps on a live board.

Source: https://taskhold.com/integrations/trae
Last updated: 2026-10-26

Trae's agent accepts remote MCP servers with custom headers, which is all Taskhold needs. Once connected, it takes tasks from the list you keep in the browser, plans steps and reports progress on the [live board](https://taskhold.com/demo/live).

The workflow is the same one [Cursor](https://taskhold.com/for/cursor) and [Windsurf](https://taskhold.com/for/windsurf) use, so a team on mixed editors shares one list.

## What you get with Trae and Taskhold

- Trae's agent claims tasks as "Trae in <repo>" so other agents leave them alone.
- A live board with its steps, current step and last message.
- Questions you answer from the board, read back by the agent with taskhold_updates.

## Connect Trae to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Open Settings > MCP > Add > Create Manually, or click Raw Config (JSON) to edit mcp.json.
3. Paste the entry below. For one project only, turn on project MCP in Settings > MCP and put it in .trae/mcp.json instead.

```json
{
  "mcpServers": {
    "taskhold": {
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

## Tell Trae how to use the list

Trae reads project rules from .trae/rules/ and global rules from Settings > Rules & Memories. It can also load AGENTS.md and CLAUDE.md once you turn that on in the same settings page. Save this as .trae/rules/taskhold.md:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Trae in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

Trae only interpolates ${workspaceFolder} in MCP config, not environment variables, so the key is stored in plain text. Don't put the header in a .trae/mcp.json you commit; use the user config and keep the key out of project files.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Trae docs: add MCP servers](https://docs.trae.ai/ide/add-mcp-servers), checked 2026-10-26
- [Trae docs: rules](https://docs.trae.ai/ide/rules), checked 2026-10-26

## Related

- [Task list MCP server for Cursor](https://taskhold.com/for/cursor.md)
- [Task list MCP for Windsurf and Devin Desktop](https://taskhold.com/for/windsurf.md)
- [Use Taskhold with Zed's agent](https://taskhold.com/integrations/zed.md)
- [Use Taskhold with Kiro](https://taskhold.com/integrations/kiro.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

---

# Use Taskhold with Goose

> Add Taskhold to Goose as a streamable_http extension in config.yaml, pull the key from an env var, and watch each task's steps on a live board.

Source: https://taskhold.com/integrations/goose
Last updated: 2026-10-26

Goose is an open source agent that runs in a terminal or its desktop app and loads tools as extensions. Taskhold plugs in as a remote extension: a task list you fill in the browser, that Goose plans into steps and reports on while you watch the [live board](https://taskhold.com/demo/live).

Goose reads AGENTS.md first, the same file [Codex](https://taskhold.com/for/codex) and [OpenCode](https://taskhold.com/for/opencode) read, so one copy of the workflow serves all of them.

## What you get with Goose and Taskhold

- Goose claims tasks as "Goose in <repo>" and works through them in priority order.
- Steps, percent done and its current step on the live board, plus questions you answer from there.
- Summaries on finished tasks, visible from your phone.

## Connect Goose to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Export it in your shell profile: export TASKHOLD_API_KEY=atd_sk_...
3. Add the extension to ~/.config/goose/config.yaml, then start a new Goose session.

```yaml
extensions:
  taskhold:
    type: streamable_http
    name: taskhold
    enabled: true
    uri: https://taskhold.com/api/mcp
    headers:
      Authorization: "Bearer ${TASKHOLD_API_KEY}"
    env_keys:
      - TASKHOLD_API_KEY
    timeout: 300
```

env_keys tells Goose which variables to pass in; header values are expanded from them.

## Tell Goose how to use the list

Goose looks for AGENTS.md, then .goosehints, in the directory you start it from. Add the workflow to AGENTS.md:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Goose in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

Goose's docs describe ${VAR} expansion for OAuth settings but not for headers; header expansion is in its source code (crates/goose/src/agents/extension.rs) and works only when the variable is listed in env_keys. Leave env_keys out and Goose sends the literal text ${TASKHOLD_API_KEY}, which Taskhold rejects with 401.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Goose docs: config files](https://github.com/aaif-goose/goose/blob/main/documentation/docs/guides/config-files.md), checked 2026-10-26
- [Goose docs: using extensions](https://github.com/aaif-goose/goose/blob/main/documentation/docs/getting-started/using-extensions.md), checked 2026-10-26
- [Goose docs: using goosehints and AGENTS.md](https://github.com/aaif-goose/goose/blob/main/documentation/docs/guides/context-engineering/using-goosehints.md), checked 2026-10-26

## Related

- [Task list MCP server for Codex CLI](https://taskhold.com/for/codex.md)
- [Use Taskhold with Charm's Crush](https://taskhold.com/integrations/crush.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.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

---

# Use Taskhold with Amp

> Connect Amp to Taskhold with an amp.mcpServers entry that reads your key from an env var, add the AGENTS.md workflow, and see its progress live.

Source: https://taskhold.com/integrations/amp
Last updated: 2026-10-26

Amp works in your terminal and editor and reads AGENTS.md on every thread. Add Taskhold as an MCP server and it takes tasks from a list you keep in the browser, reports each step and asks questions on the [live board](https://taskhold.com/demo/live).

The same list can feed [Claude Code](https://taskhold.com/for/claude-code) or [Codex](https://taskhold.com/for/codex) at the same time; see [several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list).

## What you get with Amp and Taskhold

- Amp claims a task as "Amp in <repo>" so other agents skip it.
- Steps, progress and its last message on the live board while the thread runs.
- Blocked questions you answer from the board; Amp reads them with taskhold_updates.

## Connect Amp to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Export it in your shell profile: export TASKHOLD_API_KEY=atd_sk_...
3. Add the server to ~/.config/amp/settings.json and start a new thread.

```json
{
  "amp.mcpServers": {
    "taskhold": {
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer ${TASKHOLD_API_KEY}" }
    }
  }
}
```

Amp expands ${VAR_NAME} from the environment. amp mcp add has no header flag, so headers go in the JSON.

## Tell Amp how to use the list

Amp reads AGENTS.md from the current directory up to your home folder, and always includes ~/.config/amp/AGENTS.md. Put the workflow in the repo's AGENTS.md, or in the global file to use it everywhere:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Amp in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

A server added in the workspace file .amp/settings.json doesn't run until you approve it with amp mcp approve taskhold. Keep the Taskhold entry in your user settings instead: no approval step, and no chance of committing it.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Amp manual: MCP](https://ampcode.com/docs/customize/mcp), checked 2026-10-26
- [Amp manual: AGENTS.md](https://ampcode.com/docs/customize/agents-md), checked 2026-10-26

## Related

- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Use Taskhold with Goose](https://taskhold.com/integrations/goose.md)
- [Use Taskhold with Claude Desktop and claude.ai](https://taskhold.com/integrations/claude-desktop.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

---

# Use Taskhold with Kiro

> Add Taskhold to Kiro's mcp.json with an approved env var for the key, steer the agent with AGENTS.md, and follow every task on a live board.

Source: https://taskhold.com/integrations/kiro
Last updated: 2026-10-26

Kiro plans work from specs and steering files. Taskhold gives it a shared queue to work from and a [live board](https://taskhold.com/demo/live) where you see each task's steps and answer its questions, in Kiro's IDE, CLI or web app.

If you write specs first, [break a spec into agent tasks](https://taskhold.com/guides/break-a-spec-into-agent-tasks) shows how to turn one into a Taskhold queue. Kiro can share the list with [Claude Code](https://taskhold.com/for/claude-code) or [Amp](https://taskhold.com/integrations/amp).

## What you get with Kiro and Taskhold

- Kiro claims tasks as "Kiro in <repo>" and plans each into steps.
- Progress and the running step on the live board, with blocked questions at the top.
- A summary on each finished task.

## Connect Kiro to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Export it in your shell profile: export TASKHOLD_API_KEY=atd_sk_...
3. Add TASKHOLD_API_KEY to Kiro's "Mcp Approved Env Vars" setting. Kiro only expands variables on that list.
4. Add the server to ~/.kiro/settings/mcp.json (every workspace) or .kiro/settings/mcp.json (one workspace).

```json
{
  "mcpServers": {
    "taskhold": {
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer ${TASKHOLD_API_KEY}" }
    }
  }
}
```

## Tell Kiro how to use the list

Kiro always includes AGENTS.md at the workspace root, and steering files in .kiro/steering/. Add the workflow to AGENTS.md, or save it as .kiro/steering/taskhold.md:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Kiro in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

If TASKHOLD_API_KEY isn't in the approved list, Kiro sends the header unexpanded and every Taskhold call fails with 401. When the server shows an auth error, check that setting first.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Kiro docs: MCP configuration](https://kiro.dev/docs/mcp/configuration/), checked 2026-10-26
- [Kiro docs: steering](https://kiro.dev/docs/steering/), checked 2026-10-26

## Related

- [Break a spec into tasks for your coding agent](https://taskhold.com/guides/break-a-spec-into-agent-tasks.md)
- [Use Taskhold with Amp](https://taskhold.com/integrations/amp.md)
- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.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

---

# Use Taskhold with Warp

> Add Taskhold to Warp as an MCP server with a bearer header, keep the workflow in AGENTS.md, and watch the agent's steps on a live board.

Source: https://taskhold.com/integrations/warp
Last updated: 2026-10-26

Warp's agent runs in the terminal you already use. Connected to Taskhold, it works from a list you manage in the browser and reports steps, progress and questions to the [live board](https://taskhold.com/demo/live).

Warp can also pick up MCP servers you configured for [Claude Code](https://taskhold.com/for/claude-code) or [Codex](https://taskhold.com/for/codex), so you may find Taskhold already listed.

## What you get with Warp and Taskhold

- Warp's agent claims tasks as "Warp in <repo>".
- Steps and progress on the live board while you keep using the terminal for other things.
- Questions under Needs you, answered from the board.

## Connect Warp to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Open Settings > Agents > MCP servers and click + Add, or edit ~/.warp/.mcp.json.
3. Paste the entry below and start the server.

```json
{
  "mcpServers": {
    "taskhold": {
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
```

Warp's docs: pass a bearer token through the headers field.

## Tell Warp how to use the list

Warp reads project rules from AGENTS.md (or WARP.md, which wins if both exist). Add the workflow there; global rules live in Warp Drive:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Warp in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

Warp doesn't document environment variable expansion in headers, so the key is stored as text in ~/.warp/.mcp.json. Keep it out of a project .warp/.mcp.json you commit.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Warp docs: MCP](https://docs.warp.dev/agents/capabilities/mcp/), checked 2026-10-26
- [Warp docs: rules](https://docs.warp.dev/agents/capabilities/rules/), checked 2026-10-26

## Related

- [Taskhold in tmux: status bar and a live board pane](https://taskhold.com/integrations/tmux.md)
- [Task list MCP server for Codex CLI](https://taskhold.com/for/codex.md)
- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [Use Taskhold with Qwen Code](https://taskhold.com/integrations/qwen-code.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

---

# Use Taskhold with Crush

> Add Taskhold to Crush with one mcp add line in crushrc, mark it sessionless, and let Crush report steps and questions to a live board.

Source: https://taskhold.com/integrations/crush
Last updated: 2026-10-26

Crush is Charm's terminal coding agent. One line in crushrc connects it to Taskhold, and from then on it works from a list you keep in the browser and reports its steps to the [live board](https://taskhold.com/demo/live).

Crush reads AGENTS.md, so the workflow you write for [Codex](https://taskhold.com/for/codex) or [OpenCode](https://taskhold.com/for/opencode) works unchanged.

## What you get with Crush and Taskhold

- Crush claims tasks as "Crush in <repo>" and plans them into steps.
- Progress, the current step and blocked questions on the live board.
- Summaries on finished tasks you can read from any device.

## Connect Crush to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Export it in your shell profile: export TASKHOLD_API_KEY=atd_sk_...
3. Add this line to ~/.config/crush/crushrc (every project) or ./crushrc (one project):

```bash
mcp add taskhold --type http --url "https://taskhold.com/api/mcp" \
  --header Authorization "Bearer $TASKHOLD_API_KEY" --sessionless true
```

Still on the older crush.json? The same server there:

```json
{
  "mcp": {
    "taskhold": {
      "type": "http",
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer $TASKHOLD_API_KEY" },
      "sessionless": true
    }
  }
}
```

## Tell Crush how to use the list

Crush reads AGENTS.md in the project and ~/.config/crush/CRUSH.md globally. Add the workflow to AGENTS.md:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Crush in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

Taskhold's MCP server is stateless: it never issues an Mcp-Session-Id. Crush opens a subscription stream that stateless servers refuse, and only auto-detects that for GitHub's server. Without --sessionless true the connection to Taskhold can drop.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Crush README](https://github.com/charmbracelet/crush), checked 2026-10-26
- [Crush config docs](https://github.com/charmbracelet/crush/blob/main/docs/config/README.md), checked 2026-10-26

## Related

- [Use Taskhold with Goose](https://taskhold.com/integrations/goose.md)
- [Task list MCP server for OpenCode](https://taskhold.com/for/opencode.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.md)
- [Use Taskhold with Warp's agent](https://taskhold.com/integrations/warp.md)
- [Use Taskhold with Factory Droid](https://taskhold.com/integrations/factory-droid.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

---

# Use Taskhold with Qwen Code

> Connect Qwen Code to Taskhold with an httpUrl entry in settings.json, read the key from an env var, and watch its plan and progress on a live board.

Source: https://taskhold.com/integrations/qwen-code
Last updated: 2026-10-26

Qwen Code is a terminal agent built from Gemini CLI, and it configures MCP servers the same way. Add Taskhold and Qwen Code works from your shared list, with steps and progress on the [live board](https://taskhold.com/demo/live).

Setting up [Gemini CLI](https://taskhold.com/for/gemini-cli) too? The entry is nearly identical, and both agents can share one list; see [several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list).

## What you get with Qwen Code and Taskhold

- Qwen Code claims tasks as "Qwen Code in <repo>".
- Its plan, progress and current step on the live board.
- Questions you answer from the board, picked up with taskhold_updates.

## Connect Qwen Code to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Export it in your shell profile: export TASKHOLD_API_KEY=atd_sk_...
3. Add the server to ~/.qwen/settings.json (or .qwen/settings.json in one project).

```json
{
  "mcpServers": {
    "taskhold": {
      "httpUrl": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer $TASKHOLD_API_KEY" }
    }
  }
}
```

Qwen Code expands $VAR_NAME and ${VAR_NAME} in settings.json.

## Tell Qwen Code how to use the list

Qwen Code reads QWEN.md and also reads AGENTS.md when the repo has one. Add the workflow to AGENTS.md so other agents share 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.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Qwen Code in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

The key has to be httpUrl. In Qwen Code, url means an SSE server, so a generic snippet with url connects with the wrong transport and fails against Taskhold's Streamable HTTP endpoint.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Qwen Code docs: MCP](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/mcp.md), checked 2026-10-26
- [Qwen Code docs: settings](https://github.com/QwenLM/qwen-code/blob/main/docs/users/configuration/settings.md), checked 2026-10-26
- [Qwen Code docs: memory and context files](https://github.com/QwenLM/qwen-code/blob/main/docs/users/features/memory.md), checked 2026-10-26

## Related

- [Task list MCP server for Gemini CLI](https://taskhold.com/for/gemini-cli.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Use Taskhold with Charm's Crush](https://taskhold.com/integrations/crush.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

---

# Use Taskhold with Factory Droid

> Add Taskhold to Factory's Droid with droid mcp add or ~/.factory/mcp.json, expand the key from your shell, and see its steps on a live board.

Source: https://taskhold.com/integrations/factory-droid
Last updated: 2026-10-26

Droid is Factory's coding agent for the terminal. Connected to Taskhold, it takes work from a list you control in the browser and reports steps and progress to the [live board](https://taskhold.com/demo/live).

Droid reads AGENTS.md, so the workflow is the one on the [CLAUDE.md task workflow guide](https://taskhold.com/guides/claude-md-task-workflow). To check on Droid from your phone, see [monitoring agent progress](https://taskhold.com/guides/monitor-coding-agent-progress).

## What you get with Factory Droid and Taskhold

- Droid claims tasks as "Droid in <repo>".
- Steps, progress and questions on the live board.
- Summaries on finished work.

## Connect Factory Droid to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Export it in your shell profile: export TASKHOLD_API_KEY=atd_sk_...
3. Add the server with the command below, or put the JSON in ~/.factory/mcp.json.

```bash
droid mcp add taskhold https://taskhold.com/api/mcp --type http --header "Authorization: Bearer <your atd_sk_ key>"
```

```json
{
  "mcpServers": {
    "taskhold": {
      "type": "http",
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer ${TASKHOLD_API_KEY}" },
      "disabled": false
    }
  }
}
```

Droid expands ${NAME} in mcp.json from the shell it was started in.

## Tell Factory Droid how to use the list

Droid reads AGENTS.md at the project root. Add the workflow there:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Droid in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

Factory's docs warn against putting auth headers in a project .factory/mcp.json. Keep the Taskhold entry in ~/.factory/mcp.json, and start Droid from a shell where TASKHOLD_API_KEY is exported, or the header goes out empty.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Factory docs: MCP configuration](https://docs.factory.com/cli/configuration/mcp), checked 2026-10-26

## Related

- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.md)
- [Use Taskhold with Amp](https://taskhold.com/integrations/amp.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.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

---

# Use Taskhold with the Copilot coding agent

> Give GitHub Copilot's cloud coding agent your Taskhold list: MCP config in repo settings, a COPILOT_MCP_ secret for the key, and a live board of its runs.

Source: https://taskhold.com/integrations/copilot-coding-agent
Last updated: 2026-10-26

Copilot's coding agent works in GitHub's cloud, so you can't watch a terminal. Taskhold gives it a list to report into: assign an issue, and the agent plans its steps and reports progress to the [live board](https://taskhold.com/demo/live) while it runs.

For Copilot in your editor, see [VS Code](https://taskhold.com/for/vs-code); for the terminal, [Copilot CLI](https://taskhold.com/integrations/copilot-cli).

## What you get with Copilot coding agent and Taskhold

- Each run reports a plan of steps, progress and its current step to the live board.
- Questions it can't settle go under Needs you; the run reads your answer with taskhold_updates if it is still going.
- A summary on the task when the pull request is ready.

## Connect Copilot coding agent to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. In the repository, open Settings > Secrets and variables > Agents and add a secret named COPILOT_MCP_TASKHOLD_API_KEY with the key. Copilot only passes secrets whose names start with COPILOT_MCP_.
3. Open Settings > Copilot > MCP servers, paste the configuration below and save.

```json
{
  "mcpServers": {
    "taskhold": {
      "type": "http",
      "url": "https://taskhold.com/api/mcp",
      "tools": ["*"],
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_TASKHOLD_API_KEY",
        "X-Taskhold-Agent": "Copilot coding agent"
      }
    }
  }
}
```

type and tools are required. X-Taskhold-Agent sets the name on the board.

## Tell Copilot coding agent how to use the list

The cloud agent reads .github/copilot-instructions.md, AGENTS.md and a root CLAUDE.md. Add the workflow to AGENTS.md:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Copilot coding agent in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

To hand it work from Taskhold instead of an issue, see [handing tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent).

## One limit to know

The key is one repository secret, so every cloud run in that repo writes to the Taskhold account the key belongs to. Fine for your own repos; on a shared repo, use a key from an account the team agrees on. The agent's firewall doesn't apply to MCP servers, but it does block curl calls to the Taskhold REST API from its shell.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [GitHub docs: extend the coding agent with MCP](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp), checked 2026-10-26
- [GitHub docs: repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions), checked 2026-10-26

## Related

- [Task list MCP server for VS Code and Copilot](https://taskhold.com/for/vs-code.md)
- [Use Taskhold with GitHub Copilot CLI](https://taskhold.com/integrations/copilot-cli.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [File a Taskhold task when GitHub Actions fails](https://taskhold.com/integrations/github-actions.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

---

# Use Taskhold with Copilot CLI

> Add Taskhold to GitHub Copilot CLI in ~/.copilot/mcp-config.json with a bearer header, share the AGENTS.md workflow, and watch its tasks on a live board.

Source: https://taskhold.com/integrations/copilot-cli
Last updated: 2026-10-26

Copilot CLI is GitHub's agent for the terminal. Add Taskhold as an MCP server and it plans work from your shared list and reports each step to the [live board](https://taskhold.com/demo/live).

The cloud version has its own setup: [Copilot coding agent](https://taskhold.com/integrations/copilot-coding-agent). In the editor, see [VS Code](https://taskhold.com/for/vs-code).

## What you get with Copilot CLI and Taskhold

- Copilot CLI claims tasks as "Copilot CLI in <repo>".
- Steps, progress and the running step on the live board.
- Blocked questions you answer from the board.

## Connect Copilot CLI to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Add the server to ~/.copilot/mcp-config.json, or run /mcp add inside Copilot CLI and paste the header as JSON.

```json
{
  "mcpServers": {
    "taskhold": {
      "type": "http",
      "url": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" },
      "tools": ["*"]
    }
  }
}
```

## Tell Copilot CLI how to use the list

Copilot CLI reads AGENTS.md, .github/copilot-instructions.md and CLAUDE.md. Add the workflow to AGENTS.md:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Copilot CLI in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

GitHub's docs don't describe environment variable expansion in mcp-config.json, so the key is stored as text in ~/.copilot. Don't copy the entry into a project .mcp.json you commit.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [GitHub docs: add MCP servers to Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers), checked 2026-10-26

## Related

- [Use Taskhold with GitHub Copilot's cloud agent](https://taskhold.com/integrations/copilot-coding-agent.md)
- [Task list MCP server for VS Code and Copilot](https://taskhold.com/for/vs-code.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.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

---

# Use Taskhold with Claude Desktop

> Add Taskhold to Claude Desktop and claude.ai as a custom connector with a request header, or run it locally, then plan and track tasks on a live board.

Source: https://taskhold.com/integrations/claude-desktop
Last updated: 2026-10-26

Claude Desktop and claude.ai aren't coding agents, but they are a good place to plan: talk through a feature, then have Claude file it as Taskhold tasks your coding agents pick up. Anything that runs shows on the [live board](https://taskhold.com/demo/live).

For the coding side, set up [Claude Code](https://taskhold.com/for/claude-code); to plan from a spec, see [break a spec into agent tasks](https://taskhold.com/guides/break-a-spec-into-agent-tasks).

## What you get with Claude Desktop and Taskhold

- Claude can read your queue, file new tasks and split them into steps from a chat.
- Ask "what are my agents doing?" and Claude reads the tasks in progress with their steps and last messages.
- Reply to a blocked agent from the chat with a note on its task.

## Connect Claude Desktop to Taskhold

1. Start the 7-day trial, open Settings > API keys and create a key for this machine. It starts with atd_sk_. One key per tool and machine lets you revoke each one on its own.
2. Open Customize > Connectors, click + Add, then Add custom connector.
3. Enter the URL below. Under Authentication choose No sign in, and under Request headers add Authorization with the value Bearer and your key.

```text
URL: https://taskhold.com/api/mcp
Header: Authorization: Bearer <your atd_sk_ key>
```

A connector added this way also works on claude.ai in the browser.

To run it locally instead, add the hosted build to claude_desktop_config.json (Settings > Developer > Edit Config). Needs Node.js 18 or later:

```json
{
  "mcpServers": {
    "taskhold": {
      "command": "npx",
      "args": ["-y", "https://taskhold.com/dl/taskhold-mcp-latest.tgz"],
      "env": { "TASKHOLD_API_KEY": "<your atd_sk_ key>" }
    }
  }
}
```

## Tell Claude Desktop how to use the list

Claude Desktop has no rules file. Put the workflow in a Project's instructions so every chat in that project follows 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.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Claude Desktop in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

On a Team or Enterprise plan, a connector with a fixed header gives everyone who uses it that one key, so every member would write into one Taskhold account. Use the connector on an individual plan, or the local config on your own machine.

## What leaves your machine, and how to disconnect

Taskhold receives task titles, steps, progress messages, questions and summaries, whatever the agent or script sends. Taskhold never sends code or commands to your machine, and it doesn't read your repository.

To cut a tool off, open Settings > API keys and revoke its key. The next call fails with 401. Then remove the Taskhold entry from the tool's config so it stops trying.

## Sources

- [Claude Help Center: custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp), checked 2026-10-26
- [Claude docs: authenticate a custom connector with request headers](https://claude.com/docs/connectors/custom/add-unlisted#authenticate-with-request-headers), checked 2026-10-26
- [MCP docs: connect to local servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers), checked 2026-10-26

## Related

- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [Break a spec into tasks for your coding agent](https://taskhold.com/guides/break-a-spec-into-agent-tasks.md)
- [Use Taskhold with Zed's agent](https://taskhold.com/integrations/zed.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

---

# Show the current Taskhold task in ccstatusline

> Add the running Taskhold task, its progress bar and current step to ccstatusline with a Custom Command widget. Exact settings, timeout and caching.

Source: https://taskhold.com/integrations/ccstatusline
Last updated: 2026-10-26

> Short answer: ccstatusline is a configurable Claude Code status line. Its Custom Command widget runs any command and shows the output, so taskhold-mcp statusline puts the task in progress, a ten-block bar and the running step next to your model, git branch and token count. Set the widget timeout to 3 seconds and a 10 second cache.

If you already run ccstatusline, you don't need Taskhold's own status line: add one widget and the line shows what your agents are doing, the same thing the [live board](https://taskhold.com/demo/live) shows in a browser. Without ccstatusline, use the [one-command status line](https://taskhold.com/docs/claude-code-status-line) instead.

## What you get

One widget in your ccstatusline layout that reads the task in progress from Taskhold and prints its title, a ten-block bar, percent done, steps done and the step that's running, for example: ▶ Deploy v2.4 to staging ███░░░░░░░ 33% 1/3 · Run migrations. With nothing in progress it reads "taskhold: nothing in progress".

## Set it up

1. Install the Taskhold CLI and save your key. It installs in ~/.taskhold, no sudo.
2. Run ccstatusline's editor, add a Custom Command widget to a line, press e and enter the command below.
3. Press t and set the timeout to 3000 ms. The default 1000 ms is shorter than Taskhold's 2.5 second fetch limit, so a slow first fetch would show [Timeout].
4. Under Configure Status Line, set Custom Command Cache TTL to 10 seconds so repaints reuse the last answer.

```bash
curl -fsSL https://taskhold.com/install.sh | sh
taskhold-mcp login
npx -y ccstatusline@latest   # opens the editor
```

Details and checksums: taskhold.com/install

```text
$HOME/.taskhold/bin/taskhold-mcp statusline
```

The widget command. ccstatusline pipes Claude Code's JSON to it on stdin; taskhold-mcp ignores it.

The editor writes ~/.config/ccstatusline/settings.json. The widget ends up looking like this, if you'd rather edit the file:

```json
{
  "customCommandCacheTtlSeconds": 10,
  "lines": [
    [
      {
        "id": "taskhold",
        "type": "custom-command",
        "commandPath": "$HOME/.taskhold/bin/taskhold-mcp statusline",
        "timeout": 3000,
        "maxWidth": 70
      }
    ]
  ]
}
```

Shortened: keep the version field and your other widgets as the editor wrote them.

Claude Code needs ccstatusline as its status line command, with a refresh interval so the line updates while you are idle and another agent is working:

```json
{
  "statusLine": {
    "type": "command",
    "command": "npx -y ccstatusline@latest",
    "padding": 0,
    "refreshInterval": 10
  }
}
```

~/.claude/settings.json. A pinned global install (command: ccstatusline) repaints faster than npx.

## One limit to know

The widget shows one task: the one Taskhold returns as in progress for your account, which is the most recently active. If three agents are running, the line shows one of them. For all of them at once, keep the live board open or run taskhold-mcp watch in a spare pane ([tmux](https://taskhold.com/integrations/tmux) works well).

## Sources

- [ccstatusline README](https://github.com/sirmalloc/ccstatusline), checked 2026-10-26
- [ccstatusline usage: Custom Command widget](https://github.com/sirmalloc/ccstatusline/blob/main/docs/USAGE.md#custom-command-widget), checked 2026-10-26
- [Claude Code docs: status line](https://code.claude.com/docs/en/statusline), checked 2026-10-26

## Related

- [ccusage and Taskhold in one Claude Code status line](https://taskhold.com/integrations/ccusage.md)
- [Show your Taskhold task in CCometixLine](https://taskhold.com/integrations/ccometixline.md)
- [Taskhold in tmux: status bar and a live board pane](https://taskhold.com/integrations/tmux.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.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

---

# ccusage and Taskhold in one status line

> Keep ccusage's cost and burn rate in the Claude Code status line and add the current Taskhold task on a second row, with one short wrapper script.

Source: https://taskhold.com/integrations/ccusage
Last updated: 2026-10-26

ccusage's status line shows session cost, burn rate and context use, and has no slot for another command's output. Claude Code shows each line a status line script prints as its own row, so a four-line wrapper gives you ccusage on top and the running Taskhold task, the one the [live board](https://taskhold.com/demo/live) shows, underneath.

Prefer one configurable line? [ccstatusline](https://taskhold.com/integrations/ccstatusline) can run both as widgets. Taskhold alone: [the status line recipe](https://taskhold.com/docs/claude-code-status-line).

## Set it up

1. Install the Taskhold CLI and save your key.
2. Save the wrapper as ~/.claude/statusline.sh and make it executable (chmod +x).
3. Point Claude Code at the wrapper in ~/.claude/settings.json.

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

```bash
#!/bin/sh
# ~/.claude/statusline.sh: ccusage on the first row, the Taskhold task on the second.
input=$(cat)
printf '%s' "$input" | bun x ccusage statusline
"$HOME/.taskhold/bin/taskhold-mcp" statusline </dev/null
```

ccusage reads Claude Code's session JSON on stdin; taskhold-mcp doesn't need it. Use npx -y ccusage statusline if you don't have Bun.

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "refreshInterval": 10
  }
}
```

## One limit to know

Claude Code cancels a status line script that is still running when the next update arrives. On a cold start, ccusage plus a Taskhold fetch can take long enough to be cancelled, and the second row stays empty until one run finishes and fills Taskhold's 10 second cache. If it keeps happening, run ccusage with --offline.

## Sources

- [ccusage docs: status line](https://github.com/ryoppippi/ccusage/blob/main/docs/guide/statusline.md), checked 2026-10-26
- [Claude Code docs: status line (multiple lines)](https://code.claude.com/docs/en/statusline), checked 2026-10-26

## Related

- [Show your Taskhold task in ccstatusline](https://taskhold.com/integrations/ccstatusline.md)
- [Show your Taskhold task in CCometixLine](https://taskhold.com/integrations/ccometixline.md)
- [See what your coding agent is doing right now](https://taskhold.com/guides/monitor-coding-agent-progress.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

---

# Show the current Taskhold task in CCometixLine

> Add the running Taskhold task and its progress to CCometixLine with a cmd metric in config.toml, cached for 10 seconds and run in the background.

Source: https://taskhold.com/integrations/ccometixline
Last updated: 2026-10-26

CCometixLine is a fast Claude Code status line written in Rust. Its cmd metric shows the first line of any command, cached and run in the background, which is exactly what taskhold-mcp statusline prints: the task in progress, its bar and the running step, the same thing the [live board](https://taskhold.com/demo/live) shows.

Using [ccstatusline](https://taskhold.com/integrations/ccstatusline) instead? It has its own page. Without either, see [the status line recipe](https://taskhold.com/docs/claude-code-status-line).

## Set it up

1. Install the Taskhold CLI and save your key.
2. Add a cmd metric to a line in ~/.claude/ccline/config.toml.

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

```toml
[[line]]
right = [
  { metric = "cmd", options = { run = "$HOME/.taskhold/bin/taskhold-mcp statusline", cache_s = 10 } },
]
```

Merge into your existing [[line]] entries; keep your other metrics on the left.

## One limit to know

CCometixLine reads only the v2 config format, and shows only the first line of the command's output. taskhold-mcp prints a single line, so nothing is lost, but a long task title is cut at 40 characters.

## Sources

- [CCometixLine README: configuration](https://github.com/Haleclipse/CCometixLine), checked 2026-10-26

## Related

- [Show your Taskhold task in ccstatusline](https://taskhold.com/integrations/ccstatusline.md)
- [ccusage and Taskhold in one Claude Code status line](https://taskhold.com/integrations/ccusage.md)
- [Show your Taskhold task in the Starship prompt](https://taskhold.com/integrations/starship.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

---

# Show the current Taskhold task in your Starship prompt

> A Starship custom module that puts the running Taskhold task and its progress bar in your shell prompt, with the timeout setting it needs.

Source: https://taskhold.com/integrations/starship
Last updated: 2026-10-26

Starship custom modules run a command and print its output in the prompt. With taskhold-mcp statusline as the command, every prompt shows the task an agent is on and how far along it is, the line the [live board](https://taskhold.com/demo/live) would give you, in any shell and any terminal, including ones with no status bar such as Ghostty.

For a bar that updates on its own, see [tmux](https://taskhold.com/integrations/tmux) or [WezTerm](https://taskhold.com/integrations/wezterm). In Claude Code itself, use [the status line recipe](https://taskhold.com/docs/claude-code-status-line).

## Set it up

1. Install the Taskhold CLI and save your key.
2. Add the module to ~/.config/starship.toml.

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

```toml
[custom.taskhold]
command = "~/.taskhold/bin/taskhold-mcp statusline"
when = true
format = "[$output]($style) "
style = "blue"
ignore_timeout = true
```

## One limit to know

Starship runs the module on every prompt and has no refresh interval of its own. Taskhold's CLI caches its answer for 10 seconds, so most prompts are instant, but a prompt after a quiet spell waits for one fetch (up to 2.5 seconds). Drop ignore_timeout if you'd rather skip the module than wait: Starship's default command_timeout of 500 ms then hides it on a slow fetch.

## Sources

- [Starship docs: custom commands](https://starship.rs/config/#custom-commands), checked 2026-10-26

## Related

- [Taskhold in tmux: status bar and a live board pane](https://taskhold.com/integrations/tmux.md)
- [Show your Taskhold task in WezTerm's tab bar](https://taskhold.com/integrations/wezterm.md)
- [Show your Taskhold task in CCometixLine](https://taskhold.com/integrations/ccometixline.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

---

# Taskhold in tmux

> Show the running Taskhold task in tmux's status bar every 10 seconds, and keep the whole live board in a pane next to your agents with taskhold-mcp watch.

Source: https://taskhold.com/integrations/tmux
Last updated: 2026-10-26

If your agents run in tmux panes, tmux can show what they are working on in two ways: the current task in the status bar, and the whole [live board](https://taskhold.com/demo/live) in a pane of its own that redraws when anything changes.

Runners built on tmux, such as [Claude Squad](https://taskhold.com/integrations/claude-squad), work the same way. For several agents on one list, see [running several agents](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list).

## Status bar

Install the Taskhold CLI, then add three lines to ~/.tmux.conf and reload it (tmux source-file ~/.tmux.conf):

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

```text
set -g status-interval 10
set -g status-right-length 90
set -g status-right '#(~/.taskhold/bin/taskhold-mcp statusline)'
```

status-right-length defaults to 40, which cuts the line short.

## A live board pane

taskhold-mcp watch draws the live board in a terminal and redraws from the event stream: tasks in progress with their bars, blocked questions, recent changes. Split a pane and run it:

```bash
tmux split-window -h -l 60 'taskhold-mcp watch'
```

## One limit to know

tmux never waits for a #() command; it shows the previous result and runs the command again in the background. The status bar can lag one interval behind, up to 10 seconds with the settings above. The watch pane follows the event stream and updates within a second or two.

## Sources

- [tmux manual page](https://man.openbsd.org/tmux.1), checked 2026-10-26

## Related

- [Use Taskhold with Claude Squad](https://taskhold.com/integrations/claude-squad.md)
- [Show your Taskhold task in ccstatusline](https://taskhold.com/integrations/ccstatusline.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Show your Taskhold task in the Starship prompt](https://taskhold.com/integrations/starship.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

---

# Show the current Taskhold task in WezTerm

> A WezTerm update-status handler that puts the running Taskhold task and its progress bar on the right of the tab bar, refreshed every 10 seconds.

Source: https://taskhold.com/integrations/wezterm
Last updated: 2026-10-26

WezTerm can print any text on the right side of its tab bar from a Lua event handler. Point it at taskhold-mcp statusline and the tab bar shows the task your agents are on and its progress, a one-line version of the [live board](https://taskhold.com/demo/live).

Other terminals: [iTerm2](https://taskhold.com/integrations/iterm2) has status bar components, and any terminal can use a [Starship](https://taskhold.com/integrations/starship) prompt module or [tmux](https://taskhold.com/integrations/tmux).

## Set it up

Install the Taskhold CLI and save your key, then add the handler to ~/.wezterm.lua:

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

```lua
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.status_update_interval = 10000
wezterm.on('update-status', function(window, pane)
  local ok, out = wezterm.run_child_process { os.getenv('HOME') .. '/.taskhold/bin/taskhold-mcp', 'statusline' }
  window:set_right_status(ok and out:gsub('%s+$', '') or '')
end)

return config
```

Merge into your existing config; keep one return config at the end.

## One limit to know

The text lives in the tab bar, so it disappears if you hide the tab bar (hide_tab_bar_if_only_one_tab = true with a single tab). WezTerm runs one update-status at a time, so a slow fetch delays the next refresh rather than piling up.

## Sources

- [WezTerm docs: update-status event](https://wezterm.org/config/lua/window-events/update-status.html), checked 2026-10-26
- [WezTerm docs: window:set_right_status](https://wezterm.org/config/lua/window/set_right_status.html), checked 2026-10-26

## Related

- [Show your Taskhold task in iTerm2's status bar](https://taskhold.com/integrations/iterm2.md)
- [Show your Taskhold task in the Starship prompt](https://taskhold.com/integrations/starship.md)
- [Taskhold in tmux: status bar and a live board pane](https://taskhold.com/integrations/tmux.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

---

# Show the current Taskhold task in iTerm2

> Put the running Taskhold task in iTerm2's status bar with a user variable and an Interpolated String component, or a self-refreshing Python one.

Source: https://taskhold.com/integrations/iterm2
Last updated: 2026-10-26

iTerm2's status bar can show a value your shell sets. Set it from taskhold-mcp statusline and every session shows the task in progress and its bar, a glance at the [live board](https://taskhold.com/demo/live) without leaving the terminal.

Also see [WezTerm](https://taskhold.com/integrations/wezterm), [Starship](https://taskhold.com/integrations/starship) and [tmux](https://taskhold.com/integrations/tmux).

## Set it up with a user variable

1. Install the Taskhold CLI and save your key.
2. Install iTerm2's shell integration (iTerm2 > Install Shell Integration).
3. Add the function below to ~/.zshrc (or ~/.bashrc).
4. In Settings > Profiles > Session, turn on the status bar, click Configure Status Bar, drag in an Interpolated String component and set its value to \(user.taskhold).

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

```bash
iterm2_print_user_vars() {
  iterm2_set_user_var taskhold "$(~/.taskhold/bin/taskhold-mcp statusline)"
}
```

## One limit to know

Shell integration sets user variables when a prompt is drawn. While an agent holds the terminal, no prompt is drawn and the value stays where it was. For a value that refreshes on its own, write a status bar component with iTerm2's Python API (iterm2.StatusBarComponent with update_cadence=10) that runs the same command.

## Sources

- [iTerm2 docs: scripting fundamentals (user variables)](https://iterm2.com/documentation-scripting-fundamentals.html), checked 2026-10-26
- [iTerm2 Python API: status bar components](https://iterm2.com/python-api/statusbar.html), checked 2026-10-26

## Related

- [Show your Taskhold task in WezTerm's tab bar](https://taskhold.com/integrations/wezterm.md)
- [Taskhold in the Mac menu bar with SwiftBar or xbar](https://taskhold.com/integrations/swiftbar.md)
- [Show your Taskhold task in the Starship prompt](https://taskhold.com/integrations/starship.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

---

# Taskhold in the Mac menu bar

> A five-line SwiftBar or xbar plugin that shows the running Taskhold task and its progress in the macOS menu bar, with a link to the live board.

Source: https://taskhold.com/integrations/swiftbar
Last updated: 2026-10-26

SwiftBar and xbar turn any script's output into a menu bar item. This plugin shows the task your agents are on and how far along it is, refreshes every 10 seconds, and opens the [live board](https://taskhold.com/demo/live) when you click it.

Raycast users can get the same line in Raycast instead: see [Raycast](https://taskhold.com/integrations/raycast). For alerts rather than a glance, see [macOS notifications](https://taskhold.com/integrations/macos-notifications).

## Set it up

1. Install the Taskhold CLI and save your key with taskhold-mcp login. Menu bar apps don't see your shell's variables, so the saved key matters.
2. Save the plugin as taskhold.10s.sh in your SwiftBar (or xbar) plugin folder. The 10s in the name is the refresh interval.
3. Make it executable: chmod +x taskhold.10s.sh. SwiftBar picks it up right away; in xbar, choose Refresh all.

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

```bash
#!/bin/bash
# <xbar.title>Taskhold</xbar.title>
"$HOME/.taskhold/bin/taskhold-mcp" statusline </dev/null
echo "---"
echo "Open live board | href=https://taskhold.com/dashboard/live"
```

## One limit to know

SwiftBar and xbar read a | in the first line as the start of display options, so a task title with a | in it is cut short in the menu bar. xbar itself has had no release since 2021; SwiftBar is maintained and reads the same plugins.

## Sources

- [SwiftBar README](https://github.com/swiftbar/SwiftBar), checked 2026-10-26
- [xbar plugin guide](https://github.com/matryer/xbar-plugins/blob/main/CONTRIBUTING.md), checked 2026-10-26

## Related

- [Show your Taskhold task in Raycast](https://taskhold.com/integrations/raycast.md)
- [Mac notifications when a coding agent is blocked](https://taskhold.com/integrations/macos-notifications.md)
- [Show your Taskhold task in iTerm2's status bar](https://taskhold.com/integrations/iterm2.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

---

# Show the current Taskhold task in Raycast

> A Raycast inline Script Command that shows the running Taskhold task and its progress bar in Raycast's root search, refreshed every 10 seconds.

Source: https://taskhold.com/integrations/raycast
Last updated: 2026-10-26

Raycast Script Commands in inline mode show the first line of a script's output right in the command list and refresh it on a timer. With taskhold-mcp statusline, Raycast shows what your agents are doing every time you open it, a pocket version of the [live board](https://taskhold.com/demo/live).

Want it in the menu bar instead? See [SwiftBar and xbar](https://taskhold.com/integrations/swiftbar). For alerts, see [ntfy](https://taskhold.com/integrations/ntfy).

## Set it up

1. Install the Taskhold CLI and save your key with taskhold-mcp login.
2. Save the script below as taskhold.sh in a folder, make it executable, and add that folder in Raycast under Settings > Extensions > Script Commands.
3. Add the command to your favorites so it stays visible.

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

```bash
#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Taskhold
# @raycast.mode inline
# @raycast.refreshTime 10s
# @raycast.packageName Taskhold
"$HOME/.taskhold/bin/taskhold-mcp" statusline </dev/null
```

## One limit to know

The line lives in Raycast's window, not the macOS menu bar, so you see it when you open Raycast. Raycast refreshes at most the first 10 inline commands automatically, and 10 seconds is its shortest interval.

## Sources

- [Raycast Script Commands README](https://github.com/raycast/script-commands), checked 2026-10-26
- [Raycast Script Commands: output modes](https://github.com/raycast/script-commands/blob/master/documentation/OUTPUTMODES.md), checked 2026-10-26

## Related

- [Taskhold in the Mac menu bar with SwiftBar or xbar](https://taskhold.com/integrations/swiftbar.md)
- [Phone alerts from Taskhold with ntfy](https://taskhold.com/integrations/ntfy.md)
- [Mac notifications when a coding agent is blocked](https://taskhold.com/integrations/macos-notifications.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

---

# Phone alerts for blocked and finished tasks with ntfy

> Get an ntfy push on your phone when a coding agent blocks a Taskhold task or finishes one, with a tap-through to the live board. One bash script.

Source: https://taskhold.com/integrations/ntfy
Last updated: 2026-10-26

The [live board](https://taskhold.com/demo/live) sends desktop notifications while it is open. For your phone with the board closed, this script follows Taskhold's event stream and publishes to an ntfy topic: high priority when an agent needs you, normal when it finishes. Tap the notification to open the board and reply.

Prefer Slack? See [Slack alerts](https://taskhold.com/docs/slack-alerts). Answering from the phone is covered in [answering a blocked coding agent](https://taskhold.com/guides/answer-a-blocked-coding-agent).

## What you get

One ntfy message when an agent blocks a task with a question, and one when it finishes a whole task (not each step). Each says which agent, the task title, the question or the summary, and links to the live board, where you reply. Your own changes never trigger a message.

## Before you begin

- The ntfy app on your phone, subscribed to a topic name nobody would guess (topics on ntfy.sh are public to anyone who knows the name).
- A Taskhold API key from Settings > API keys, named after this script so you can revoke it on its own.
- bash, curl and jq on the machine that runs the script.

## The script

Save this as taskhold-ntfy.sh and make it executable (chmod +x). The top half is the ntfy part; the loop below it is the same for every notifier.

```bash
#!/bin/bash
# taskhold-ntfy.sh: push to ntfy when an agent blocks or finishes a Taskhold task.
# Needs curl and jq. Run: TASKHOLD_API_KEY=atd_sk_... ./taskhold-ntfy.sh
key=${TASKHOLD_API_KEY:?set TASKHOLD_API_KEY}
board=https://taskhold.com/dashboard/live
last=""

topic=${NTFY_TOPIC:?set NTFY_TOPIC}
notify() { # kind, title, detail, agent
  if [ "$1" = blocked ]; then t="$4 needs you: $2"; p=high; tag=warning
  else t="$4 finished: $2"; p=default; tag=white_check_mark; fi
  curl -s -o /dev/null -H "Title: $t" -H "Priority: $p" -H "Tags: $tag" -H "Click: $board" \
    --data-raw "${3:-No details}" "https://ntfy.sh/$topic"
}

while :; do
  while IFS= read -r line; do
    case "$line" in
      "id: "*) last=${line#id: } ;;
      "data: "*)
        e=${line#data: }
        # Agents only: a task (not a step) finished, or any task or step blocked.
        jq -e '.type == "task.status" and .actor == "agent" and (.data.to == "blocked" or (.data.to == "done" and .task_id == .root_task_id))' <<<"$e" >/dev/null || continue
        kind=$(jq -r .data.to <<<"$e")
        title=$(jq -r '.task_title // "a task"' <<<"$e")
        agent=$(jq -r '.actor_name // "An agent"' <<<"$e")
        detail=$(jq -r 'if .data.to == "blocked" then .data.blocked_reason else .data.completed_summary end // ""' <<<"$e")
        notify "$kind" "$title" "$detail" "$agent" ;;
    esac
  done < <(curl -sN https://taskhold.com/api/events/stream -H "Authorization: Bearer $key" ${last:+-H "Last-Event-ID: $last"})
  sleep 3
done
```

Run it anywhere a process can stay up, such as a spare terminal, a tmux window or a small server:

```bash
NTFY_TOPIC=taskhold-7f3k2q TASKHOLD_API_KEY=atd_sk_... ./taskhold-ntfy.sh
```

The server ends each stream after 10 minutes and the script reconnects with the last event id, so events that happen in between arrive once, in order. Details on the stream: [events and the live stream](https://taskhold.com/docs/events).

## One limit to know

ntfy.sh caps anonymous publishing (250 messages a day at the time of writing), which a busy day of agents won't reach, and anyone who learns the topic name can read your task titles. Use a long random topic, or your own ntfy server with an access token (add -H "Authorization: Bearer tk_..." to the curl line).

## Sources

- [ntfy docs: publishing](https://docs.ntfy.sh/publish/), checked 2026-10-26

## Related

- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [Pushover alerts when a coding agent needs you](https://taskhold.com/integrations/pushover.md)
- [Discord alerts when a coding agent is blocked](https://taskhold.com/integrations/discord.md)
- [Telegram messages when a coding agent needs you](https://taskhold.com/integrations/telegram.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

---

# Pushover alerts for blocked and finished tasks

> A bash script that sends a Pushover notification when an agent blocks or finishes a Taskhold task, high priority for questions, linked to the live board.

Source: https://taskhold.com/integrations/pushover
Last updated: 2026-10-26

Pushover delivers reliable notifications to phones, watches and desktops. This script follows Taskhold's event stream and sends one when an agent needs an answer (high priority, so it breaks through quiet hours if you allow that) and one when it finishes a task. The notification links to the [live board](https://taskhold.com/demo/live).

Other channels: [ntfy](https://taskhold.com/integrations/ntfy), [Slack](https://taskhold.com/docs/slack-alerts), [Discord](https://taskhold.com/integrations/discord).

## What you get

One Pushover message when an agent blocks a task with a question, and one when it finishes a whole task (not each step). Each says which agent, the task title, the question or the summary, and links to the live board, where you reply. Your own changes never trigger a message.

## Before you begin

- A Pushover account and your user key.
- A Pushover application token: create an application named Taskhold on pushover.net.
- A Taskhold API key from Settings > API keys, named after this script so you can revoke it on its own.
- bash, curl and jq on the machine that runs the script.

## The script

Save this as taskhold-pushover.sh and make it executable (chmod +x). The top half is the Pushover part; the loop below it is the same for every notifier.

```bash
#!/bin/bash
# taskhold-pushover.sh: send a Pushover notification when an agent blocks or finishes a Taskhold task.
# Needs curl and jq. Run: TASKHOLD_API_KEY=atd_sk_... ./taskhold-pushover.sh
key=${TASKHOLD_API_KEY:?set TASKHOLD_API_KEY}
board=https://taskhold.com/dashboard/live
last=""

: "${PUSHOVER_TOKEN:?set PUSHOVER_TOKEN}" "${PUSHOVER_USER:?set PUSHOVER_USER}"
notify() { # kind, title, detail, agent
  if [ "$1" = blocked ]; then t="$4 needs you"; pr=1; else t="$4 finished a task"; pr=0; fi
  curl -s -o /dev/null --form-string "token=$PUSHOVER_TOKEN" --form-string "user=$PUSHOVER_USER" \
    --form-string "title=$t" --form-string "message=$2${3:+: $3}" --form-string "priority=$pr" \
    --form-string "url=$board" --form-string "url_title=Open the live board" \
    https://api.pushover.net/1/messages.json
}

while :; do
  while IFS= read -r line; do
    case "$line" in
      "id: "*) last=${line#id: } ;;
      "data: "*)
        e=${line#data: }
        # Agents only: a task (not a step) finished, or any task or step blocked.
        jq -e '.type == "task.status" and .actor == "agent" and (.data.to == "blocked" or (.data.to == "done" and .task_id == .root_task_id))' <<<"$e" >/dev/null || continue
        kind=$(jq -r .data.to <<<"$e")
        title=$(jq -r '.task_title // "a task"' <<<"$e")
        agent=$(jq -r '.actor_name // "An agent"' <<<"$e")
        detail=$(jq -r 'if .data.to == "blocked" then .data.blocked_reason else .data.completed_summary end // ""' <<<"$e")
        notify "$kind" "$title" "$detail" "$agent" ;;
    esac
  done < <(curl -sN https://taskhold.com/api/events/stream -H "Authorization: Bearer $key" ${last:+-H "Last-Event-ID: $last"})
  sleep 3
done
```

Run it anywhere a process can stay up, such as a spare terminal, a tmux window or a small server:

```bash
PUSHOVER_TOKEN=a... PUSHOVER_USER=u... TASKHOLD_API_KEY=atd_sk_... ./taskhold-pushover.sh
```

The server ends each stream after 10 minutes and the script reconnects with the last event id, so events that happen in between arrive once, in order. Details on the stream: [events and the live stream](https://taskhold.com/docs/events).

## One limit to know

Pushover is a paid app after its own trial, and its application tokens have a monthly message allowance. One message per blocked or finished task stays far below it, but don't widen the filter to progress events.

## Sources

- [Pushover API](https://pushover.net/api), checked 2026-10-26

## Related

- [Phone alerts from Taskhold with ntfy](https://taskhold.com/integrations/ntfy.md)
- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [Mac notifications when a coding agent is blocked](https://taskhold.com/integrations/macos-notifications.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

---

# Discord alerts for blocked and finished tasks

> Post to a Discord channel through a webhook when a coding agent blocks a Taskhold task or finishes one, with the question or summary and a board link.

Source: https://taskhold.com/integrations/discord
Last updated: 2026-10-26

If your team talks in Discord, this script posts there when an agent needs a decision or finishes a task, so whoever is around can open the [live board](https://taskhold.com/demo/live) and answer. It uses a channel webhook, no bot.

For Slack, see [Slack alerts](https://taskhold.com/docs/slack-alerts); for a team running several agents, see [one list for several agents](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list).

## What you get

One Discord message when an agent blocks a task with a question, and one when it finishes a whole task (not each step). Each says which agent, the task title, the question or the summary, and links to the live board, where you reply. Your own changes never trigger a message.

## Before you begin

- A Discord webhook URL: Server Settings > Integrations > Webhooks > New Webhook, pick the channel, Copy Webhook URL.
- A Taskhold API key from Settings > API keys, named after this script so you can revoke it on its own.
- bash, curl and jq on the machine that runs the script.

## The script

Save this as taskhold-discord.sh and make it executable (chmod +x). The top half is the Discord part; the loop below it is the same for every notifier.

```bash
#!/bin/bash
# taskhold-discord.sh: post to a Discord channel when an agent blocks or finishes a Taskhold task.
# Needs curl and jq. Run: TASKHOLD_API_KEY=atd_sk_... ./taskhold-discord.sh
key=${TASKHOLD_API_KEY:?set TASKHOLD_API_KEY}
board=https://taskhold.com/dashboard/live
last=""

hook=${DISCORD_WEBHOOK_URL:?set DISCORD_WEBHOOK_URL}
notify() { # kind, title, detail, agent
  if [ "$1" = blocked ]; then h="**$4 needs you**"; else h="**$4 finished a task**"; fi
  text=$(printf '%s\n%s\n%s\n%s' "$h" "$2" "${3:+> $3}" "$board")
  jq -n --arg c "$text" '{username: "Taskhold", content: $c[0:2000], allowed_mentions: {parse: []}}' \
    | curl -s -o /dev/null -H "Content-Type: application/json" -d @- "$hook"
}

while :; do
  while IFS= read -r line; do
    case "$line" in
      "id: "*) last=${line#id: } ;;
      "data: "*)
        e=${line#data: }
        # Agents only: a task (not a step) finished, or any task or step blocked.
        jq -e '.type == "task.status" and .actor == "agent" and (.data.to == "blocked" or (.data.to == "done" and .task_id == .root_task_id))' <<<"$e" >/dev/null || continue
        kind=$(jq -r .data.to <<<"$e")
        title=$(jq -r '.task_title // "a task"' <<<"$e")
        agent=$(jq -r '.actor_name // "An agent"' <<<"$e")
        detail=$(jq -r 'if .data.to == "blocked" then .data.blocked_reason else .data.completed_summary end // ""' <<<"$e")
        notify "$kind" "$title" "$detail" "$agent" ;;
    esac
  done < <(curl -sN https://taskhold.com/api/events/stream -H "Authorization: Bearer $key" ${last:+-H "Last-Event-ID: $last"})
  sleep 3
done
```

Run it anywhere a process can stay up, such as a spare terminal, a tmux window or a small server:

```bash
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... TASKHOLD_API_KEY=atd_sk_... ./taskhold-discord.sh
```

The server ends each stream after 10 minutes and the script reconnects with the last event id, so events that happen in between arrive once, in order. Details on the stream: [events and the live stream](https://taskhold.com/docs/events).

## One limit to know

The webhook URL is the only credential: anyone who has it can post to that channel. Keep it out of shell history and repositories, and delete and recreate the webhook in Discord if it leaks. allowed_mentions is empty so a task title can't ping @everyone.

## Sources

- [Discord developer docs: execute webhook](https://docs.discord.com/developers/resources/webhook#execute-webhook), checked 2026-10-26

## Related

- [Phone alerts from Taskhold with ntfy](https://taskhold.com/integrations/ntfy.md)
- [Microsoft Teams alerts for blocked coding agents](https://taskhold.com/integrations/microsoft-teams.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.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

---

# Telegram messages for blocked and finished tasks

> A Telegram bot message when a coding agent blocks a Taskhold task or finishes one: a bash script on the events stream and the Bot API's sendMessage.

Source: https://taskhold.com/integrations/telegram
Last updated: 2026-10-26

A Telegram bot is a quick way to get agent questions on your phone. This script follows Taskhold's event stream and messages you through your own bot when an agent blocks or finishes a task, with a link to the [live board](https://taskhold.com/demo/live) where you reply.

Other channels: [ntfy](https://taskhold.com/integrations/ntfy), [Pushover](https://taskhold.com/integrations/pushover), [Slack](https://taskhold.com/docs/slack-alerts).

## What you get

One Telegram message when an agent blocks a task with a question, and one when it finishes a whole task (not each step). Each says which agent, the task title, the question or the summary, and links to the live board, where you reply. Your own changes never trigger a message.

## Before you begin

- A bot token from @BotFather (/newbot).
- Your chat id: send your bot any message, then open https://api.telegram.org/bot<token>/getUpdates and read message.chat.id.
- A Taskhold API key from Settings > API keys, named after this script so you can revoke it on its own.
- bash, curl and jq on the machine that runs the script.

## The script

Save this as taskhold-telegram.sh and make it executable (chmod +x). The top half is the Telegram part; the loop below it is the same for every notifier.

```bash
#!/bin/bash
# taskhold-telegram.sh: message you on Telegram when an agent blocks or finishes a Taskhold task.
# Needs curl and jq. Run: TASKHOLD_API_KEY=atd_sk_... ./taskhold-telegram.sh
key=${TASKHOLD_API_KEY:?set TASKHOLD_API_KEY}
board=https://taskhold.com/dashboard/live
last=""

: "${TELEGRAM_BOT_TOKEN:?set TELEGRAM_BOT_TOKEN}" "${TELEGRAM_CHAT_ID:?set TELEGRAM_CHAT_ID}"
notify() { # kind, title, detail, agent
  if [ "$1" = blocked ]; then h="$4 needs you"; else h="$4 finished a task"; fi
  curl -s -o /dev/null "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
    -d "chat_id=$TELEGRAM_CHAT_ID" \
    --data-urlencode "text=$(printf '%s\n%s\n%s\n%s' "$h" "$2" "$3" "$board" | cut -c1-4000)"
}

while :; do
  while IFS= read -r line; do
    case "$line" in
      "id: "*) last=${line#id: } ;;
      "data: "*)
        e=${line#data: }
        # Agents only: a task (not a step) finished, or any task or step blocked.
        jq -e '.type == "task.status" and .actor == "agent" and (.data.to == "blocked" or (.data.to == "done" and .task_id == .root_task_id))' <<<"$e" >/dev/null || continue
        kind=$(jq -r .data.to <<<"$e")
        title=$(jq -r '.task_title // "a task"' <<<"$e")
        agent=$(jq -r '.actor_name // "An agent"' <<<"$e")
        detail=$(jq -r 'if .data.to == "blocked" then .data.blocked_reason else .data.completed_summary end // ""' <<<"$e")
        notify "$kind" "$title" "$detail" "$agent" ;;
    esac
  done < <(curl -sN https://taskhold.com/api/events/stream -H "Authorization: Bearer $key" ${last:+-H "Last-Event-ID: $last"})
  sleep 3
done
```

Run it anywhere a process can stay up, such as a spare terminal, a tmux window or a small server:

```bash
TELEGRAM_BOT_TOKEN=123:abc TELEGRAM_CHAT_ID=42 TASKHOLD_API_KEY=atd_sk_... ./taskhold-telegram.sh
```

The server ends each stream after 10 minutes and the script reconnects with the last event id, so events that happen in between arrive once, in order. Details on the stream: [events and the live stream](https://taskhold.com/docs/events).

## One limit to know

The bot can only message you after you have messaged it first, which is also how you find the chat id. Replies you type to the bot go nowhere: answer on the board, where the agent reads them.

## Sources

- [Telegram Bot API: sendMessage](https://core.telegram.org/bots/api#sendmessage), checked 2026-10-26

## Related

- [Phone alerts from Taskhold with ntfy](https://taskhold.com/integrations/ntfy.md)
- [Pushover alerts when a coding agent needs you](https://taskhold.com/integrations/pushover.md)
- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.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

---

# Mac notifications for blocked and finished tasks

> Native macOS notifications when a coding agent blocks or finishes a Taskhold task, even with the board closed, using terminal-notifier and one bash script.

Source: https://taskhold.com/integrations/macos-notifications
Last updated: 2026-10-26

The [live board](https://taskhold.com/demo/live) can send desktop notifications, but only while its tab is open. This script runs in a terminal and posts a native macOS notification whenever an agent blocks or finishes a task; clicking it opens the board.

Want a glance instead of an alert? See [the menu bar plugin](https://taskhold.com/integrations/swiftbar). Away from the Mac, use [ntfy](https://taskhold.com/integrations/ntfy).

## What you get

One macOS notifications message when an agent blocks a task with a question, and one when it finishes a whole task (not each step). Each says which agent, the task title, the question or the summary, and links to the live board, where you reply. Your own changes never trigger a message.

## Before you begin

- terminal-notifier: brew install terminal-notifier.
- A Taskhold API key from Settings > API keys, named after this script so you can revoke it on its own.
- bash, curl and jq on the machine that runs the script.

## The script

Save this as taskhold-mac.sh and make it executable (chmod +x). The top half is the macOS notifications part; the loop below it is the same for every notifier.

```bash
#!/bin/bash
# taskhold-mac.sh: show a macOS notification when an agent blocks or finishes a Taskhold task.
# Needs curl and jq. Run: TASKHOLD_API_KEY=atd_sk_... ./taskhold-mac.sh
key=${TASKHOLD_API_KEY:?set TASKHOLD_API_KEY}
board=https://taskhold.com/dashboard/live
last=""

notify() { # kind, title, detail, agent
  if [ "$1" = blocked ]; then h="$4 needs you"; else h="$4 finished a task"; fi
  terminal-notifier -title Taskhold -subtitle "$h" -message "$2${3:+: $3}" \
    -group "taskhold-$1" -open "$board"
}

while :; do
  while IFS= read -r line; do
    case "$line" in
      "id: "*) last=${line#id: } ;;
      "data: "*)
        e=${line#data: }
        # Agents only: a task (not a step) finished, or any task or step blocked.
        jq -e '.type == "task.status" and .actor == "agent" and (.data.to == "blocked" or (.data.to == "done" and .task_id == .root_task_id))' <<<"$e" >/dev/null || continue
        kind=$(jq -r .data.to <<<"$e")
        title=$(jq -r '.task_title // "a task"' <<<"$e")
        agent=$(jq -r '.actor_name // "An agent"' <<<"$e")
        detail=$(jq -r 'if .data.to == "blocked" then .data.blocked_reason else .data.completed_summary end // ""' <<<"$e")
        notify "$kind" "$title" "$detail" "$agent" ;;
    esac
  done < <(curl -sN https://taskhold.com/api/events/stream -H "Authorization: Bearer $key" ${last:+-H "Last-Event-ID: $last"})
  sleep 3
done
```

Run it anywhere a process can stay up, such as a spare terminal, a tmux window or a small server:

```bash
TASKHOLD_API_KEY=atd_sk_... ./taskhold-mac.sh
```

The server ends each stream after 10 minutes and the script reconnects with the last event id, so events that happen in between arrive once, in order. Details on the stream: [events and the live stream](https://taskhold.com/docs/events).

## One limit to know

Notifications only arrive while the Mac is awake and the script is running. After sleep the script reconnects from the last event it saw and catches up, but a restarted script starts from now. -group replaces the previous notification of the same kind, so a burst of finished tasks shows as one, the latest. Without terminal-notifier, osascript -e 'display notification ...' works too, but clicking it doesn't open the board.

## Sources

- [terminal-notifier README](https://github.com/julienXX/terminal-notifier), checked 2026-10-26
- [Apple: displaying notifications from scripts](https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/DisplayNotifications.html), checked 2026-10-26

## Related

- [Taskhold in the Mac menu bar with SwiftBar or xbar](https://taskhold.com/integrations/swiftbar.md)
- [Phone alerts from Taskhold with ntfy](https://taskhold.com/integrations/ntfy.md)
- [Show your Taskhold task in Raycast](https://taskhold.com/integrations/raycast.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

---

# Microsoft Teams alerts for blocked and finished tasks

> Post an Adaptive Card to a Teams channel through a Workflows webhook when a coding agent blocks or finishes a Taskhold task. One bash script.

Source: https://taskhold.com/integrations/microsoft-teams
Last updated: 2026-10-26

Teams retired Office 365 connector webhooks in 2026; channel webhooks now come from Workflows. This script follows Taskhold's event stream and posts an Adaptive Card to a channel through one of those when an agent needs a decision or finishes a task, with a link to the [live board](https://taskhold.com/demo/live).

Teams of people running agents together: see [several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list). Slack users: [Slack alerts](https://taskhold.com/docs/slack-alerts).

## What you get

One Microsoft Teams message when an agent blocks a task with a question, and one when it finishes a whole task (not each step). Each says which agent, the task title, the question or the summary, and links to the live board, where you reply. Your own changes never trigger a message.

## Before you begin

- A Workflows webhook URL: in the channel, open ... > Workflows, choose the template "Send webhook alerts to a channel", finish the steps and copy the URL.
- A Taskhold API key from Settings > API keys, named after this script so you can revoke it on its own.
- bash, curl and jq on the machine that runs the script.

## The script

Save this as taskhold-teams.sh and make it executable (chmod +x). The top half is the Microsoft Teams part; the loop below it is the same for every notifier.

```bash
#!/bin/bash
# taskhold-teams.sh: post to a Teams channel when an agent blocks or finishes a Taskhold task.
# Needs curl and jq. Run: TASKHOLD_API_KEY=atd_sk_... ./taskhold-teams.sh
key=${TASKHOLD_API_KEY:?set TASKHOLD_API_KEY}
board=https://taskhold.com/dashboard/live
last=""

hook=${TEAMS_WORKFLOW_URL:?set TEAMS_WORKFLOW_URL}
notify() { # kind, title, detail, agent
  if [ "$1" = blocked ]; then h="$4 needs you"; else h="$4 finished a task"; fi
  jq -n --arg h "$h" --arg t "$2" --arg d "${3:- }" --arg u "$board" '{type: "message", attachments: [{
    contentType: "application/vnd.microsoft.card.adaptive",
    content: {type: "AdaptiveCard", version: "1.2", body: [
      {type: "TextBlock", text: $h, weight: "Bolder", wrap: true},
      {type: "TextBlock", text: $t, wrap: true},
      {type: "TextBlock", text: $d, wrap: true, isSubtle: true},
      {type: "TextBlock", text: ("[Open the live board](" + $u + ")"), wrap: true}]}}]}' \
    | curl -s -o /dev/null -H "Content-Type: application/json" -d @- "$hook"
}

while :; do
  while IFS= read -r line; do
    case "$line" in
      "id: "*) last=${line#id: } ;;
      "data: "*)
        e=${line#data: }
        # Agents only: a task (not a step) finished, or any task or step blocked.
        jq -e '.type == "task.status" and .actor == "agent" and (.data.to == "blocked" or (.data.to == "done" and .task_id == .root_task_id))' <<<"$e" >/dev/null || continue
        kind=$(jq -r .data.to <<<"$e")
        title=$(jq -r '.task_title // "a task"' <<<"$e")
        agent=$(jq -r '.actor_name // "An agent"' <<<"$e")
        detail=$(jq -r 'if .data.to == "blocked" then .data.blocked_reason else .data.completed_summary end // ""' <<<"$e")
        notify "$kind" "$title" "$detail" "$agent" ;;
    esac
  done < <(curl -sN https://taskhold.com/api/events/stream -H "Authorization: Bearer $key" ${last:+-H "Last-Event-ID: $last"})
  sleep 3
done
```

Run it anywhere a process can stay up, such as a spare terminal, a tmux window or a small server:

```bash
TEAMS_WORKFLOW_URL='https://...' TASKHOLD_API_KEY=atd_sk_... ./taskhold-teams.sh
```

The server ends each stream after 10 minutes and the script reconnects with the last event id, so events that happen in between arrive once, in order. Details on the stream: [events and the live stream](https://taskhold.com/docs/events).

## One limit to know

A workflow belongs to the person who created it. If they leave the organization or lose access, the webhook stops and nothing posts. Create it from a shared or service account if the channel matters.

## Sources

- [Microsoft Learn: create incoming webhooks with Workflows](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook), checked 2026-10-26
- [Microsoft 365 Developer Blog: retirement of Office 365 connectors](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/), checked 2026-10-26

## Related

- [Discord alerts when a coding agent is blocked](https://taskhold.com/integrations/discord.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Phone alerts from Taskhold with ntfy](https://taskhold.com/integrations/ntfy.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

---

# File a Taskhold task when a GitHub Actions run fails

> One GitHub Actions step that files a high-priority Taskhold task with the logs link when a workflow fails, so your coding agent picks up the fix.

Source: https://taskhold.com/integrations/github-actions
Last updated: 2026-10-26

A red build is work for your agent. This step runs only when an earlier step failed and files a Taskhold task with the run's link, so the next agent session sees it at the top of the queue and the [live board](https://taskhold.com/demo/live) shows who picks it up.

To show a whole deploy's stages as live progress instead, use the [CI progress recipe](https://taskhold.com/docs/ci-progress). GitLab: [GitLab CI](https://taskhold.com/integrations/gitlab-ci).

## Set it up

1. Create an API key in Taskhold named after the repository, for example "CI acme/api".
2. Add it to the repository as the Actions secret TASKHOLD_API_KEY.
3. Add this step at the end of the job you care about.

```yaml
      - name: File a Taskhold task if this run failed
        if: ${{ failure() }}
        env:
          TASKHOLD_API_KEY: ${{ secrets.TASKHOLD_API_KEY }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          jq -n --arg t "Fix failing ${{ github.workflow }} on ${GITHUB_REF_NAME}" \
                --arg d "Run: $RUN_URL (commit ${GITHUB_SHA::7})" \
                '{title: $t, description: $d, priority: "high", labels: ["ci"]}' \
          | curl -sf https://taskhold.com/api/tasks -H "Authorization: Bearer $TASKHOLD_API_KEY" \
              -H "X-Taskhold-Agent: GitHub Actions" -H "Content-Type: application/json" -d @-
```

failure() is true when any earlier step in the job failed. jq builds the JSON so branch names with quotes can't break it.

## What your agent sees

A todo titled "Fix failing CI on main" with the run link in the description, marked as added by GitHub Actions. With the [task workflow](https://taskhold.com/guides/claude-md-task-workflow) in CLAUDE.md or AGENTS.md, the next session takes the highest-priority todo, which is this one.

## One limit to know

Every failed run files a new task, so a flaky test that fails five times files five. Put the step only on the branch that matters (if: ${{ failure() && github.ref == 'refs/heads/main' }}), or close duplicates from the board.

## Sources

- [GitHub docs: expressions, failure()](https://docs.github.com/en/actions/reference/workflows-and-actions/expressions), checked 2026-10-26

## Related

- [File a Taskhold task when a GitLab pipeline fails](https://taskhold.com/integrations/gitlab-ci.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [Use Taskhold with GitHub Copilot's cloud agent](https://taskhold.com/integrations/copilot-coding-agent.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

---

# File a Taskhold task when a GitLab pipeline fails

> A GitLab CI job that runs only when the pipeline fails and files a high-priority Taskhold task with the pipeline link for your coding agent to pick up.

Source: https://taskhold.com/integrations/gitlab-ci
Last updated: 2026-10-26

When a pipeline goes red, this job files a Taskhold task with the pipeline link. Your coding agent finds it at the top of the queue on its next session, and the [live board](https://taskhold.com/demo/live) shows it being worked on.

The same idea on GitHub: [GitHub Actions](https://taskhold.com/integrations/github-actions). For stage-by-stage deploy progress, adapt the curl calls from the [CI progress recipe](https://taskhold.com/docs/ci-progress).

## Set it up

1. Create an API key in Taskhold named after the project.
2. In GitLab, open Settings > CI/CD > Variables, add TASKHOLD_API_KEY with the key and set Visibility to Masked. atd_sk_ keys meet GitLab's masking rules.
3. Add the job to .gitlab-ci.yml. It runs in the .post stage, only when a job in an earlier stage failed.

```yaml
taskhold_on_failure:
  stage: .post
  when: on_failure
  image: alpine:3.20
  script:
    - apk add --no-cache curl jq
    - >
      jq -n --arg t "Fix failing pipeline on $CI_COMMIT_REF_NAME"
      --arg d "Pipeline: $CI_PIPELINE_URL (commit $CI_COMMIT_SHORT_SHA)"
      '{title: $t, description: $d, priority: "high", labels: ["ci"]}'
      | curl -sf https://taskhold.com/api/tasks -H "Authorization: Bearer $TASKHOLD_API_KEY"
      -H "X-Taskhold-Agent: GitLab CI" -H "Content-Type: application/json" -d @-
```

## One limit to know

Every failed pipeline files a new task, so a flaky job can file several. Add rules to the job (for example, only on the default branch) or close duplicates from the board. A masked variable is still visible to anyone who can edit the pipeline, so use a key you can revoke on its own.

## Sources

- [GitLab docs: CI/CD YAML syntax (when: on_failure)](https://docs.gitlab.com/ci/yaml/), checked 2026-10-26
- [GitLab docs: mask a CI/CD variable](https://docs.gitlab.com/ci/variables/#mask-a-cicd-variable), checked 2026-10-26

## Related

- [File a Taskhold task when GitHub Actions fails](https://taskhold.com/integrations/github-actions.md)
- [How to hand tasks to your coding agent](https://taskhold.com/guides/hand-tasks-to-your-coding-agent.md)
- [Turn TODO comments into tasks your agent can do](https://taskhold.com/guides/turn-code-todos-into-tasks.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

---

# Use Taskhold with Claude Squad

> Run several Claude Code or Codex sessions with Claude Squad and see what each is doing on one Taskhold board, labelled by branch, blocked ones first.

Source: https://taskhold.com/integrations/claude-squad
Last updated: 2026-10-26

> Short answer: Claude Squad runs each agent session in its own tmux session and git worktree. Taskhold adds one list they all work from and a live board that shows which session is on which task, how far along it is and which one is waiting on you. Set it up once with a user-scope MCP server and a committed CLAUDE.md.

Claude Squad is good at running many agents side by side; switching between them to find the one that's stuck is the slow part. With Taskhold, every session reports into one [live board](https://taskhold.com/demo/live): its plan, its current step and its questions, labelled with its branch.

The general pattern is in [running several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list).

## What you get

- Each session takes a different task: one an agent has started shows as in progress, so the next session takes the next one.
- One card per session on the live board, labelled with its branch, with its steps, progress and last message.
- Sessions that need you listed first under Needs you, so you know which one to switch to in Claude Squad.

## Set it up

Claude Squad starts the normal claude (or codex, gemini) command in a new worktree for every session, so two things must be true for each session to see Taskhold:

1. The MCP server is configured at user scope, not per project. A project-local Claude Code server is stored against the original folder path and doesn't follow a new worktree.
2. The workflow lives in a CLAUDE.md or AGENTS.md that is committed. Worktrees only contain tracked files.

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

Codex sessions (cs -p codex) read ~/.codex/config.toml instead: see [Codex setup](https://taskhold.com/for/codex).

Add the workflow to the repo's CLAUDE.md, with one extra line so each session labels itself by branch:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Claude Code in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
- Running in a worktree: use the agent label "Claude Code on <branch>" (git branch --show-current).
```

Commit it, then start sessions as usual with cs. To see every session's progress without leaving tmux, open a window with taskhold-mcp watch (see [tmux](https://taskhold.com/integrations/tmux)).

## One limit to know

Claude Squad has no hooks, so Taskhold only knows what each agent reports through the MCP tools. A session that ignores the workflow (or never got CLAUDE.md, because it wasn't committed) does its work but never shows on the board. Claude Squad's own list still tells you a session is running; the board tells you what it is doing.

## Sources

- [Claude Squad README](https://github.com/smtg-ai/claude-squad), checked 2026-10-26

## Related

- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Taskhold in tmux: status bar and a live board pane](https://taskhold.com/integrations/tmux.md)
- [Use Taskhold with Conductor](https://taskhold.com/integrations/conductor.md)
- [Use Taskhold with ccmanager's status hooks](https://taskhold.com/integrations/ccmanager.md)
- [Use Taskhold alongside container-use](https://taskhold.com/integrations/container-use.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

---

# Use Taskhold with Conductor

> Run Claude Code and Codex workspaces in Conductor and track every one on a Taskhold live board, labelled by workspace, with questions that need you first.

Source: https://taskhold.com/integrations/conductor
Last updated: 2026-10-26

Conductor runs Claude Code and Codex in parallel workspaces on your Mac. Each workspace loads the agent's own MCP config and reads CLAUDE.md or AGENTS.md from the repo, which is all Taskhold needs: one list the workspaces take tasks from, and a [live board](https://taskhold.com/demo/live) of what each is doing, even from your phone.

The pattern behind it: [running several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list). For a terminal-based runner, see [Claude Squad](https://taskhold.com/integrations/claude-squad).

## What you get

- Workspaces that don't pick the same task, because a started task shows as in progress to all of them.
- A card per workspace with its steps, progress and last message, labelled with the workspace name.
- Blocked questions from any workspace collected under Needs you, answered from the board.

## Set it up

Conductor doesn't have its own MCP format: Claude Code and Codex sessions use their own config. Add Taskhold at user scope so every workspace sees it:

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

For Codex, add the server to ~/.codex/config.toml as on the [Codex page](https://taskhold.com/for/codex).

Commit the workflow to CLAUDE.md or AGENTS.md. Conductor sets CONDUCTOR_WORKSPACE_NAME in every agent process, so ask the agent to use it as its label:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Claude Code in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
- In a Conductor workspace: use the agent label "Claude Code in $CONDUCTOR_WORKSPACE_NAME" (echo $CONDUCTOR_WORKSPACE_NAME).
```

The MCP status dialog in Conductor's composer shows whether taskhold connected.

## One limit to know

Conductor's enterprise data privacy mode turns off custom MCP servers, and Conductor Cloud workspaces don't read your local ~/.claude.json, so neither sees Taskhold. On local workspaces with the default settings it works as above.

## Sources

- [Conductor docs](https://conductor.build/docs), checked 2026-10-26

## Related

- [Use Taskhold with Claude Squad](https://taskhold.com/integrations/claude-squad.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Task list MCP server for Codex CLI](https://taskhold.com/for/codex.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

---

# Use Taskhold with ccmanager

> Run agent sessions in ccmanager and use its status hooks to post "waiting for input" on the Taskhold task, so the live board shows which session needs you.

Source: https://taskhold.com/integrations/ccmanager
Last updated: 2026-10-26

ccmanager runs Claude Code, Codex, Gemini CLI and other agents in git worktrees and knows when each session goes idle, busy or waiting for input. Its status hooks can pass that on to Taskhold, so the [live board](https://taskhold.com/demo/live) says a session is waiting even when the agent itself didn't report it.

The setup for the agents themselves is the same as for [Claude Squad](https://taskhold.com/integrations/claude-squad); the general pattern is in [several agents on one list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list).

## Connect the sessions

ccmanager starts each agent in a new worktree, so configure Taskhold at user scope and commit the workflow to CLAUDE.md or AGENTS.md:

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

## Add a waiting-for-input hook

1. Save your API key where the script can read it: mkdir -p ~/.config/taskhold && printf '%s' 'atd_sk_...' > ~/.config/taskhold/key && chmod 600 ~/.config/taskhold/key (or export TASKHOLD_API_KEY).
2. Save the script below as ~/.config/ccmanager/taskhold-waiting.sh and make it executable.
3. In ccmanager, open Global Configuration > Configure Status Hooks and set the waiting_input hook to bash ~/.config/ccmanager/taskhold-waiting.sh, or add it to ~/.config/ccmanager/config.json as shown.

```bash
#!/bin/bash
# taskhold-waiting.sh: ccmanager status hook. Says on the Taskhold task in progress that a session waits for you.
# ccmanager runs it in the worktree and sets CCMANAGER_WORKTREE_BRANCH. Needs curl and jq.
key=${TASKHOLD_API_KEY:-$(cat ~/.config/taskhold/key 2>/dev/null)}
base=${TASKHOLD_API_URL:-https://taskhold.com/api}
[ -z "$key" ] && exit 0
auth="Authorization: Bearer $key"
id=$(curl -s --max-time 3 "$base/tasks/current" -H "$auth" | jq -r '.task.id // empty')
[ -z "$id" ] && exit 0
jq -n --arg m "Waiting for input in ccmanager ($CCMANAGER_WORKTREE_BRANCH)" '{message: $m}' \
  | curl -s --max-time 3 -o /dev/null "$base/tasks/$id/progress" -H "$auth" \
    -H "Content-Type: application/json" -d @-
exit 0
```

```json
{
  "statusHooks": {
    "waiting_input": { "command": "bash ~/.config/ccmanager/taskhold-waiting.sh", "enabled": true }
  }
}
```

Merge into ~/.config/ccmanager/config.json.

## One limit to know

The hook knows the branch but not which Taskhold task the session is on, so it writes to the task Taskhold returns as in progress, the most recently active one. With several sessions running at once that can be another session's task. Treat it as a nudge to look; questions that need a real answer should still come from the agent through taskhold_block.

## Sources

- [ccmanager README](https://github.com/kbwo/ccmanager), checked 2026-10-26

## Related

- [Use Taskhold with Claude Squad](https://taskhold.com/integrations/claude-squad.md)
- [Get notified when your coding agent is blocked](https://taskhold.com/guides/answer-a-blocked-coding-agent.md)
- [Use Taskhold with Agent Deck](https://taskhold.com/integrations/agent-deck.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

---

# Use Taskhold with Agent Deck

> Add Taskhold to Agent Deck's MCP catalog once, attach it to any session with one key, and follow every agent's plan and progress on a live board.

Source: https://taskhold.com/integrations/agent-deck
Last updated: 2026-10-26

Agent Deck is a terminal manager for Claude Code, Codex, Gemini CLI, OpenCode and other agents in tmux sessions. It keeps a catalog of MCP servers you attach to sessions as needed; add Taskhold there and attached sessions report to the [live board](https://taskhold.com/demo/live).

For the workflow each agent follows, see the [CLAUDE.md task workflow guide](https://taskhold.com/guides/claude-md-task-workflow); for several agents at once, [one list for several agents](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list).

## Set it up

1. Add Taskhold to the MCP catalog in ~/.config/agent-deck/config.toml.
2. Attach it to a session: press m in the session list, or run agent-deck mcp attach <session> taskhold.
3. Commit the workflow to the repo's CLAUDE.md or AGENTS.md.

```toml
[mcps.taskhold]
url = "https://taskhold.com/api/mcp"
transport = "http"
headers = { Authorization = "Bearer <your atd_sk_ key>" }
description = "Taskhold task list"
```

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Claude Code in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

## One limit to know

Attaching a catalog server writes it, header included, into the session's project .mcp.json. Add .mcp.json to .gitignore in repos where you attach Taskhold, or skip the catalog and configure Taskhold at user scope (claude mcp add --scope user) so the key never lands in the repo.

## Sources

- [Agent Deck README](https://github.com/asheshgoplani/agent-deck), checked 2026-10-26
- [Agent Deck config reference](https://github.com/asheshgoplani/agent-deck/blob/main/skills/agent-deck/references/config-reference.md), checked 2026-10-26

## Related

- [Use Taskhold with ccmanager's status hooks](https://taskhold.com/integrations/ccmanager.md)
- [Use Taskhold with Claude Squad](https://taskhold.com/integrations/claude-squad.md)
- [A CLAUDE.md task workflow that survives sessions](https://taskhold.com/guides/claude-md-task-workflow.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

---

# Use Taskhold alongside container-use

> Agents that work in container-use environments can still plan and report to Taskhold: both are MCP servers on the same agent. The one permission to add.

Source: https://taskhold.com/integrations/container-use
Last updated: 2026-10-26

container-use gives each agent its own container and branch to work in, through an MCP server. Taskhold is another MCP server on the same agent, so the agent works inside the container and reports its plan and progress to the [live board](https://taskhold.com/demo/live) from the host.

Setup for the agent itself: [Claude Code](https://taskhold.com/for/claude-code) or [Cursor](https://taskhold.com/for/cursor). Several agents at once: [one list for several agents](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list).

## How the two fit

container-use's rules tell the agent to use its environments for every file, code and shell operation. Taskhold calls are none of those: they are MCP tool calls the agent makes from the host, so the two don't conflict and no network access from inside the container is needed.

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

## One limit to know

container-use's docs start Claude Code with --allowedTools listing only the container-use tools. Add the Taskhold tools to that list, or every progress report stops for a permission prompt:

```bash
claude --allowedTools 'mcp__container-use__*' 'mcp__taskhold__*'
```

## Sources

- [container-use README](https://github.com/dagger/container-use), checked 2026-10-26

## Related

- [Task list MCP server for Claude Code](https://taskhold.com/for/claude-code.md)
- [Run several coding agents on one task list](https://taskhold.com/guides/run-multiple-coding-agents-on-one-task-list.md)
- [Use Taskhold with Claude Squad](https://taskhold.com/integrations/claude-squad.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

---

# Show on the board when Cursor's agent stops

> A Cursor stop hook that marks the Taskhold task in progress when Cursor's agent finishes, aborts or errors, so the live board shows it stopped.

Source: https://taskhold.com/integrations/cursor-hooks
Last updated: 2026-10-26

Cursor's agent reports progress through the Taskhold MCP tools while it works. If it stops without saying so (you aborted it, or it hit an error), the [live board](https://taskhold.com/demo/live) would keep showing its last message. A stop hook closes that gap by writing "Cursor agent stopped (aborted)" on the task in progress.

Cursor itself connects as on the [Cursor setup page](https://taskhold.com/for/cursor); the Claude Code version of this idea is the [Notification hook](https://taskhold.com/docs/claude-code-hooks).

## Set it up

1. Save your API key where the script can read it: mkdir -p ~/.config/taskhold && printf '%s' 'atd_sk_...' > ~/.config/taskhold/key && chmod 600 ~/.config/taskhold/key (or export TASKHOLD_API_KEY).
2. Save the script below as ~/.cursor/hooks/taskhold-stop.sh and make it executable.
3. Register it in ~/.cursor/hooks.json. User hooks run from ~/.cursor/, so the path is relative to it.

```bash
#!/bin/bash
# ~/.cursor/hooks/taskhold-stop.sh: after each Cursor turn, show its last words on the Taskhold task in progress.
# Needs curl and jq. Key from TASKHOLD_API_KEY or ~/.config/taskhold/key.
input=$(cat)
key=${TASKHOLD_API_KEY:-$(cat ~/.config/taskhold/key 2>/dev/null)}
base=${TASKHOLD_API_URL:-https://taskhold.com/api}
msg=$(printf '%s' "$input" | jq -r '"Cursor agent stopped (" + .status + ")" // empty' 2>/dev/null | tr '\n' ' ' | sed 's/ *$//' | cut -c1-200)
if [ -n "$key" ] && [ -n "$msg" ]; then
  auth="Authorization: Bearer $key"
  id=$(curl -s --max-time 3 "$base/tasks/current" -H "$auth" | jq -r '.task.id // empty')
  [ -n "$id" ] && jq -n --arg m "$msg" '{message: $m}' | curl -s --max-time 3 -o /dev/null \
    "$base/tasks/$id/progress" -H "$auth" -H "Content-Type: application/json" \
    -H "X-Taskhold-Agent: Cursor" -d @-
fi
echo '{}'
exit 0
```

```json
{
  "version": 1,
  "hooks": {
    "stop": [
      { "command": "./hooks/taskhold-stop.sh", "timeout": 10 }
    ]
  }
}
```

## One limit to know

Cursor's stop event says how the run ended (completed, aborted or error) but carries no summary, so the board shows the status only. The hook writes to the task Taskhold returns as in progress, the most recently active one; with other agents working at the same time that may not be Cursor's.

## Sources

- [Cursor docs: hooks](https://cursor.com/docs/hooks), checked 2026-10-26

## Related

- [Task list MCP server for Cursor](https://taskhold.com/for/cursor.md)
- [Codex notify: show each turn's result on the board](https://taskhold.com/integrations/codex-hooks.md)
- [Gemini CLI hook: show each reply on the board](https://taskhold.com/integrations/gemini-cli-hooks.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

---

# Show each Codex turn on the board

> Use Codex's notify setting to copy the agent's last message onto the Taskhold task in progress after each turn, so the live board shows what it just did.

Source: https://taskhold.com/integrations/codex-hooks
Last updated: 2026-10-26

Codex runs a program of your choice when a turn completes and passes it the agent's last message. This script puts that message on the Taskhold task in progress, so the [live board](https://taskhold.com/demo/live) shows what Codex just said even between its own progress reports.

Codex itself connects as on the [Codex setup page](https://taskhold.com/for/codex). For Claude Code, see the [hooks recipe](https://taskhold.com/docs/claude-code-hooks).

## Set it up

1. Save your API key where the script can read it: mkdir -p ~/.config/taskhold && printf '%s' 'atd_sk_...' > ~/.config/taskhold/key && chmod 600 ~/.config/taskhold/key (or export TASKHOLD_API_KEY).
2. Save the script below as ~/.codex/taskhold-notify.sh and make it executable.
3. Add the notify line to ~/.codex/config.toml, above any [table] such as [mcp_servers.taskhold]: in TOML, a key placed after a table belongs to that table.

```bash
#!/bin/bash
# ~/.codex/taskhold-notify.sh: after each Codex turn, show its last words on the Taskhold task in progress.
# Needs curl and jq. Key from TASKHOLD_API_KEY or ~/.config/taskhold/key.
input="$1"
key=${TASKHOLD_API_KEY:-$(cat ~/.config/taskhold/key 2>/dev/null)}
base=${TASKHOLD_API_URL:-https://taskhold.com/api}
msg=$(printf '%s' "$input" | jq -r '."last-assistant-message" // empty' 2>/dev/null | tr '\n' ' ' | sed 's/ *$//' | cut -c1-200)
if [ -n "$key" ] && [ -n "$msg" ]; then
  auth="Authorization: Bearer $key"
  id=$(curl -s --max-time 3 "$base/tasks/current" -H "$auth" | jq -r '.task.id // empty')
  [ -n "$id" ] && jq -n --arg m "$msg" '{message: $m}' | curl -s --max-time 3 -o /dev/null \
    "$base/tasks/$id/progress" -H "$auth" -H "Content-Type: application/json" \
    -H "X-Taskhold-Agent: Codex" -d @-
fi
exit 0
```

Codex passes the event as one JSON argument, with type agent-turn-complete.

```toml
notify = ["bash", "/Users/you/.codex/taskhold-notify.sh"]
```

Use the absolute path; Codex doesn't expand ~ here.

## One limit to know

notify fires once per turn, so a long turn shows nothing new until it ends, and only the first 200 characters of the message fit. The hook writes to the task Taskhold returns as in progress, which with several agents running may belong to another one. Codex's newer hooks.json Stop hook passes the same last_assistant_message on stdin if you'd rather use that.

## Sources

- [Codex docs: advanced configuration (notify)](https://developers.openai.com/codex/config-advanced), checked 2026-10-26
- [Codex docs: hooks](https://developers.openai.com/codex/hooks), checked 2026-10-26

## Related

- [Task list MCP server for Codex CLI](https://taskhold.com/for/codex.md)
- [Cursor hook: show on the board when the agent stops](https://taskhold.com/integrations/cursor-hooks.md)
- [Gemini CLI hook: show each reply on the board](https://taskhold.com/integrations/gemini-cli-hooks.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

---

# Show each Gemini CLI reply on the board

> An AfterAgent hook for Gemini CLI that copies each reply onto the Taskhold task in progress, so the live board shows what the agent just did.

Source: https://taskhold.com/integrations/gemini-cli-hooks
Last updated: 2026-10-26

Gemini CLI hooks run a command at points in the agent loop. An AfterAgent hook gets the agent's reply, and this script puts the start of it on the Taskhold task in progress, so the [live board](https://taskhold.com/demo/live) stays current between the agent's own progress reports.

Gemini CLI itself connects as on the [Gemini CLI setup page](https://taskhold.com/for/gemini-cli). Codex and Cursor have their own versions: [Codex notify](https://taskhold.com/integrations/codex-hooks), [Cursor hooks](https://taskhold.com/integrations/cursor-hooks).

## Set it up

1. Save your API key where the script can read it: mkdir -p ~/.config/taskhold && printf '%s' 'atd_sk_...' > ~/.config/taskhold/key && chmod 600 ~/.config/taskhold/key (or export TASKHOLD_API_KEY).
2. Save the script below as ~/.gemini/hooks/taskhold.sh and make it executable.
3. Register it in ~/.gemini/settings.json. The timeout is in milliseconds.

```bash
#!/bin/bash
# ~/.gemini/hooks/taskhold.sh: after each Gemini CLI turn, show its last words on the Taskhold task in progress.
# Needs curl and jq. Key from TASKHOLD_API_KEY or ~/.config/taskhold/key.
input=$(cat)
key=${TASKHOLD_API_KEY:-$(cat ~/.config/taskhold/key 2>/dev/null)}
base=${TASKHOLD_API_URL:-https://taskhold.com/api}
msg=$(printf '%s' "$input" | jq -r '.prompt_response // empty' 2>/dev/null | tr '\n' ' ' | sed 's/ *$//' | cut -c1-200)
if [ -n "$key" ] && [ -n "$msg" ]; then
  auth="Authorization: Bearer $key"
  id=$(curl -s --max-time 3 "$base/tasks/current" -H "$auth" | jq -r '.task.id // empty')
  [ -n "$id" ] && jq -n --arg m "$msg" '{message: $m}' | curl -s --max-time 3 -o /dev/null \
    "$base/tasks/$id/progress" -H "$auth" -H "Content-Type: application/json" \
    -H "X-Taskhold-Agent: Gemini CLI" -d @-
fi
echo '{}'  # Gemini CLI reads hook stdout as JSON
exit 0
```

```json
{
  "hooks": {
    "AfterAgent": [
      {
        "matcher": "*",
        "hooks": [
          { "name": "taskhold", "type": "command", "command": "~/.gemini/hooks/taskhold.sh", "timeout": 5000 }
        ]
      }
    ]
  }
}
```

## One limit to know

If you turn on Gemini CLI's environment variable redaction, variables with KEY in the name are stripped before hooks run, so TASKHOLD_API_KEY disappears. Keep the key in ~/.config/taskhold/key, or add TASKHOLD_API_KEY to the redaction allow list. Like any hook that writes to the task in progress, it may land on another agent's task when several run at once.

## Sources

- [Gemini CLI docs: hooks](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/index.md), checked 2026-10-26
- [Gemini CLI docs: hooks reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/reference.md), checked 2026-10-26

## Related

- [Task list MCP server for Gemini CLI](https://taskhold.com/for/gemini-cli.md)
- [Codex notify: show each turn's result on the board](https://taskhold.com/integrations/codex-hooks.md)
- [Cursor hook: show on the board when the agent stops](https://taskhold.com/integrations/cursor-hooks.md)
- [Windsurf Cascade hook: show each reply on the board](https://taskhold.com/integrations/windsurf-hooks.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

---

# Show each Cascade reply on the board

> A post_cascade_response hook for Windsurf (Devin Desktop) that copies Cascade's reply onto the Taskhold task in progress, so the live board stays current.

Source: https://taskhold.com/integrations/windsurf-hooks
Last updated: 2026-10-26

Windsurf, now Devin Desktop, runs hooks around Cascade's actions. The post_cascade_response hook receives Cascade's reply, and this script puts the start of it on the Taskhold task in progress, so the [live board](https://taskhold.com/demo/live) shows what Cascade just did.

Cascade itself connects as on the [Windsurf setup page](https://taskhold.com/for/windsurf). Other agents: [Gemini CLI hooks](https://taskhold.com/integrations/gemini-cli-hooks), [Cursor hooks](https://taskhold.com/integrations/cursor-hooks).

## Set it up

1. Save your API key where the script can read it: mkdir -p ~/.config/taskhold && printf '%s' 'atd_sk_...' > ~/.config/taskhold/key && chmod 600 ~/.config/taskhold/key (or export TASKHOLD_API_KEY).
2. Save the script below as ~/.codeium/taskhold-cascade.sh and make it executable.
3. Register it in ~/.codeium/windsurf/hooks.json (user level). A workspace can use .devin/hooks.json, or .windsurf/hooks.json on older versions.

```bash
#!/bin/bash
# ~/.codeium/taskhold-cascade.sh: after each Windsurf turn, show its last words on the Taskhold task in progress.
# Needs curl and jq. Key from TASKHOLD_API_KEY or ~/.config/taskhold/key.
input=$(cat)
key=${TASKHOLD_API_KEY:-$(cat ~/.config/taskhold/key 2>/dev/null)}
base=${TASKHOLD_API_URL:-https://taskhold.com/api}
msg=$(printf '%s' "$input" | jq -r '.tool_info.response // empty' 2>/dev/null | tr '\n' ' ' | sed 's/ *$//' | cut -c1-200)
if [ -n "$key" ] && [ -n "$msg" ]; then
  auth="Authorization: Bearer $key"
  id=$(curl -s --max-time 3 "$base/tasks/current" -H "$auth" | jq -r '.task.id // empty')
  [ -n "$id" ] && jq -n --arg m "$msg" '{message: $m}' | curl -s --max-time 3 -o /dev/null \
    "$base/tasks/$id/progress" -H "$auth" -H "Content-Type: application/json" \
    -H "X-Taskhold-Agent: Windsurf" -d @-
fi
exit 0
```

```json
{
  "hooks": {
    "post_cascade_response": [
      { "command": "bash ~/.codeium/taskhold-cascade.sh", "show_output": false }
    ]
  }
}
```

## One limit to know

The product was renamed in 2026 and its config paths moved; the user hooks file stayed at ~/.codeium/windsurf/hooks.json, but check the docs if your version differs. The hook writes to the task Taskhold returns as in progress, which may belong to another agent when several run at once.

## Sources

- [Devin Desktop docs: Cascade hooks](https://docs.devin.ai/desktop/cascade/hooks), checked 2026-10-26

## Related

- [Task list MCP for Windsurf and Devin Desktop](https://taskhold.com/for/windsurf.md)
- [Gemini CLI hook: show each reply on the board](https://taskhold.com/integrations/gemini-cli-hooks.md)
- [Cursor hook: show on the board when the agent stops](https://taskhold.com/integrations/cursor-hooks.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

---

# Taskhold docs

> How to wire your coding agents, CI jobs and scripts into Taskhold, with live progress per step.

Source: https://taskhold.com/docs

## Start here

- [What Taskhold is: a task list your agents report into](https://taskhold.com/docs/overview.md): Taskhold in one page: a hosted task list you share with your coding agents, live progress per step, the MCP and REST surfaces, price, data handling.
- [Quickstart: watch your agent's first plan in 5 minutes](https://taskhold.com/docs/quickstart.md): Connect Claude Code, Cursor or any MCP client to Taskhold and watch your agent plan steps and report progress on the live board, in about five minutes.
- [Install the Taskhold CLI: terminal board and status line](https://taskhold.com/install.md): Most agents need nothing installed. One command adds the Taskhold terminal board and the Claude Code status line. How updates, pins and uninstall work.

## Live progress

- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md): How Taskhold turns agent reports into a live board: steps as subtasks, progress rollup, the live and quiet markers, the time estimate, blocked questions.
- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md): Write progress messages and blocking questions a person can act on from the live board: headline first, one request, options with a recommendation.

## Recipes

- [Show the current task in the Claude Code status line](https://taskhold.com/docs/claude-code-status-line.md): A 24-line script that puts the Taskhold task in progress, its progress bar and the running step in the Claude Code status line. Uses curl and jq.
- [Claude Code hook: start every session with your replies](https://taskhold.com/docs/claude-code-hooks.md): A SessionStart hook that tells Claude Code which Taskhold task is in progress and what you changed since, so a new session picks up your replies first.
- [Report CI and deploy progress to Taskhold with curl](https://taskhold.com/docs/ci-progress.md): Have a GitHub Actions job open a Taskhold task, plan its stages as steps, tick them off and block with the logs link on failure. Plain curl and jq.
- [Slack alerts for blocked tasks from the events stream](https://taskhold.com/docs/slack-alerts.md): A 53-line Bun script that follows the Taskhold event stream and posts to a Slack channel when an agent blocks with a question or finishes a task.
- [Review what each coding agent did this week](https://taskhold.com/docs/agent-review.md): A Bun script that reads the Taskhold events API and prints a weekly scorecard per agent, with dated evidence and the CLAUDE.md lines to add.

## Reference

- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md): Every Taskhold MCP tool: what it does, its arguments, what it returns and when an agent should call it. Remote server at taskhold.com/api/mcp.
- [Taskhold REST API: tasks, steps, progress, curl examples](https://taskhold.com/docs/rest-api.md): Taskhold REST API reference: authentication, tasks, steps, progress, notes, events and the live snapshot, with curl examples and real responses.
- [Taskhold events API and Server-Sent Events stream](https://taskhold.com/docs/events.md): Follow every Taskhold change as it happens: the cursor feed at /api/events, the SSE stream at /api/events/stream, event types and a curl watcher.
- [Troubleshooting Taskhold: errors, missing tools, no progress](https://taskhold.com/docs/troubleshooting.md): Fixes for the common Taskhold problems: no taskhold tools in the agent, 401 and 402 responses, a bar that won't move, stale cards and silent streams.
- [Glossary: blocked, steps, progress reports, setup URLs](https://taskhold.com/docs/glossary.md): What Taskhold means by blocked, step, progress report, agent label, setup URL, API key and live board, so agents, docs and people mean the same thing.
- [Security and buying questions](https://taskhold.com/docs/security.md): Where Taskhold stores data, what leaves your machine, subprocessors, auth, deletion, export, pricing and what isn't built: answers for a security review.

OpenAPI: https://taskhold.com/openapi.json
Agent setup file: https://taskhold.com/SKILL.md
Changelog: https://taskhold.com/changelog

---

# What Taskhold is

> Taskhold in one page: a hosted task list you share with your coding agents, live progress per step, the MCP and REST surfaces, price, data handling.

Source: https://taskhold.com/docs/overview
Last updated: 2026-10-26

Taskhold is a hosted task list shared by one person and their AI coding agents. You add and order tasks in a web app. Your agents (Claude Code, Cursor, Codex, Windsurf, VS Code, Gemini CLI, or any MCP client) read the same list, break work into steps, report progress, and ask you questions when they're stuck.

While they work, you watch the live board at /dashboard/live: one card per task with a progress bar split by step, which agent is on it, how long it has run, an estimate of the time left, and what it's doing right now. This page is short enough to forward to a teammate.

## What an agent does with it

- Takes the highest-priority task and marks it in progress, so a second agent skips it (taskhold_start).
- Breaks it into steps you can see (taskhold_plan) and ticks them off one by one (taskhold_complete).
- Reports progress inside a long step: a percent, or 12 of 40 files, plus a one-line message (taskhold_progress).
- Blocks the task with a specific question when it needs a decision (taskhold_block), then reads your reply (taskhold_updates).
- Finishes with a summary of what changed, and files the bugs and TODOs it noticed as new tasks.

## Surfaces

| Surface | What it is | Docs |
| --- | --- | --- |
| Remote MCP server | https://taskhold.com/api/mcp, Streamable HTTP, Bearer key. 19 taskhold_* tools. | /docs/mcp-tools |
| REST API | The same data over JSON at https://taskhold.com/api, for scripts and CI jobs. OpenAPI 3.1 at /openapi.json. | /docs/rest-api |
| Live events | Every change as it happens: a cursor feed and a Server-Sent Events stream. | /docs/events |
| Web app | The list, each task's steps and timeline, and the live board. Works on phones. | /docs/live-progress |
| Agent skill | A Claude Code plugin with the taskhold skill and MCP config, on GitHub. | /docs/quickstart |

## Price and data

- One plan: $12 a month or $120 a year per person, every agent included. 7-day trial with a card; cancel before it ends and nothing is charged. There is no free plan.
- Your tasks are private to your account. Agents authenticate with API keys you can revoke in Settings.
- Keep secrets and large code blocks out of tasks: a file path and line number are enough.

## Not a fit

- Teams that want one shared workspace with roles. Each person has their own account.
- Work that should live next to pull requests: use GitHub Issues.
- A single session's checklist: your agent's built-in todo list or a TODO.md costs nothing.

## Related

- [Quickstart: watch your agent's first plan in 5 minutes](https://taskhold.com/docs/quickstart.md)
- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md)
- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md)

---

# Quickstart: your agent's first live plan

> Connect Claude Code, Cursor or any MCP client to Taskhold and watch your agent plan steps and report progress on the live board, in about five minutes.

Source: https://taskhold.com/docs/quickstart
Last updated: 2026-10-26

By the end of this page your agent will have planned a task in steps, reported progress, and finished it while you watched the bar fill on the live board. You need a Taskhold account (7-day trial) and a coding agent that supports remote MCP servers.

## 1. Connect the agent

- Open Settings and 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 it: the markdown holds a fresh API key, the config for that client, and the workflow instructions.
- Settings shows "Connected" when the agent's first call arrives.

To connect Claude Code by hand instead, run this with a key from Settings:

```bash
claude mcp add --transport http --scope user taskhold https://taskhold.com/api/mcp \
  --header "Authorization: Bearer API_KEY"
```

Replace API_KEY with a key that starts with atd_sk_. Other clients: taskhold.com/for.

## 2. Open the live board

Open https://taskhold.com/dashboard/live in a browser tab you can see while the agent works. Click "Notify me" if you want a desktop notification when an agent gets blocked or finishes.

## 3. Give the agent a real task

Add a task in the web app (or let the agent file one), then say to the agent:

```text
Take my next Taskhold task. Plan it in steps with taskhold_plan, report progress as you go, and block it with a question if you need me.
```

The card appears under Working now when the agent calls taskhold_start. Each step it plans becomes a segment of the bar; the segment fills as the step finishes, and the running step's message shows under the bar.

## 4. Make it the default

Add this block to CLAUDE.md or AGENTS.md so every session works this way without being asked:

```markdown
## Tasks (Taskhold)

The person and I share a task list through the taskhold MCP tools. They watch a live board while I work.
- Session start: taskhold_get_current, then taskhold_updates for replies. Nothing in progress? taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task (agent: "Claude Code in <repo>").
- More than a couple of steps: taskhold_plan, then taskhold_start and taskhold_complete each step.
- taskhold_progress at milestones (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 check taskhold_updates.
- Done: taskhold_complete with what changed and how I checked it.
- A TODO or bug I'm not fixing now: taskhold_create (or taskhold_create_from_todo with file and line).
```

If you installed the Claude Code plugin from github.com/gettaskhold/taskhold-plugin, its skill carries the same workflow and you can skip the block.

## Check that it worked

- The task shows a bar split into the steps the agent planned, with the agent's name on the card.
- The Activity feed lists "Started", the plan, progress messages and "Completed".
- The finished task moves to Finished recently with the agent's summary.

Nothing on the board? See /docs/troubleshooting.

## What your agent sends, and how to disconnect it

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.

## Related

- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md)
- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md)
- [Show the current task in the Claude Code status line](https://taskhold.com/docs/claude-code-status-line.md)
- [Glossary: blocked, steps, progress reports, setup URLs](https://taskhold.com/docs/glossary.md)

---

# Install the Taskhold CLI (optional)

> Most agents need nothing installed. One command adds the Taskhold terminal board and the Claude Code status line. How updates, pins and uninstall work.

Source: https://taskhold.com/install
Last updated: 2026-10-26

Most agents need nothing installed. Taskhold's MCP server is remote: Claude Code, Cursor, Codex, Windsurf and most other clients connect to https://taskhold.com/api/mcp over HTTPS, and the setup URL in Settings gives your agent the exact config.

The CLI on this page is optional. It adds a live board in your terminal, the task in progress in the Claude Code status line, and a stdio server for clients that can't reach a remote one. It comes from taskhold.com, not the npm registry.

## Install the CLI

```bash
curl -fsSL https://taskhold.com/install.sh | sh
```

Read the installer first if you like: https://taskhold.com/install.sh (about 80 lines of sh).

- Needs Node.js 18 or later, or Bun. No sudo: everything goes in ~/.taskhold.
- Downloads the latest build from taskhold.com and checks its sha256 against /dl/latest.json before installing anything.
- Links taskhold-mcp into ~/.local/bin when that folder is on your PATH. Otherwise it prints the PATH line to add, and the full path ~/.taskhold/bin/taskhold-mcp works everywhere.

Then save your API key (Settings, API keys):

```bash
taskhold-mcp login
```

Paste the atd_sk_ key when asked. It is checked against the API and stored in ~/.taskhold/config.json, readable only by you. TASKHOLD_API_KEY in the environment wins over the saved key.

## Watch your agents from the terminal

```bash
taskhold-mcp watch
```

The live board in a terminal: tasks in progress with a bar split by step, what each agent says it is doing, blocked tasks with their question, and recent activity. It redraws as events arrive over the events stream and reconnects on its own. Ctrl-C quits.

## Show the task in the Claude Code status line

```bash
taskhold-mcp statusline --install
```

This adds a statusLine entry to ~/.claude/settings.json and keeps a backup next to it. If you already have a status line, it leaves yours alone and tells you; add --force to replace it. New Claude Code sessions show the line:

```text
▶ Deploy v2.4 to staging ███░░░░░░░ 33% 1/3 · Run migrations
```

To mix Taskhold into a status line you already like, use the [status line recipe](/docs/claude-code-status-line) or the [status line generator](/tools/claude-code-statusline) instead.

## Use the stdio server

For MCP clients that only run local servers. npx downloads the latest build from taskhold.com each time the client starts the server:

```json
{
  "mcpServers": {
    "taskhold": {
      "command": "npx",
      "args": [
        "-y",
        "https://taskhold.com/dl/taskhold-mcp-latest.tgz"
      ],
      "env": {
        "TASKHOLD_API_KEY": "atd_sk_..."
      }
    }
  }
}
```

With Bun: bunx -p https://taskhold.com/dl/taskhold-mcp-latest.tgz taskhold-mcp

If you installed the CLI, the installed copy is a faster stdio server: set command to its full path (for example /Users/you/.taskhold/bin/taskhold-mcp), no args. It reads the saved key.

## Updates and version pins

- taskhold-mcp update installs the latest version. taskhold-mcp update 1.3.0 installs that version and pins it.
- The CLI checks for a new version at most once a day and prints one line when there is one. The line goes to stderr, so an MCP client never sees it. Turn it off with TASKHOLD_NO_UPDATE_CHECK=1; pinned installs don't check.
- npx configs that use taskhold-mcp-latest.tgz get each new version on the next start. To pin one, put the version in the file name: taskhold-mcp-1.3.0.tgz.
- To pin at install time: curl -fsSL https://taskhold.com/install.sh | sh -s -- --version 1.3.0

## Current version and checksums

| File | Size | sha256 |
| --- | --- | --- |
| taskhold-mcp-1.3.2.mjs | 916 KB | fcfa8d73142c58a4210e7fda62861dcae7e810f33f87cd9d20edcdc4cdca5f17 |
| taskhold-mcp-1.3.2.tgz | 194 KB | 8b72e45fbc8a352cf8c36cf84303bfed026a1c3bf810a2b8e44a6efb28d93e0f |

taskhold-mcp 1.3.2, released 2026-10-27. Every release with its checksums: https://taskhold.com/dl/releases.json. A released file never changes; a new build gets a new version number.

Check a download yourself:

```bash
curl -fsSL https://taskhold.com/dl/taskhold-mcp-1.3.2.mjs | shasum -a 256
```

## Uninstall

```bash
taskhold-mcp uninstall
```

Removes ~/.taskhold, the ~/.local/bin link and the Claude Code status line if the installer set it. By hand: rm -rf ~/.taskhold. Stdio entries in an MCP client config are yours to delete. The remote server has nothing to uninstall; revoke its key in Settings.

## Related

- [Quickstart: watch your agent's first plan in 5 minutes](https://taskhold.com/docs/quickstart.md)
- [Show the current task in the Claude Code status line](https://taskhold.com/docs/claude-code-status-line.md)
- [Troubleshooting Taskhold: errors, missing tools, no progress](https://taskhold.com/docs/troubleshooting.md)

---

# How live progress works

> How Taskhold turns agent reports into a live board: steps as subtasks, progress rollup, the live and quiet markers, the time estimate, blocked questions.

Source: https://taskhold.com/docs/live-progress
Last updated: 2026-10-26

Live progress is built from three things an agent sends: a plan (steps), progress inside a step, and status changes (start, block, complete). Taskhold rolls them into one bar per task and streams every change to the board as it happens.

Terms such as blocked, step and setup URL are defined in the [glossary](/docs/glossary).

## Steps

Steps are subtasks one level below a task. taskhold_plan (or POST /api/tasks/{id}/subtasks) adds them in order; replace: true swaps out the steps that haven't started and keeps the done and running ones. Steps don't nest, and a task can have up to 200.

Starting a step also starts its task. Completing a step returns the next one to the agent, and once every step is done the agent is told to complete the task with a summary.

## How the bar is computed

| Task state | Bar shows |
| --- | --- |
| Done | 100% |
| Has steps | The average of its steps: a done step counts 100, a running step counts its own reported progress, the rest count 0 |
| No steps, progress reported | The percent, or current / total (12 of 40 = 30%) |
| No steps, nothing reported | An indeterminate bar while in progress |

On a task with steps, progress reported on the task itself is shown as its message but doesn't move the bar. Report it on the running step.

## Live, quiet and stale

Every report from an agent updates the task's last activity time. The board marks an in-progress task live if the agent spoke in the last 2 minutes, quiet after that, and stale after 15 minutes without a word. A stale card usually means the session ended without completing or blocking the task.

## Time estimate

The estimate of time left is linear: elapsed time divided by percent done, times the percent remaining. It appears once a task is at least 5% done and has run for 30 seconds, and it is only as good as the progress reports behind it.

## Blocked tasks and replies

taskhold_block puts the task at the top of the board under Needs you, with the agent's question. You reply on the board (or reply and unblock). The agent reads your reply with taskhold_updates, which returns the changes you made since the cursor it passes, so it never re-reads old history.

## Reporting patterns that read well on the board

| Do | Avoid |
| --- | --- |
| Plan 3 to 8 steps named for outcomes: "Migrate the users table" | One step per tool call, or a single step called "Work" |
| current / total when counting: 12 of 40 files | A percent you guessed |
| A message per milestone, every few minutes at most | A progress call after every tool call |
| Block on the step that's stuck, with one specific question | Leaving the task in progress while you wait |
| Complete with what changed and how you checked it | Completing a task you only partly did |

## Related

- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md)
- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md)
- [Taskhold events API and Server-Sent Events stream](https://taskhold.com/docs/events.md)
- [Glossary: blocked, steps, progress reports, setup URLs](https://taskhold.com/docs/glossary.md)

---

# Write progress notes and questions a person can act on

> Write progress messages and blocking questions a person can act on from the live board: headline first, one request, options with a recommendation.

Source: https://taskhold.com/docs/agent-messages
Last updated: 2026-10-26

The person reads your messages on a phone or in a corner of the screen, between other things. Put the point first and make any request specific enough to answer in one line.

## Progress messages

- Say what is happening now, in under 80 characters: "Running the test suite (412 tests)".
- Name the thing, not the activity: "Migrating invoices table" beats "Working on database stuff".
- Use current and total when you're counting; the numbers go in the bar, not the message.

## Blocking questions

A blocked task asks for one of four things. Say which in the first words, then give what the person needs to answer without opening the code:

| Request | Shape | Example |
| --- | --- | --- |
| Decide | Options, your recommendation, what each costs | Decide: keep the old /v1 route for 30 days (safer) or remove it now (simpler)? I recommend 30 days. |
| Answer | A question with a short answer | Answer: which Stripe account should test checkouts use, the shared one or acct_...? |
| Approve | What you'll do and how to undo it | Approve: drop the unused sessions_old table (8 MB). Backup at backups/sessions_old.sql. |
| Access | Exactly what is missing and where it goes | Access: I need STAGING_DB_URL in .env.local to run the migration. |

Block the step that's stuck rather than the whole task when only one step needs the person, and keep working on other steps while you wait.

## When the reply doesn't settle it

- Read the reply with taskhold_updates. If it answers, unblock and say what you'll do in one line.
- If it's unclear, ask one follow-up on the same task, quoting their reply: "You said 'the shared one'. Do you mean acct_live_shared or acct_test_shared?"
- After two unclear rounds, stop asking. Leave the task blocked, move to other work, and write what you'd do by default and why.
- Never pick an answer you weren't given for anything you can't undo. If the reply doesn't settle it, block again with a narrower question; don't guess.

## Always ask first

Deleting data, spending money, changing billing or prices, touching secrets or access, and deploying to production. Block with an Approve request even when you're fairly sure.

## Give them the context

Put what you tried and what you found in the question, so the person can answer without opening the code: "Tests fail only on Node 20 (passes on 22). Pin Node 22 in CI, or fix the polyfill? I recommend pinning."

## Don't fake it

If you don't know, say so and block. A blocked task costs the person a minute; a confident guess can cost them the afternoon.

## Completion summaries

- First line: the outcome. "CSV export works for all three report types."
- Then what changed (files or areas), how you checked it, and anything left over, filed as new tasks.

## Related

- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md)
- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md)
- [Quickstart: watch your agent's first plan in 5 minutes](https://taskhold.com/docs/quickstart.md)

---

# Show the current task in the Claude Code status line

> A 24-line script that puts the Taskhold task in progress, its progress bar and the running step in the Claude Code status line. Uses curl and jq.

Source: https://taskhold.com/docs/claude-code-status-line
Last updated: 2026-10-26

Claude Code runs a command of your choice for its status line. This script asks Taskhold for the task in progress and prints one line: title, a ten-block bar, steps done and the step that's running. It caches the answer for 10 seconds.

Prefer one command with no script to maintain? The [Taskhold CLI](/install) sets up the same line with taskhold-mcp statusline --install. This page is for building it into a status line of your own.

## Before you begin

- curl and jq on your PATH.
- A Taskhold API key from Settings, saved where the script can read it:

```bash
mkdir -p ~/.config/taskhold && printf '%s' 'API_KEY' > ~/.config/taskhold/key && chmod 600 ~/.config/taskhold/key
```

Replace API_KEY with your atd_sk_ key, or export TASKHOLD_API_KEY instead.

## Add the script

Save this as ~/.claude/taskhold-statusline.sh and make it executable (chmod +x):

```bash
#!/bin/bash
# ~/.claude/taskhold-statusline.sh: the task in progress, its bar and the running step.
# Needs curl and jq. Key from TASKHOLD_API_KEY or ~/.config/taskhold/key.
cat > /dev/null  # Claude Code sends session JSON on stdin; this script doesn't need it
key=${TASKHOLD_API_KEY:-$(cat ~/.config/taskhold/key 2>/dev/null)}
base=${TASKHOLD_API_URL:-https://taskhold.com/api}
cache="${TMPDIR:-/tmp}/taskhold-statusline.txt"
now=$(date +%s)
if [ -f "$cache" ]; then
  read -r stamp < "$cache"
  if [ $((now - stamp)) -lt 10 ]; then tail -n +2 "$cache"; exit 0; fi
fi
line=$(curl -s --max-time 2 "$base/tasks/current" -H "Authorization: Bearer $key" | jq -r '
  .task // empty
  | (.overall_progress // 0) as $p
  | (($p / 10) | floor) as $f
  | (([range(0; $f)] | map("█") | join("")) + ([range($f; 10)] | map("░") | join(""))) as $bar
  | (((.subtasks // []) | map(select(.status == "in_progress")) | .[0].title) // .progress_message // "") as $now
  | "\(.title)  \($bar) \($p)%"
    + (if (.subtask_counts.total // 0) > 0 then "  \(.subtask_counts.done)/\(.subtask_counts.total) steps" else "" end)
    + (if $now != "" then "  > \($now)" else "" end)' 2>/dev/null)
line=${line:-No task in progress}
printf '%s\n%s\n' "$now" "$line" > "$cache"
echo "$line"
```

Then point Claude Code at it in ~/.claude/settings.json:

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/taskhold-statusline.sh",
    "refreshInterval": 10
  }
}
```

refreshInterval keeps the line current while the session is idle and another agent is working.

## What you'll see

```text
Deploy v2.4 to staging  ███░░░░░░░ 33%  1/3 steps  > Run migrations
```

With nothing in progress the line reads "No task in progress". To check the script by hand, run it with echo '{}' piped in.

## Related

- [Install the Taskhold CLI: terminal board and status line](https://taskhold.com/install.md)
- [Claude Code hook: start every session with your replies](https://taskhold.com/docs/claude-code-hooks.md)
- [Taskhold REST API: tasks, steps, progress, curl examples](https://taskhold.com/docs/rest-api.md)

---

# Start every Claude Code session with your replies

> A SessionStart hook that tells Claude Code which Taskhold task is in progress and what you changed since, so a new session picks up your replies first.

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

A new Claude Code session doesn't know you answered a blocked question an hour ago. A SessionStart hook can tell it: Claude Code adds the hook's output to the session as context before the first prompt. This one prints the task in progress and the last 10 changes you made in Taskhold.

## Add the hook script

Save this as ~/.claude/hooks/taskhold-session-start.sh and make it executable. It reads the key the same way as the status line recipe:

```bash
#!/bin/bash
# ~/.claude/hooks/taskhold-session-start.sh: what's in progress, and what the person changed.
# Claude Code adds this script's output to the session as context. Needs curl and jq.
key=${TASKHOLD_API_KEY:-$(cat ~/.config/taskhold/key 2>/dev/null)}
base=${TASKHOLD_API_URL:-https://taskhold.com/api}
[ -z "$key" ] && exit 0
auth="Authorization: Bearer $key"
current=$(curl -s --max-time 3 "$base/tasks/current" -H "$auth" | jq -r '.task // empty
  | "Taskhold: \"\(.title)\" is in progress (id \(.id)), \(.overall_progress // 0)% done."')
changes=$(curl -s --max-time 3 "$base/events?actor=human&limit=10" -H "$auth" | jq -r '.events[]?
  | "- \(.created_at[0:16]) \(.task_title // "list"): \(.summary)"')
[ -n "$current" ] && echo "$current"
[ -n "$changes" ] && printf 'Latest changes the person made in Taskhold:\n%s\nCall taskhold_updates for replies since your last cursor.\n' "$changes"
exit 0
```

## Register it

Add the hook to ~/.claude/settings.json (all projects) or .claude/settings.json (one repo):

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          { "type": "command", "command": "bash ~/.claude/hooks/taskhold-session-start.sh" }
        ]
      }
    ]
  }
}
```

SessionStart runs before MCP servers connect, so the hook uses the REST API, not the MCP tools. Keep it fast: both requests time out after 3 seconds.

## What Claude sees

```text
Taskhold: "Deploy v2.4 to staging" is in progress (id fd11278a-...), 33% done.
Latest changes the person made in Taskhold:
- 2026-10-26T05:30 Deploy v2.4 to staging: Use the shared Stripe test account, not the new one.
Call taskhold_updates for replies since your last cursor.
```

## Show on the board when Claude Code waits for you

Claude Code fires a Notification hook when it needs your permission for a tool or has been idle at the prompt. Those waits happen in the terminal, so the board can't see them. This hook copies the wait onto the task in progress as its latest message, without moving the bar. Save it as ~/.claude/hooks/taskhold-waiting.sh and make it executable:

```bash
#!/bin/bash
# ~/.claude/hooks/taskhold-waiting.sh: when Claude Code stops to wait for you (a permission
# prompt, or idle at the prompt), say so on the live board under the task in progress.
# Claude Code sends the hook JSON on stdin; .message is the text it shows. Needs curl and jq.
key=${TASKHOLD_API_KEY:-$(cat ~/.config/taskhold/key 2>/dev/null)}
base=${TASKHOLD_API_URL:-https://taskhold.com/api}
[ -z "$key" ] && exit 0
msg=$(jq -r '.message // "Waiting for input"' | cut -c1-200)
auth="Authorization: Bearer $key"
id=$(curl -s --max-time 3 "$base/tasks/current" -H "$auth" | jq -r '.task.id // empty')
[ -z "$id" ] && exit 0
jq -n --arg m "In the terminal: $msg" '{message: $m}' | curl -s --max-time 3 -o /dev/null \
  "$base/tasks/$id/progress" -H "$auth" -H "Content-Type: application/json" \
  -H "X-Taskhold-Agent: Claude Code" -d @-
exit 0
```

Register it next to the SessionStart hook:

```json
{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "bash ~/.claude/hooks/taskhold-waiting.sh" }
        ]
      }
    ]
  }
}
```

The card then reads "In the terminal: Claude needs your permission to use Bash" until the agent reports again. For questions that need an answer, the agent should still call taskhold_block, which puts the task under Needs you and lets you reply from the board.

## Related

- [Show the current task in the Claude Code status line](https://taskhold.com/docs/claude-code-status-line.md)
- [Taskhold events API and Server-Sent Events stream](https://taskhold.com/docs/events.md)
- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md)

---

# Report CI and deploy progress to Taskhold

> Have a GitHub Actions job open a Taskhold task, plan its stages as steps, tick them off and block with the logs link on failure. Plain curl and jq.

Source: https://taskhold.com/docs/ci-progress
Last updated: 2026-10-26

Anything that can make an HTTP request can report into Taskhold, not only coding agents. A deploy job that shows up on the live board next to your agents means one place to look. This recipe uses the REST API from GitHub Actions; the same calls work from any CI system or a cron job.

## Before you begin

- Create an API key in Taskhold Settings and name it after the job, for example "CI deploy".
- Add it to the repository as the secret TASKHOLD_API_KEY.
- The X-Taskhold-Agent header sets the name shown on the board, here "GitHub Actions (deploy)".

## The workflow

```yaml
# .github/workflows/deploy.yml (excerpt): one Taskhold task per run, one step per stage.
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      TH: https://taskhold.com/api
      AUTH: "Authorization: Bearer ${{ secrets.TASKHOLD_API_KEY }}"
      AGENT: "X-Taskhold-Agent: GitHub Actions (${{ github.workflow }})"
    steps:
      - uses: actions/checkout@v4

      - name: Open a Taskhold task with steps
        id: th
        run: |
          json() { curl -sf -H "$AUTH" -H "$AGENT" -H "Content-Type: application/json" "$@"; }
          task=$(json "$TH/tasks" -d "{\"title\": \"Deploy ${GITHUB_SHA::7}\", \"priority\": \"high\"}" | jq -r .task.id)
          json -X PATCH "$TH/tasks/$task" -d '{"status": "in_progress"}' > /dev/null
          read -r build test ship < <(json "$TH/tasks/$task/subtasks" \
            -d '{"steps": ["Build", "Test", "Ship"]}' | jq -r '[.subtasks[].id] | join(" ")')
          echo "task=$task" >> "$GITHUB_OUTPUT"
          echo "build=$build" >> "$GITHUB_OUTPUT"
          echo "test=$test" >> "$GITHUB_OUTPUT"
          echo "ship=$ship" >> "$GITHUB_OUTPUT"

      - name: Build
        run: |
          curl -sf -X PATCH "$TH/tasks/${{ steps.th.outputs.build }}" -H "$AUTH" -H "$AGENT" \
            -H "Content-Type: application/json" -d '{"status": "in_progress"}' > /dev/null
          make build
          curl -sf -X PATCH "$TH/tasks/${{ steps.th.outputs.build }}" -H "$AUTH" -H "$AGENT" \
            -H "Content-Type: application/json" -d '{"status": "done"}' > /dev/null

      # ... the same for Test and Ship ...

      - name: Tell the person if it failed
        if: failure()
        run: |
          url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
          curl -sf -X PATCH "$TH/tasks/${{ steps.th.outputs.task }}" -H "$AUTH" -H "$AGENT" \
            -H "Content-Type: application/json" \
            -d "{\"status\": \"blocked\", \"blocked_reason\": \"Deploy failed. Logs: $url\"}"
```

## What each call does

| Call | Effect on the board |
| --- | --- |
| POST /api/tasks | A new task, marked as added by an agent |
| PATCH /api/tasks/{id} with status in_progress | The card moves to Working now with the job's name and a start time |
| POST /api/tasks/{id}/subtasks with steps | The bar splits into one segment per stage |
| PATCH a step with status done | That segment fills; the bar advances by one stage |
| PATCH the task with status blocked and blocked_reason | The card moves to Needs you with the logs link |

For a long stage, report counts inside it with POST /api/tasks/{step_id}/progress and a body like {"current": 120, "total": 400, "message": "Uploading assets"}.

## Related

- [Taskhold REST API: tasks, steps, progress, curl examples](https://taskhold.com/docs/rest-api.md)
- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md)
- [Slack alerts for blocked tasks from the events stream](https://taskhold.com/docs/slack-alerts.md)

---

# Get a Slack message when an agent is blocked

> A 53-line Bun script that follows the Taskhold event stream and posts to a Slack channel when an agent blocks with a question or finishes a task.

Source: https://taskhold.com/docs/slack-alerts
Last updated: 2026-10-26

The live board can send desktop notifications, but only while it's open. This script runs anywhere you keep a process alive (a spare terminal, a small server), follows the event stream, and posts to Slack through an incoming webhook when an agent blocks a task or completes one.

For the no-code way to get notified and answer from your phone, see [answering a blocked coding agent](/guides/answer-a-blocked-coding-agent).

## Before you begin

- Bun 1.1 or later.
- A Slack incoming webhook URL: create a Slack app, turn on Incoming Webhooks, add one for the channel. It starts with https://hooks.slack.com/services/.
- A Taskhold API key.

## The script

```ts
// taskhold-slack.ts: post to Slack when an agent blocks or finishes a task.
// Run: TASKHOLD_API_KEY=atd_sk_... SLACK_WEBHOOK_URL=https://hooks.slack.com/... bun taskhold-slack.ts
const base = process.env.TASKHOLD_API_URL ?? "https://taskhold.com/api";
const app = base.replace(/\/api$/, "");
const key = process.env.TASKHOLD_API_KEY!;
const hook = process.env.SLACK_WEBHOOK_URL!;
let lastId = "";

async function post(e: any) {
  const blocked = e.data?.to === "blocked";
  const head = blocked ? `${e.actor_name ?? "An agent"} needs you` : `${e.actor_name ?? "An agent"} finished a task`;
  const detail = blocked ? e.data.blocked_reason : e.data.completed_summary;
  await fetch(hook, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `${head}: ${e.task_title}`,
      blocks: [
        { type: "section", text: { type: "mrkdwn", text: `*${head}*\n${e.task_title}${detail ? `\n>${detail}` : ""}` } },
        { type: "actions", elements: [{ type: "button", text: { type: "plain_text", text: blocked ? "Answer on the board" : "Open the board" }, url: `${app}/dashboard/live` }] },
      ],
    }),
  });
}

for (;;) {
  try {
    const res = await fetch(`${base}/events/stream`, {
      headers: { Authorization: `Bearer ${key}`, ...(lastId ? { "Last-Event-ID": lastId } : {}) },
    });
    if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
    let buf = "";
    for await (const chunk of res.body.pipeThrough(new TextDecoderStream())) {
      buf += chunk;
      let end;
      while ((end = buf.indexOf("\n\n")) >= 0) {
        const frame = buf.slice(0, end);
        buf = buf.slice(end + 2);
        const id = frame.match(/^id: (\d+)/m)?.[1];
        const data = frame.match(/^data: (.*)$/m)?.[1];
        if (id) lastId = id;
        if (!data || !/^event: task$/m.test(frame)) continue;
        const e = JSON.parse(data);
        if (e.type !== "task.status" || e.actor !== "agent") continue;
        const topLevel = e.task_id === e.root_task_id; // steps finish often; post only whole tasks
        if (e.data?.to === "blocked" || (e.data?.to === "done" && topLevel)) await post(e);
      }
    }
  } catch (err) {
    console.error("stream dropped:", (err as Error).message);
  }
  await Bun.sleep(3000); // the server ends each stream after 10 minutes; reconnect from lastId
}
```

It reconnects with the Last-Event-ID header, so events that happen while it reconnects are delivered once, in order. Change the filter line to post other events, for example every task.created from an agent.

## What gets posted

One message per event: a bold line naming the agent ("Claude Code in api-server needs you"), the task title, the question or summary as a quote, and a button that opens the live board.

## Related

- [Taskhold events API and Server-Sent Events stream](https://taskhold.com/docs/events.md)
- [Report CI and deploy progress to Taskhold with curl](https://taskhold.com/docs/ci-progress.md)
- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md)

---

# Review what each agent did this week

> A Bun script that reads the Taskhold events API and prints a weekly scorecard per agent, with dated evidence and the CLAUDE.md lines to add.

Source: https://taskhold.com/docs/agent-review
Last updated: 2026-10-26

Once a week, look at how each agent worked, not only what it finished: did it plan, report progress, ask clear questions and say how it checked its work? This script reads your events with an API key and prints one scorecard per agent, the events behind anything it flags, and the instruction lines that would fix it.

It only calls GET /api/events (see [events and the live stream](/docs/events)), so it changes nothing. To read a single run as it happens instead, use the [live board](/guides/review-what-your-agent-did).

## What it measures

- Tasks finished and steps finished, per agent label ("Claude Code in api", "Codex in web"), counting only top-level tasks as tasks.
- Plans posted with taskhold_plan, and progress reports. Reports an agent sends in quick succession are stored as one event, so the count is the updates you could see.
- Completions with a real summary: what changed and how it was checked, at least 20 characters.
- Blocked questions, how long each waited for your answer (until your next note or status change on that task), and questions too short to answer without a follow-up.
- Tasks you reopened after the agent marked them done.

## Run it

```bash
TASKHOLD_KEY=atd_sk_... bun agent-review.ts            # last 7 days
TASKHOLD_KEY=atd_sk_... bun agent-review.ts --days 30
```

Needs Bun 1.1 or later and an API key from Settings. Save the script below as agent-review.ts.

```ts
#!/usr/bin/env bun
/**
 * Review what each coding agent did this week, from Taskhold's events API: a scorecard per agent, dated
 * evidence for anything worth fixing, and the instruction lines to add to CLAUDE.md / AGENTS.md. Read-only.
 *
 *   TASKHOLD_KEY=atd_sk_... bun agent-review.ts [--days 7] [--base https://taskhold.com]
 *   bun agent-review.ts --fixture events.json        (a saved /api/events response)
 *
 * Uses only GET /api/events (https://taskhold.com/docs/events). Progress reports an agent sends in quick
 * succession are stored as one event, so "Progress reports" counts the updates you could see.
 */
type Ev = {
  id: number; type: string; actor: "agent" | "human"; actor_name?: string | null; task_id: string; root_task_id?: string | null;
  task_title?: string; summary?: string; data?: { from?: string; to?: string; blocked_reason?: string | null; completed_summary?: string | null };
  created_at: string;
};
const args = process.argv.slice(2);
const opt = (k: string, d?: string) => (args.includes(k) ? args[args.indexOf(k) + 1] : d);
const days = Number(opt("--days", "7"));
const since = Date.now() - days * 86_400_000;

async function load(): Promise<Ev[]> {
  const fx = opt("--fixture");
  if (fx) return (await Bun.file(fx).json()).events;
  const key = process.env.TASKHOLD_KEY;
  if (!key) throw new Error("set TASKHOLD_KEY (an API key from Settings) or pass --fixture");
  const site = opt("--base", "https://taskhold.com")!;
  const out: Ev[] = [];
  let cursor = 0;
  for (;;) {
    const r = await fetch(`${site}/api/events?since=${cursor}&limit=500`, { headers: { Authorization: `Bearer ${key}` } });
    if (!r.ok) throw new Error(`events ${r.status}`);
    const j = (await r.json()) as { events: Ev[]; cursor: number };
    out.push(...j.events);
    if (j.events.length < 500 || j.cursor === cursor) break;
    cursor = j.cursor;
  }
  return out;
}

const evs = (await load()).filter((e) => Date.parse(e.created_at) >= since || opt("--fixture"));
const isRoot = (e: Ev) => !e.root_task_id || e.root_task_id === e.task_id;
type Card = { tasks: number; steps: number; blocks: number; withSummary: number; progress: number; plans: number; reopened: number; waitMin: number[]; evidence: string[] };
const cards = new Map<string, Card>();
const card = (n: string) => cards.get(n) ?? (cards.set(n, { tasks: 0, steps: 0, blocks: 0, withSummary: 0, progress: 0, plans: 0, reopened: 0, waitMin: [], evidence: [] }), cards.get(n)!);
const lastAgentOnTask = new Map<string, string>();
const openBlocks = new Map<string, { agent: string; at: number }>();

for (const e of evs.sort((a, b) => a.id - b.id)) {
  const day = e.created_at.slice(0, 10);
  if (e.actor === "agent") {
    // Only events that count open a card: task.created carries the name guessed from the client before
    // the agent's own label ("Claude Code" vs "Claude Code in api"), which would add an empty card.
    if (!["subtasks.planned", "task.progress", "task.status"].includes(e.type)) continue;
    const name = e.actor_name || "agent";
    lastAgentOnTask.set(e.root_task_id || e.task_id, name);
    const c = card(name);
    if (e.type === "subtasks.planned") c.plans++;
    if (e.type === "task.progress") c.progress++;
    if (e.type === "task.status" && e.data?.to === "done") {
      if (isRoot(e)) {
        c.tasks++;
        if ((e.data.completed_summary ?? "").trim().length >= 20) c.withSummary++;
        else c.evidence.push(`${day} finished "${e.task_title}" without a summary of what changed and how it was checked`);
      } else c.steps++;
    }
    if (e.type === "task.status" && e.data?.to === "blocked") {
      c.blocks++;
      openBlocks.set(e.task_id, { agent: name, at: Date.parse(e.created_at) });
      if ((e.data.blocked_reason ?? "").length < 15) c.evidence.push(`${day} blocked "${e.task_title}" with a vague question: "${e.data.blocked_reason ?? ""}"`);
    }
  } else {
    // A human note or status change on a blocked task = the answer; measure how long the agent waited.
    const b = openBlocks.get(e.task_id);
    if (b && (e.type === "task.note" || e.type === "task.status")) {
      card(b.agent).waitMin.push(Math.round((Date.parse(e.created_at) - b.at) / 60_000));
      openBlocks.delete(e.task_id);
    }
    if (e.type === "task.status" && e.data?.from === "done" && e.data?.to !== "done") {
      const who = lastAgentOnTask.get(e.root_task_id || e.task_id) ?? "agent";
      card(who).reopened++;
      card(who).evidence.push(`${day} you reopened "${e.task_title}" after the agent marked it done`);
    }
  }
}

const median = (xs: number[]) => (xs.length ? [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)] : NaN);
console.log(`# Agent review, last ${days} days (${evs.length} events)\n`);
for (const [name, c] of cards) {
  const summaryRate = c.tasks ? Math.round((100 * c.withSummary) / c.tasks) : NaN;
  console.log(`## ${name}\n`);
  console.log("| KPI | Value | Bar |\n|---|---|---|");
  console.log(`| Tasks finished | ${c.tasks} | - |`);
  console.log(`| Steps finished | ${c.steps} | - |`);
  console.log(`| Plans posted | ${c.plans} | 1 per multi-step task |`);
  console.log(`| Progress reports | ${c.progress} | a few per long task |`);
  console.log(`| Done with a real summary | ${Number.isNaN(summaryRate) ? "-" : summaryRate + "%"} | 100% |`);
  console.log(`| Blocked questions | ${c.blocks} | - |`);
  console.log(`| Median wait for your answer | ${Number.isNaN(median(c.waitMin)) ? "-" : median(c.waitMin) + " min"} | your side of the deal |`);
  console.log(`| Reopened by you | ${c.reopened} | 0 |`);
  console.log(`\nEvidence:\n${c.evidence.slice(0, 8).map((x) => `- ${x}`).join("\n") || "- nothing to flag"}\n`);
  const plan: string[] = [];
  if (c.tasks && summaryRate < 100) plan.push("Done: taskhold_complete with what changed and how you checked it (tests run, page opened).");
  if (c.tasks >= 2 && c.plans < c.tasks / 2) plan.push("More than a couple of steps: taskhold_plan first, then start and complete each step.");
  if (c.reopened) plan.push("Before taskhold_complete, re-read the task's acceptance check and run it.");
  if (c.evidence.some((x) => x.includes("vague question"))) plan.push("Need a decision: taskhold_block with Decide/Answer/Approve/Access first, options and your recommendation (https://taskhold.com/docs/agent-messages).");
  console.log(`Instruction changes for CLAUDE.md / AGENTS.md:\n${plan.map((p) => `- ${p}`).join("\n") || "- none this week"}\n`);
}

export {};

```

## Sample output

From a run on October 26, 2026 against the live API, on a test account where one agent planned, reported and finished with a summary, and another asked a one-word question, finished without a summary and had its task reopened:

```md
# Agent review, last 7 days (18 events)

## Claude Code in api

| KPI | Value | Bar |
|---|---|---|
| Tasks finished | 1 | - |
| Steps finished | 3 | - |
| Plans posted | 1 | 1 per multi-step task |
| Progress reports | 1 | a few per long task |
| Done with a real summary | 100% | 100% |
| Blocked questions | 0 | - |
| Median wait for your answer | - | your side of the deal |
| Reopened by you | 0 | 0 |

Evidence:
- nothing to flag

Instruction changes for CLAUDE.md / AGENTS.md:
- none this week

## Codex in web

| KPI | Value | Bar |
|---|---|---|
| Tasks finished | 1 | - |
| Steps finished | 0 | - |
| Plans posted | 0 | 1 per multi-step task |
| Progress reports | 0 | a few per long task |
| Done with a real summary | 0% | 100% |
| Blocked questions | 1 | - |
| Median wait for your answer | 1 min | your side of the deal |
| Reopened by you | 1 | 0 |

Evidence:
- 2026-10-26 blocked "Fix CSV export" with a vague question: "which one?"
- 2026-10-26 finished "Fix CSV export" without a summary of what changed and how it was checked
- 2026-10-26 you reopened "Fix CSV export" after the agent marked it done

Instruction changes for CLAUDE.md / AGENTS.md:
- Done: taskhold_complete with what changed and how you checked it (tests run, page opened).
- Before taskhold_complete, re-read the task's acceptance check and run it.
- Need a decision: taskhold_block with Decide/Answer/Approve/Access first, options and your recommendation (https://taskhold.com/docs/agent-messages).
```

## Turn the suggestions into instructions

Each line under "Instruction changes" is written to paste into the agent's CLAUDE.md or AGENTS.md as is. Add the ones that match what you saw in the evidence, run the review again next week, and drop a line once that agent's scorecard is clean. The full instruction block is on the [quickstart](/docs/quickstart); clear block questions are covered in [agent messages](/docs/agent-messages).

## Related

- [Taskhold events API and Server-Sent Events stream](https://taskhold.com/docs/events.md)
- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md)
- [Slack alerts for blocked tasks from the events stream](https://taskhold.com/docs/slack-alerts.md)

---

# MCP tools reference

> Every Taskhold MCP tool: what it does, its arguments, what it returns and when an agent should call it. Remote server at taskhold.com/api/mcp.

Source: https://taskhold.com/docs/mcp-tools
Last updated: 2026-10-26

The remote MCP server is https://taskhold.com/api/mcp (Streamable HTTP, stateless), authenticated with the header Authorization: Bearer atd_sk_... It serves 19 tools. Tool results are plain text written for the agent, and every error says what to do next.

## Live progress tools

| Tool | Arguments | Use it to |
| --- | --- | --- |
| taskhold_plan | task_id, steps (strings or {title, description}, 1 to 50), replace? | Break a task into ordered steps. Returns the checklist with step ids. |
| taskhold_progress | task_id, percent? (0-100), current?, total?, message? | Move the bar inside a step or a step-less task. Give at least one of percent, total or message. |
| taskhold_updates | since? (cursor), include_agent? | Read what the person changed since the cursor: replies, new tasks, priority changes, unblocks. |

## Work tools

| Tool | Arguments | Use it to |
| --- | --- | --- |
| taskhold_get_current | none | See the task in progress, its steps and the next one. Call at session start. |
| taskhold_list | status?, priority?, project_id?, limit? (default 20) | List top-level tasks grouped by status. |
| taskhold_get | task_id | Read one task with description, steps, notes and summary. |
| taskhold_search | query, status? | Find tasks by text in title or description. |
| taskhold_start | task_id, agent? | Mark a task or step in progress. agent is the label shown on the board. |
| taskhold_complete | task_id, summary? | Finish a task or step. Completing a step returns the next one. |
| taskhold_block | task_id, reason | Stop and ask the person. The reason shows at the top of the board. |
| taskhold_unblock | task_id | Move a blocked task back to todo. |
| taskhold_add_note | task_id, note | Leave a finding or decision on the task's timeline. |
| taskhold_create | title, description?, priority?, project_id?, labels?, parent_task_id? | File new work, or one step with parent_task_id. |
| taskhold_create_from_todo | title, file_path, line_number, description? | File a TODO comment with its location. |
| taskhold_update | task_id, title?, description?, priority?, project_id? | Edit a task. |
| taskhold_set_priority | task_id, priority | Change priority (low, medium, high, urgent). |
| taskhold_list_projects | none | List projects. |
| taskhold_list_labels | none | List labels. |
| taskhold_get_summary | none | Counts by status, priority and who added them. |

## Example: report progress

A tools/call request over plain HTTP, the same thing an MCP client sends:

```bash
curl -s https://taskhold.com/api/mcp -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"taskhold_progress",
       "arguments":{"task_id":"TASK_ID","current":3,"total":5,"message":"Building api image"}}}'
```

The text the agent gets back:

```text
Progress on "Build images": [############--------] 60%
Now: Building api image
```

## Example: read replies

```text
- [2026-10-26T05:30:12.004Z] Human on "Send receipts from the new domain": Send from mail.example.com; the DNS records are in. (task c61740dd-...)

Cursor: 41 (pass as since next time)
```

taskhold_updates with since: 38. Without since, the latest 20 changes.

## Errors

Tool errors come back as isError results whose text names the problem and the next call: a task id that doesn't exist names taskhold_list, a missing key or subscription comes back as the 401 or 402 message from /docs/troubleshooting.

## Related

- [Taskhold REST API: tasks, steps, progress, curl examples](https://taskhold.com/docs/rest-api.md)
- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md)
- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md)

---

# REST API

> Taskhold REST API reference: authentication, tasks, steps, progress, notes, events and the live snapshot, with curl examples and real responses.

Source: https://taskhold.com/docs/rest-api
Last updated: 2026-10-26

Base URL https://taskhold.com/api. Every request sends Authorization: Bearer atd_sk_... and JSON bodies. Writes made with an API key are recorded as agent changes. The full machine-readable description is /openapi.json (OpenAPI 3.1).

## Name the caller

Send X-Taskhold-Agent with a label, for example "GitHub Actions (deploy)", and the board shows it on the card and in the activity feed. Without it Taskhold uses a known client from the User-Agent, then the API key's name.

## Endpoints

| Method and path | What it does |
| --- | --- |
| GET /api/tasks | List tasks. Filters: status, priority, project_id, created_by, parent_id, include_subtasks, limit, offset |
| POST /api/tasks | Create a task: title, description, priority, status, labels, parent_task_id, code_file_path, code_line_number |
| GET /api/tasks/current | The task in progress, with steps and rollups, or task: null |
| GET /api/tasks/{id} | One task with steps, notes, labels and project |
| PATCH /api/tasks/{id} | Update: status, blocked_reason, completed_summary, title, description, priority, project_id, agent_name |
| DELETE /api/tasks/{id} | Delete a task |
| GET /api/tasks/{id}/subtasks | Steps in order, with counts and overall progress |
| POST /api/tasks/{id}/subtasks | Add steps: {steps: [...], replace?} or one {title} |
| PUT /api/tasks/{id}/subtasks | Reorder steps: {order: [step ids]} |
| POST /api/tasks/{id}/progress | Report progress: percent, or current and total, and message. Reports on one task within 5 seconds merge into one event; an account can send 120 a minute (then 429 with Retry-After) |
| GET /api/tasks/{id}/notes | Notes on a task |
| POST /api/tasks/{id}/notes | Add a note: {content} |
| GET /api/events | Changes after a cursor (see /docs/events) |
| GET /api/events/stream | The same changes as Server-Sent Events |
| GET /api/live | What the live board shows, in one call |
| GET /api/projects, GET /api/labels, GET /api/summary | Projects, labels, counts |
| GET /api/account/export | Everything in the account as one JSON file: tasks with steps, notes and history, events, projects, labels, key names. The same file as Download my data in Settings |

## Create a task and plan steps

```bash
curl -s https://taskhold.com/api/tasks -H "Authorization: Bearer API_KEY" -H "Content-Type: application/json" \
  -H "X-Taskhold-Agent: deploy script" -d '{"title": "Deploy v2.4 to staging", "priority": "high"}'

curl -s -X PATCH https://taskhold.com/api/tasks/TASK_ID -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" -d '{"status": "in_progress"}'

curl -s https://taskhold.com/api/tasks/TASK_ID/subtasks -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" -d '{"steps": ["Build images", "Run migrations", "Smoke tests"]}'
```

```json
{"subtasks": [{"id": "0a017133-...", "title": "Build images", "status": "todo", ...}, ...],
 "task": {"id": "fd11278a-...", "status": "in_progress", "subtask_counts": {"total": 3, "done": 0, "in_progress": 0, "blocked": 0, "todo": 3}, "overall_progress": 0, ...}}
```

Response to the last call (201), shortened.

## Report progress

```bash
curl -s https://taskhold.com/api/tasks/STEP_ID/progress -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" -d '{"current": 3, "total": 5, "message": "Building api image"}'
```

```json
{"task": {"id": "0a017133-...", "progress": 60, "progress_current": 3, "progress_total": 5,
          "progress_message": "Building api image", "last_activity_at": "2026-10-26T05:09:47.401Z", ...}}
```

The parent task's overall_progress is now 20: one of three steps at 60%.

## Finish or block

```bash
curl -s -X PATCH https://taskhold.com/api/tasks/TASK_ID -H "Authorization: Bearer API_KEY" -H "Content-Type: application/json" \
  -d '{"status": "done", "completed_summary": "Deployed 2.4 to staging; smoke tests pass."}'

curl -s -X PATCH https://taskhold.com/api/tasks/TASK_ID -H "Authorization: Bearer API_KEY" -H "Content-Type: application/json" \
  -d '{"status": "blocked", "blocked_reason": "Decide: run the migration now or after hours?"}'
```

## Status codes

| Code | Meaning |
| --- | --- |
| 200, 201 | OK; the body holds the task (or list) after the change |
| 400 | Validation failed; details lists each field problem. Also: adding steps to a step (steps don't nest), more than 200 steps |
| 401 | Key missing, malformed, not a Taskhold key, or revoked. reason and message say which |
| 402 | The key is valid but the account has no active subscription |
| 403 | Fair-use ceiling reached (100,000 tasks) |
| 404 | Task or project not found in this account |

## Related

- [Taskhold events API and Server-Sent Events stream](https://taskhold.com/docs/events.md)
- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md)
- [Troubleshooting Taskhold: errors, missing tools, no progress](https://taskhold.com/docs/troubleshooting.md)

---

# Events and the live stream

> Follow every Taskhold change as it happens: the cursor feed at /api/events, the SSE stream at /api/events/stream, event types and a curl watcher.

Source: https://taskhold.com/docs/events
Last updated: 2026-10-26

Every create, status change, plan, progress report, note, edit and delete writes an event with an increasing id. Read them two ways: poll /api/events with a cursor, or hold open /api/events/stream and receive them as Server-Sent Events.

## Cursor feed

```bash
curl -s "https://taskhold.com/api/events?since=26" -H "Authorization: Bearer API_KEY"
```

```json
{"events": [
  {"id": 27, "type": "task.status", "actor": "agent", "actor_name": "GitHub Actions (deploy.yml)",
   "task_id": "0a017133-...", "root_task_id": "fd11278a-...", "task_title": "Build images", "summary": "Started",
   "data": {"from": "todo", "to": "in_progress", "blocked_reason": null, "completed_summary": null},
   "created_at": "2026-10-26T05:09:47.358Z"},
  {"id": 28, "type": "task.progress", "summary": "60% (3/5) Building api image", ...}
],
 "cursor": 28}
```

- since: return events after this id, oldest first. Without it you get the latest limit events (default 20).
- actor=human or actor=agent: only one side's changes. taskhold_updates uses actor=human.
- task_id: only events on this task and its steps.
- limit: up to 500. Pass the returned cursor as since next time.

## Event types

| type | When |
| --- | --- |
| task.created | A task or step was created |
| subtasks.planned | Steps were added with a plan |
| task.status | Status changed; data.from and data.to, plus blocked_reason or completed_summary |
| task.progress | Progress reported; summary like "60% (3/5) Building api image" |
| task.note | A note was added (replies to blocked tasks arrive this way) |
| task.updated | Title, description, priority or project changed |
| task.deleted | A task was deleted |

Progress events older than 14 days are pruned; the rest stay.

## Server-Sent Events

The stream starts at the current moment (or after Last-Event-ID, or ?since=), sends a ready event with the cursor, then one event: task frame per change. A comment line every 15 seconds keeps proxies from closing it, and the server ends each stream after 10 minutes; reconnect with Last-Event-ID and nothing is lost.

```text
retry: 3000
event: ready
data: {"cursor":26}

id: 27
event: task
data: {"id":27,"type":"task.status","actor":"agent","summary":"Started","task_title":"Build images",...}
```

## Watch from a terminal

One line per change, with curl and jq:

```bash
curl -sN https://taskhold.com/api/events/stream -H "Authorization: Bearer API_KEY" \
  | sed -un 's/^data: //p' \
  | jq -r --unbuffered 'select(.summary) | "\(.created_at[11:19])  \(.actor_name // .actor)  \(.task_title // ""): \(.summary)"'
```

```text
05:09:47  GitHub Actions (deploy.yml)  Build images: Started
05:09:47  GitHub Actions (deploy.yml)  Build images: 60% (3/5) Building api image
```

Browsers can't set an Authorization header on EventSource; in a browser, the signed-in web app uses its session cookie. From scripts, read the stream with fetch as in /docs/slack-alerts.

## Live snapshot

GET /api/live returns what the board shows in one call: active (in progress, with steps), blocked, recently_done (last 2 hours), up_next, counts (in_progress, blocked, todo, done_today), the latest events and the cursor to stream from.

## Related

- [Taskhold REST API: tasks, steps, progress, curl examples](https://taskhold.com/docs/rest-api.md)
- [Slack alerts for blocked tasks from the events stream](https://taskhold.com/docs/slack-alerts.md)
- [Review what each coding agent did this week](https://taskhold.com/docs/agent-review.md)
- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md)

---

# Troubleshooting

> Fixes for the common Taskhold problems: no taskhold tools in the agent, 401 and 402 responses, a bar that won't move, stale cards and silent streams.

Source: https://taskhold.com/docs/troubleshooting
Last updated: 2026-10-26

Find the symptom, try the fix, and if it still fails, email hello@greatwork.company with what you saw.

## The agent has no taskhold tools

- Claude Code: run claude mcp list. If taskhold is missing, paste a fresh setup URL from Settings, or run the claude mcp add command from /docs/quickstart.
- Restart the client or start a new session after adding the server; most clients load MCP servers at startup.
- Settings shows "Connected" only after the first call. If it never appears, the client isn't reaching https://taskhold.com/api/mcp.

## 401 Unauthorized

| reason | Cause | Fix |
| --- | --- | --- |
| missing_key | No Authorization header was sent | Add Authorization: Bearer atd_sk_... to the MCP config or request |
| bad_header | The header isn't "Bearer <key>" | Write the word Bearer, a space, then the key |
| not_a_taskhold_key | The key doesn't start with atd_sk_ | Use a key from Taskhold Settings |
| unknown_key | Revoked, mistyped, or from a deleted account | Make a new setup URL or key in Settings |

## 402 Subscription required

The key is fine, but the trial ended or the plan was canceled. Restart the plan at /dashboard/settings/billing and retry; the agent's config doesn't change.

## The bar doesn't move

- The task is still todo: the agent has to call taskhold_start before it shows under Working now.
- The task has steps: its bar comes from the steps. Report progress on the running step, or complete steps.
- The agent never calls taskhold_progress or taskhold_plan: add the block from /docs/quickstart to CLAUDE.md or AGENTS.md, or install the plugin's skill.

## A card says quiet or stale

Quiet means no report for 2 minutes, stale means 15. Long test runs or builds are often quiet and fine. A stale card usually means the session ended: open the task's timeline for the last note, then ask the next session to continue it or move it back to todo.

## The event stream stays silent behind a proxy

Some proxies buffer responses. Taskhold sends X-Accel-Buffering: no and Cache-Control: no-transform; if your own proxy sits in between, turn off response buffering for /api/events/stream, or poll /api/events with a cursor instead.

## Desktop notifications don't appear

Click "Notify me" on the live board and allow notifications when the browser asks. They fire while the board is open in a tab; for alerts when it's closed, see /docs/slack-alerts.

## Related

- [Quickstart: watch your agent's first plan in 5 minutes](https://taskhold.com/docs/quickstart.md)
- [Taskhold REST API: tasks, steps, progress, curl examples](https://taskhold.com/docs/rest-api.md)
- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md)

---

# Glossary

> What Taskhold means by blocked, step, progress report, agent label, setup URL, API key and live board, so agents, docs and people mean the same thing.

Source: https://taskhold.com/docs/glossary
Last updated: 2026-10-26

The words the docs, the live board and the MCP tools use, each in one or two sentences. Start with the [quickstart](/docs/quickstart) if you haven't connected an agent yet.

First check whether it's us: [/status](/status) runs live checks of the database, the MCP server and the live stream.

## Terms

| Term | Meaning |
| --- | --- |
| Blocked | A task an agent can't continue without you. The agent sets it with taskhold_block and one question; it goes to the top of the live board until you reply. |
| Step | One part of an agent's plan for a task, created with taskhold_plan. Steps are subtasks with their own status; the progress bar is split by them. |
| Progress report | A short update an agent sends with taskhold_progress: a percent or a count such as 12 of 40, plus a message. Reports on one task within 5 seconds of each other merge. |
| Agent label | The name shown on a task, such as "Claude Code in api-server". The agent passes it to taskhold_start; otherwise it comes from the client name or the key's name. |
| Setup URL | A link from Settings that configures an agent and carries a fresh API key. Paste it into the agent once; it expires after 3 days. |
| API key | The bearer token an agent sends on every call. Use one per machine and revoke it in Settings. |
| Live board | /dashboard/live: every task an agent is working on, with steps, progress, time left and blocked questions. |

## Related

- [Quickstart: watch your agent's first plan in 5 minutes](https://taskhold.com/docs/quickstart.md)
- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-progress.md)
- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md)

---

# Security and buying questions

> Where Taskhold stores data, what leaves your machine, subprocessors, auth, deletion, export, pricing and what isn't built: answers for a security review.

Source: https://taskhold.com/docs/security
Last updated: 2026-10-26

The questions a security review or a team lead asks before trying a new tool, answered from the [privacy policy](/privacy), the [terms](/terms) and the product itself. If something you need isn't here, email hello@greatwork.company.

## Answers

| Question | Answer | Where it's stated |
| --- | --- | --- |
| Where is data stored? | In a SQLite database on our own server at DigitalOcean in the US. | [Privacy policy](/privacy#who-processes-it-for-us) |
| What leaves my machine? | What your agent writes into tasks: titles, steps, progress messages, notes, and any file paths or line numbers it adds. Never your repository. | [Privacy policy](/privacy#what-we-collect) |
| Are tasks sent to an AI model? | No. Taskhold stores and shows them; it doesn't send them to any model. | [About](/about) |
| Who processes data for you? | DigitalOcean (hosting and backups), Stripe (payments) and Resend (email). | [Privacy policy](/privacy#who-processes-it-for-us) |
| How do people sign in? | Email sign-in links; there are no passwords. | [Privacy policy](/privacy) |
| How are agent keys stored? | As a SHA-256 hash, so the full key is shown once. One key per machine, each revocable in Settings. | [MCP tools](/docs/mcp-tools) |
| How do I delete my data? | Settings, Your data, Delete my account: it cancels the subscription and deletes everything at once. Backups roll over within 4 weeks. | [Privacy policy](/privacy#how-long-we-keep-it) |
| Can I export? | Yes: Download my data in Settings saves everything as one JSON file, with steps, notes and history. GET /api/account/export returns the same file with an API key. | [REST API](/docs/rest-api) |
| Am I locked in? | Tasks are plain JSON over a documented REST API and MCP. | [OpenAPI](/openapi.json) |
| What does it cost? | $12 a month or $120 a year per person, 7-day trial with a card, cancel in the Stripe portal. | [Pricing](/pricing.md) |
| Team workspaces, SSO, SOC 2? | None of these exist. Each person has their own list and signs in by email. | This page |
| How do I report a vulnerability? | See /.well-known/security.txt. | [security.txt](/.well-known/security.txt) |

## Related

- [Taskhold REST API: tasks, steps, progress, curl examples](https://taskhold.com/docs/rest-api.md)
- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md)
- [Glossary: blocked, steps, progress reports, setup URLs](https://taskhold.com/docs/glossary.md)