Docs / Recipes / How-to
Work your list with an agent
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.
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.
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.
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.
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.
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}.
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.What the agent reads back
taskhold_next in a project with notes, captured from a run against a test account on 2026-11-16:
## 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:
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.
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.
Read next
Updated 2026-11-16 · Markdown for agents · Questions: hello@greatwork.company