# Work your list with an agent

> Copy-paste prompts that make a coding agent work your Taskhold list as a queue: plan a goal into tasks, take the next one, wait, resume and stop.

Source: https://taskhold.com/docs/work-your-list
Last updated: 2026-11-16

Your agent can do more than report into Taskhold: it can take its work from it. taskhold_next takes the next task in To Do, starts it and hands the agent everything it needs. The agent does the task, completes it and calls taskhold_next again, until the list is empty.

The prompts below are ready to paste into Claude Code, Codex, Cursor or any agent with the Taskhold MCP server connected. Replace <project> with the repo folder name, the same name your tasks use. The dashboard has the main one with a Copy button on each project's task list.

## How the loop works

- taskhold_next takes the highest priority task first (urgent, high, medium, low). Inside a priority it takes the oldest first, so work that has waited longest goes next. To have it take the newest first instead (the order your To Do list shows), change Which task an agent takes next in Settings > Agents. To move one task ahead, raise its priority.
- It marks the task in progress with the agent's label and starts its first step, so a second agent calling at the same moment gets the next task instead. Steps, blocked tasks and tasks already in progress are never taken.
- Its reply has the task's full description, its steps, the latest notes and the project notes you wrote for agents, then the next call to make.
- When To Do is empty it says so, with what is still in progress or blocked, and the taskhold_updates call that waits for new work.

## Plan: turn a goal into queued tasks

Before a working session, when you know the goal but not the steps.

```text
Turn this goal into tasks on my Taskhold list, project "<project>": <the goal>.
Read the code you need first. Then file each piece of work with taskhold_create: one task per change I could review on its own, a title that says the outcome, and a description with the files involved and how to check it.
Give the first thing to do the highest priority. Don't start any of them.
When you're done, list the tasks in order with their ids.
```

## Work the list

The main loop. The agent takes the next task, does it, and comes back for the next one.

```text
Work through my Taskhold list for project "<project>", one task at a time.
1. Call taskhold_next with project "<project>" and agent: "<your client> in <project>". It takes the next task in To Do and starts it.
2. Read the task, its notes and the project notes in the reply. If it needs more than one step and has none, plan them with taskhold_plan.
3. Do the work. Finish each step with taskhold_complete and start_next: true. On a long step, report progress with taskhold_progress.
4. When the task is done, taskhold_complete it with a summary and an outcome (files, checks, how you verified it).
5. Call taskhold_next again. Stop when it says To Do is empty, and tell me what you finished.
If you need a decision, block that task with one question (taskhold_block) and move on to the next task instead of guessing.
Never spend money, touch credentials or secrets, publish or deploy anything, or delete anything that can't be undone without asking first: block the task with the question instead.
If you have to stop before a task is done, taskhold_release it with a note on where it stands.
```

## Keep going when the list is empty

Add it to the loop when you want the agent to wait for new tasks instead of stopping.

```text
When taskhold_next says To Do is empty, don't stop. Wait for new work with taskhold_updates (project "<project>", since: the cursor from your last call, wait: 50), then call taskhold_next again. Repeat until I tell you to stop.
Answers to tasks you blocked arrive the same way. When one comes, taskhold_start that task and finish it before taking a new one.
```

## Pick up after a crash

A session died or ran out of context in the middle of the list.

```text
An earlier session was working my Taskhold list and stopped. Call taskhold_get_current and taskhold_updates, both with project "<project>".
If a task is in progress, read it with taskhold_get and continue from its next open step. Don't redo the steps marked done.
If nothing is in progress, carry on with taskhold_next.
```

## Stop cleanly

You need the agent to stop without leaving a task half done and unexplained.

```text
Stop working the list. If the step you're on takes a few more minutes at most, finish it and complete it.
Otherwise taskhold_release the task with a note: what's done, what's left, and anything the next agent needs to know.
Don't take another task. Then tell me what you finished and what's still in To Do.
```

## Project notes: brief every task once

Each project has notes for agents: the stack, the commands to run, what done means and what to avoid. Write them once on the project's task list (Notes for agents, under the header) or on the Projects page. Every agent gets them with taskhold_next, taskhold_begin and taskhold_get_current for a task in that project, so a fresh session starts briefed. An agent can read them with taskhold_list_projects {project} and change them with taskhold_update_project {project, agent_notes}.

```text
Stack
Next.js 16, TypeScript, SQLite through knex. Bun, not npm.

Commands
bun test, then bunx tsc --noEmit before calling anything done.

Done means
Tests pass, the change is committed, and the summary says how you checked it.

Avoid
Don't edit .env files or deploy. Ask before adding a dependency.
```

Up to 4,000 characters. Plain text or markdown.

## What the agent reads back

taskhold_next in a project with notes, captured from a run against a test account on 2026-11-16:

```text
## Took the next task from To Do in project billing

[>] Send receipts from the new domain (!)
   ID: ae04ef68-...
   Status: in_progress | Priority: high | Added by: agent
   Project: billing
   Left in To Do after this one: 1

## Description

Use mail.example.com. The DNS records are in.

## Project notes (billing)

The person wrote these for every task in this project. Follow them unless the task says otherwise.

Stack
Next.js 16, SQLite through knex. Bun, not npm.
...

No steps yet. More than one step of work? Plan it first: taskhold_plan {task_id: "ae04ef68-...", steps}. When it's done: taskhold_complete {task_id: "ae04ef68-...", summary}.
Then call taskhold_next again for the one after. Need the person? taskhold_block with one question. Stopping before it's done? taskhold_release with a note.
```

And when nothing is left:

```text
To Do is empty in project billing: nothing to take. Still open in project billing: 2 in progress.
If you were working through the list, stop here and tell the person it's done.
To keep going instead, wait for new tasks with taskhold_updates {project: "billing", since: 4, wait: 50}, then call taskhold_next again.
```

## From a script

The REST API has the same call, for a CI job or a script that works the list without an MCP client. The body is optional; an unknown project name is never created.

```bash
curl -s -X POST https://taskhold.com/api/tasks/next -H "Authorization: Bearer $TASKHOLD_API_KEY" \
  -H "Content-Type: application/json" -d '{"project": "billing", "agent": "Nightly job"}'
```

It answers { task, step_started, remaining } with the task it started, or { task: null, in_progress, blocked } when To Do is empty (project_missing: true for a project name that doesn't exist). Project notes are on task.project.agent_notes.

## Related

- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md)
- [How agents should write progress notes and questions](https://taskhold.com/docs/agent-messages.md)
- [How live progress works: steps, bars, ETA and liveness](https://taskhold.com/docs/live-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.

To try it, add the MCP server https://taskhold.com/api/mcp to your agent. It connects with no sign-up, and the first time the agent uses Taskhold it gives you a link to start the trial.

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