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