Taskhold is an MCP server published by com.taskhold, hosted at taskhold.com. When last checked on 2026-11-22 it was working: it answers and lists its tools. It declares 24 tools, including taskhold_begin, taskhold_list, taskhold_get, taskhold_get_current, taskhold_next.
Shared task list for Claude Code, Cursor and Codex: live progress per step, questions you answer.
5 connections through 4 shared values. Tap any node.
Inferred from the host name and headers: what a server runs on, not who runs it.
Start work in one call: files a new task (or takes an existing one with task_id), plans its steps, marks it in progress and starts the first step. Use this whenever the person asks for something: it puts the request on their board with a checklist and a progress bar. Returns the task id, the numbered steps with ids, the step now running, project notes and a cursor for taskhold_updates. Every event of the call (created, planned, started) carries the agent label. On a task already under way it appends the steps. Fails without title or task_id, on an unknown task_id (get one from taskhold_list) or on a step (begin its parent, or taskhold_start the step).
| Parameter | Type | Description |
|---|---|---|
| agent | string | Label shown to the person: "<client> in <repo folder>", e.g. "Claude Code in api-server" ("Claude Code" outside a repo). |
| steps | array | The plan, in order, e.g. ["Read the code", "Write the migration", "Add tests"]. Omit for a one-step job. |
| title | string | Title of the new task (the person's request, short). Omit when passing task_id. |
None yet. Changes appear after a server's second daily check.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
| labels | array | Labels for a new task, e.g. ["bug", "refactor"] |
| project | string | Project name, e.g. the repo folder ("api-server"). Any case; created on first use. Easier than project_id. |
| task_id | string | Begin an existing task instead of filing a new one (from taskhold_list). |
| priority | string | Priority of a new task (default medium) |
| description | string | Details (markdown), e.g. the person's request in full |
| start_first_step | boolean | Also start the first step (default true) |
{
"name": "taskhold_begin",
"title": "Begin a task",
"description": "Start work in one call: files a new task (or takes an existing one with task_id), plans its steps, marks it in progress and starts the first step. Use this whenever the person asks for something: it puts the request on their board with a checklist and a progress bar. Returns the task id, the numbered steps with ids, the step now running, project notes and a cursor for taskhold_updates. Every event of the call (created, planned, started) carries the agent label. On a task already under way it appends the steps. Fails without title or task_id, on an unknown task_id (get one from taskhold_list) or on a step (begin its parent, or taskhold_start the step).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"agent": {
"type": "string",
"maxLength": 100,
"description": "Label shown to the person: \"<client> in <repo folder>\", e.g. \"Claude Code in api-server\" (\"Claude Code\" outside a repo)."
},
"steps": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"maxLength": 500,
"minLength": 1
},
{
"type": "object",
"required": [
"title"
],
"properties": {
"title": {
"type": "string",
"maxLength": 500,
"minLength": 1
},
"description": {
"type": "string",
"maxLength": 5000
}
}
}
]
},
"maxItems": 50,
"description": "The plan, in order, e.g. [\"Read the code\", \"Write the migration\", \"Add tests\"]. Omit for a one-step job."
},
"title": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Title of the new task (the person's request, short). Omit when passing task_id."
},
"labels": {
"type": "array",
"items": {
"type": "string",
"maxLength": 50,
"minLength": 1
},
"maxItems": 20,
"description": "Labels for a new task, e.g. [\"bug\", \"refactor\"]"
},
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Any case; created on first use. Easier than project_id."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "Begin an existing task instead of filing a new one (from taskhold_list)."
},
"priority": {
"enum": [
"low",
"medium",
"high",
"urgent"
],
"type": "string",
"description": "Priority of a new task (default medium)"
},
"description": {
"type": "string",
"maxLength": 10000,
"description": "Details (markdown), e.g. the person's request in full"
},
"start_first_step": {
"type": "boolean",
"description": "Also start the first step (default true)"
}
}
},
"annotations": {
"title": "Begin a task",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}List top-level tasks, one line each, grouped by status. Pass project to see one repo's work. Each line has status, title, steps done, progress and id; steps aren't listed (taskhold_get shows them). An unknown project name returns no tasks and is not created.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Max tasks to return (default 20) |
| status | string | Filter by status. Default: all. |
| project | string | Project name, e.g. the repo folder ("api-server"). Any case, or an id. Unknown names match nothing. |
| priority | string | Filter by priority |
| project_id | string | Filter by project id (project, a name, is easier) |
{
"name": "taskhold_list",
"title": "List tasks",
"description": "List top-level tasks, one line each, grouped by status. Pass project to see one repo's work. Each line has status, title, steps done, progress and id; steps aren't listed (taskhold_get shows them). An unknown project name returns no tasks and is not created.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Max tasks to return (default 20)"
},
"status": {
"enum": [
"todo",
"in_progress",
"blocked",
"done",
"all"
],
"type": "string",
"description": "Filter by status. Default: all."
},
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Any case, or an id. Unknown names match nothing."
},
"priority": {
"enum": [
"low",
"medium",
"high",
"urgent"
],
"type": "string",
"description": "Filter by priority"
},
"project_id": {
"type": "string",
"format": "uuid",
"description": "Filter by project id (project, a name, is easier)"
}
}
},
"annotations": {
"title": "List tasks",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get one task in full: status, priority, project, labels, repeat, time worked and waited on the person, description, numbered steps with ids and summaries, the 10 latest notes, the completion summary and what changed (files, checks, links, risks, how to verify). Unknown ids fail with "Task not found".
| Parameter | Type | Description |
|---|---|---|
| task_id * | string | The ID of the task to retrieve |
{
"name": "taskhold_get",
"title": "Get a task",
"description": "Get one task in full: status, priority, project, labels, repeat, time worked and waited on the person, description, numbered steps with ids and summaries, the 10 latest notes, the completion summary and what changed (files, checks, links, risks, how to verify). Unknown ids fail with \"Task not found\".",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to retrieve"
}
}
},
"annotations": {
"title": "Get a task",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Get the task in progress (in this project when you pass project), with its steps and the next one to do. Call this at the start of a session. Returns the most recently active in-progress task, its numbered steps with ids (with descriptions and the summaries of done steps), the next step's id, project notes and the latest 3 notes (taskhold_get shows 10); with nothing in progress (or an unknown project) it says so and names taskhold_begin and taskhold_next.
| Parameter | Type | Description |
|---|---|---|
| project | string | Project name, e.g. the repo folder ("api-server"). Any case, or an id. Unknown names match nothing. |
{
"name": "taskhold_get_current",
"title": "Get current tasks",
"description": "Get the task in progress (in this project when you pass project), with its steps and the next one to do. Call this at the start of a session. Returns the most recently active in-progress task, its numbered steps with ids (with descriptions and the summaries of done steps), the next step's id, project notes and the latest 3 notes (taskhold_get shows 10); with nothing in progress (or an unknown project) it says so and names taskhold_begin and taskhold_next.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Any case, or an id. Unknown names match nothing."
}
}
},
"annotations": {
"title": "Get current tasks",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Work the list as a queue: takes the next To Do task (highest priority, then oldest by default) and starts it and its first step. Atomic: no 2 agents get the same task. Returns the task, steps, project notes and next call, or that To Do is empty.
| Parameter | Type | Description |
|---|---|---|
| agent | string | Label shown to the person: "<client> in <repo folder>", e.g. "Claude Code in api-server" ("Claude Code" outside a repo). |
| project | string | Project name, e.g. the repo folder ("api-server"). Any case, or an id. Unknown names match nothing. |
{
"name": "taskhold_next",
"title": "Take the next task",
"description": "Work the list as a queue: takes the next To Do task (highest priority, then oldest by default) and starts it and its first step. Atomic: no 2 agents get the same task. Returns the task, steps, project notes and next call, or that To Do is empty.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"agent": {
"type": "string",
"maxLength": 100,
"description": "Label shown to the person: \"<client> in <repo folder>\", e.g. \"Claude Code in api-server\" (\"Claude Code\" outside a repo)."
},
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Any case, or an id. Unknown names match nothing."
}
}
},
"annotations": {
"title": "Take the next task",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Search tasks and steps by text in the title or description (case-insensitive, up to 100 tasks scanned). Returns matching lines grouped by status, with ids (a step names the task it belongs to), or a line saying nothing matched.
| Parameter | Type | Description |
|---|---|---|
| query * | string | Search text |
| status | string | Filter by status |
| project | string | Project name, e.g. the repo folder ("api-server"). Any case, or an id. Unknown names match nothing. |
| project_id | string | Filter by project id (project, a name, is easier) |
{
"name": "taskhold_search",
"title": "Search tasks",
"description": "Search tasks and steps by text in the title or description (case-insensitive, up to 100 tasks scanned). Returns matching lines grouped by status, with ids (a step names the task it belongs to), or a line saying nothing matched.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"minLength": 1,
"description": "Search text"
},
"status": {
"enum": [
"todo",
"in_progress",
"blocked",
"done",
"all"
],
"type": "string",
"description": "Filter by status"
},
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Any case, or an id. Unknown names match nothing."
},
"project_id": {
"type": "string",
"format": "uuid",
"description": "Filter by project id (project, a name, is easier)"
}
}
},
"annotations": {
"title": "Search tasks",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}File work for later (a bug, a follow-up, a chore); it lands in To Do. To file and start at once: taskhold_begin. parent_task_id adds one step to a task (taskhold_plan for several). Returns id, status and priority. Fails on an unknown parent_task_id or a step as parent, an unknown project_id (pass project by name) or at the task ceiling.
| Parameter | Type | Description |
|---|---|---|
| title * | string | Task title |
| labels | array | Labels, e.g. ["bug", "refactor"] |
| repeat | string | Repeat it: "every monday at 9am", "weekdays 8:30", "monthly on the 1st", "every 3 days". Adds a To Do copy unless the last is open. |
| project | string | Project name, e.g. the repo folder ("api-server"). Any case; created on first use. Easier than project_id. |
| priority | string | Priority (default medium) |
| project_id | string | Project id (project, a name, is easier) |
| description | string | Details (markdown) |
| parent_task_id | string | Make it a step (subtask) of this top-level task |
{
"name": "taskhold_create",
"title": "Create a task",
"description": "File work for later (a bug, a follow-up, a chore); it lands in To Do. To file and start at once: taskhold_begin. parent_task_id adds one step to a task (taskhold_plan for several). Returns id, status and priority. Fails on an unknown parent_task_id or a step as parent, an unknown project_id (pass project by name) or at the task ceiling.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"title"
],
"properties": {
"title": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Task title"
},
"labels": {
"type": "array",
"items": {
"type": "string",
"maxLength": 50,
"minLength": 1
},
"maxItems": 20,
"description": "Labels, e.g. [\"bug\", \"refactor\"]"
},
"repeat": {
"type": "string",
"description": "Repeat it: \"every monday at 9am\", \"weekdays 8:30\", \"monthly on the 1st\", \"every 3 days\". Adds a To Do copy unless the last is open."
},
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Any case; created on first use. Easier than project_id."
},
"priority": {
"enum": [
"low",
"medium",
"high",
"urgent"
],
"type": "string",
"description": "Priority (default medium)"
},
"project_id": {
"type": "string",
"format": "uuid",
"description": "Project id (project, a name, is easier)"
},
"description": {
"type": "string",
"maxLength": 10000,
"description": "Details (markdown)"
},
"parent_task_id": {
"type": "string",
"format": "uuid",
"description": "Make it a step (subtask) of this top-level task"
}
}
},
"annotations": {
"title": "Create a task",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Add ordered steps (subtasks) to a task so the person sees a checklist; the progress bar fills as steps finish. taskhold_begin already does this for new work. For an existing task: taskhold_start it, then taskhold_plan. Steps don't nest. Returns the task's whole step list with ids. Fails on an unknown task_id, on a step (plan its parent) or past 200 steps per task. Planning a done task adds todo steps but leaves it done; taskhold_start it to reopen.
| Parameter | Type | Description |
|---|---|---|
| steps * | array | Steps in order, e.g. ["Write the migration", "Update the API", "Add tests"] |
| replace | boolean | Replace steps that haven't started yet (done and in-progress steps stay). Default false: append. |
| task_id * | string | The ID of the task to plan |
{
"name": "taskhold_plan",
"title": "Plan task steps",
"description": "Add ordered steps (subtasks) to a task so the person sees a checklist; the progress bar fills as steps finish. taskhold_begin already does this for new work. For an existing task: taskhold_start it, then taskhold_plan. Steps don't nest. Returns the task's whole step list with ids. Fails on an unknown task_id, on a step (plan its parent) or past 200 steps per task. Planning a done task adds todo steps but leaves it done; taskhold_start it to reopen.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id",
"steps"
],
"properties": {
"steps": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"maxLength": 500,
"minLength": 1
},
{
"type": "object",
"required": [
"title"
],
"properties": {
"title": {
"type": "string",
"maxLength": 500,
"minLength": 1
},
"description": {
"type": "string",
"maxLength": 5000
}
}
}
]
},
"maxItems": 50,
"minItems": 1,
"description": "Steps in order, e.g. [\"Write the migration\", \"Update the API\", \"Add tests\"]"
},
"replace": {
"type": "boolean",
"description": "Replace steps that haven't started yet (done and in-progress steps stay). Default false: append."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to plan"
}
}
},
"annotations": {
"title": "Plan task steps",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
}
}Move the person's progress bar during a long step or a task without steps: percent, or current and total (e.g. 12 of 40 files), plus a short message about what's happening now. On a task with steps, the steps drive the bar: numbers you send for the task go to its running step. Call at milestones, every few minutes at most. Returns the task's progress bar and, on a task with steps, which step your numbers went to. Fails without percent, total or message, on an unknown task_id, or past the per-minute limit (the error says when to retry).
| Parameter | Type | Description |
|---|---|---|
| total | integer | Total items |
| current | integer | Items done so far, with total |
| message | string | What is happening now, e.g. "Running the test suite" |
| percent | number | 0-100 |
| task_id * | string | The ID of the task you are reporting on (a step, or a task without steps) |
{
"name": "taskhold_progress",
"title": "Report progress",
"description": "Move the person's progress bar during a long step or a task without steps: percent, or current and total (e.g. 12 of 40 files), plus a short message about what's happening now. On a task with steps, the steps drive the bar: numbers you send for the task go to its running step. Call at milestones, every few minutes at most. Returns the task's progress bar and, on a task with steps, which step your numbers went to. Fails without percent, total or message, on an unknown task_id, or past the per-minute limit (the error says when to retry).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Total items"
},
"current": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Items done so far, with total"
},
"message": {
"type": "string",
"maxLength": 500,
"description": "What is happening now, e.g. \"Running the test suite\""
},
"percent": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "0-100"
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task you are reporting on (a step, or a task without steps)"
}
}
},
"annotations": {
"title": "Report progress",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Create a task from a TODO comment in code, keeping the file path and line number (label todo-from-code plus any labels you pass; priority as in taskhold_create; use taskhold_create for anything else). Returns the new task with its id and code location. Fails at the account's task ceiling or on an invalid project name.
| Parameter | Type | Description |
|---|---|---|
| title * | string | Task title from the TODO |
| labels | array | More labels besides todo-from-code, e.g. ["bug"] |
| project | string | Project name, e.g. the repo folder ("api-server"). Any case; created on first use. Easier than project_id. |
| priority | string | Priority (default medium; low unless it's a real bug) |
| file_path * | string | Path of the file containing the TODO |
| description | string | Extra context from the code |
| line_number * | integer | Line number of the TODO |
{
"name": "taskhold_create_from_todo",
"title": "Create a task from a TODO",
"description": "Create a task from a TODO comment in code, keeping the file path and line number (label todo-from-code plus any labels you pass; priority as in taskhold_create; use taskhold_create for anything else). Returns the new task with its id and code location. Fails at the account's task ceiling or on an invalid project name.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"title",
"file_path",
"line_number"
],
"properties": {
"title": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Task title from the TODO"
},
"labels": {
"type": "array",
"items": {
"type": "string",
"maxLength": 50,
"minLength": 1
},
"maxItems": 19,
"description": "More labels besides todo-from-code, e.g. [\"bug\"]"
},
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Any case; created on first use. Easier than project_id."
},
"priority": {
"enum": [
"low",
"medium",
"high",
"urgent"
],
"type": "string",
"description": "Priority (default medium; low unless it's a real bug)"
},
"file_path": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "Path of the file containing the TODO"
},
"description": {
"type": "string",
"maxLength": 10000,
"description": "Extra context from the code"
},
"line_number": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Line number of the TODO",
"exclusiveMinimum": 0
}
}
},
"annotations": {
"title": "Create a task from a TODO",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Mark a task or step in progress when you begin it. Starting a step also starts its task. For new work, taskhold_begin files, plans and starts in one call. Returns the id, status and the next step's id when it has steps. Safe to repeat; it also resumes a blocked or done task. An unknown task_id fails with "Task not found".
| Parameter | Type | Description |
|---|---|---|
| agent | string | Label shown to the person: "<client> in <repo folder>", e.g. "Claude Code in api-server" ("Claude Code" outside a repo). |
| task_id * | string | The ID of the task to start |
{
"name": "taskhold_start",
"title": "Start a task",
"description": "Mark a task or step in progress when you begin it. Starting a step also starts its task. For new work, taskhold_begin files, plans and starts in one call. Returns the id, status and the next step's id when it has steps. Safe to repeat; it also resumes a blocked or done task. An unknown task_id fails with \"Task not found\".",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id"
],
"properties": {
"agent": {
"type": "string",
"maxLength": 100,
"description": "Label shown to the person: \"<client> in <repo folder>\", e.g. \"Claude Code in api-server\" (\"Claude Code\" outside a repo)."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to start"
}
}
},
"annotations": {
"title": "Start a task",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Mark a task or step done, with a summary of what you did and, optionally, a structured outcome: files changed (with +/- line counts), checks run (pass/fail/skip), links (PR, commit, branch, deploy, doc), follow-up task ids, risks and how the person can verify it. The person sees it as a What changed card; a step's outcome rolls up to its task. When the person should look at the work, pass needs_review: true with outcome.verify (how you checked it): the task lands in their Ready for review queue. Completing a step tells you the next one; start_next: true also starts it, and finish_task: true on the last open step closes the task too (with the same summary) in one call. For a step it returns steps done, the task's bar and the next step's id (or, after the last step, a reminder to complete the task). Completing a task closes its open steps. Repeating it on a task that is already done changes nothing and keeps the first summary (add more with taskhold_add_note); an unknown task_id fails with "Task not found", an invalid outcome fails without changing anything.
| Parameter | Type | Description |
|---|---|---|
| outcome | object | What changed, shown to the person as a What changed card (20 KB max). Every field is optional. |
| summary | string | What was done (and how you checked it). Markdown. |
| task_id * | string | The ID of the task to complete |
| start_next | boolean | When completing a step, start the next step too (default false) |
| finish_task | boolean | When completing the last open step, also complete its task with this summary (default false) |
| needs_review | boolean | Ask the person to review the work: the task goes to their Ready for review queue (it still counts as done). Needs outcome.verify, a short "how I checked it" line. They approve it or request changes; both arrive in taskhold_updates (default false) |
{
"name": "taskhold_complete",
"title": "Complete a task",
"description": "Mark a task or step done, with a summary of what you did and, optionally, a structured outcome: files changed (with +/- line counts), checks run (pass/fail/skip), links (PR, commit, branch, deploy, doc), follow-up task ids, risks and how the person can verify it. The person sees it as a What changed card; a step's outcome rolls up to its task. When the person should look at the work, pass needs_review: true with outcome.verify (how you checked it): the task lands in their Ready for review queue. Completing a step tells you the next one; start_next: true also starts it, and finish_task: true on the last open step closes the task too (with the same summary) in one call. For a step it returns steps done, the task's bar and the next step's id (or, after the last step, a reminder to complete the task). Completing a task closes its open steps. Repeating it on a task that is already done changes nothing and keeps the first summary (add more with taskhold_add_note); an unknown task_id fails with \"Task not found\", an invalid outcome fails without changing anything.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id"
],
"properties": {
"outcome": {
"type": "object",
"properties": {
"files": {
"type": "array",
"items": {
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"maxLength": 500,
"minLength": 1
},
"added": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"removed": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
}
},
"maxItems": 100,
"description": "Files changed, e.g. [{path: \"src/auth.ts\", added: 40, removed: 12}] (max 100)"
},
"links": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"url"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1
},
"kind": {
"enum": [
"pr",
"commit",
"branch",
"deploy",
"doc",
"other"
],
"type": "string"
},
"title": {
"type": "string",
"maxLength": 200
}
}
},
"maxItems": 20,
"description": "PR, commit, branch, deploy or doc links (url may be a sha or branch name) (max 20)"
},
"risks": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500,
"minLength": 1
},
"maxItems": 5,
"description": "What could go wrong or still needs a look (max 5)"
},
"checks": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"result"
],
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"detail": {
"type": "string",
"maxLength": 1000
},
"result": {
"enum": [
"pass",
"fail",
"skip"
],
"type": "string"
}
}
},
"maxItems": 20,
"description": "Checks you ran, e.g. [{name: \"bun test\", result: \"pass\", detail: \"212 tests\"}] (max 20)"
},
"verify": {
"type": "string",
"maxLength": 4000,
"description": "How the person can check it themselves, e.g. the command or page to open"
},
"follow_ups": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20,
"description": "Ids of tasks you filed for leftover work (from taskhold_create)"
}
},
"description": "What changed, shown to the person as a What changed card (20 KB max). Every field is optional."
},
"summary": {
"type": "string",
"maxLength": 5000,
"description": "What was done (and how you checked it). Markdown."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to complete"
},
"start_next": {
"type": "boolean",
"description": "When completing a step, start the next step too (default false)"
},
"finish_task": {
"type": "boolean",
"description": "When completing the last open step, also complete its task with this summary (default false)"
},
"needs_review": {
"type": "boolean",
"description": "Ask the person to review the work: the task goes to their Ready for review queue (it still counts as done). Needs outcome.verify, a short \"how I checked it\" line. They approve it or request changes; both arrive in taskhold_updates (default false)"
}
}
},
"annotations": {
"title": "Complete a task",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Mark a task (or step) blocked when you can't continue without the person (a decision, missing info, access). Returns the question and the exact taskhold_updates call to wait with. Write the reason as one question they can answer from the board in a line, e.g. "Decide: drop the legacy column or keep it nullable?". When the answer is a choice, pass 2-4 short options (with recommended and if_no_answer): the person answers with one tap and the reply reads Reply to "<question>": chose "<option>". The board shows it under Needs you. Wait for the reply with taskhold_updates {task_id, since, wait: 50}; keep working on anything that doesn't depend on it meanwhile. If the reply doesn't settle it, block again with a narrower question; don't guess. Blocking an already-blocked task asks the new question instead, and the earlier question stays in the task's history; an unknown task_id fails with "Task not found".
| Parameter | Type | Description |
|---|---|---|
| reason * | string | One answerable question, e.g. "Approve: deploy the migration to staging now?" |
| options | array | 2-4 short choices shown as buttons, e.g. ["Postgres", "SQLite", "Ask me later"]. Omit for an open question. |
| task_id * | string | The ID of the task to block |
| recommended | integer | Index into options of the one you recommend (0 = the first). Marked on the board. |
| if_no_answer | string | What you will do if nobody answers, e.g. "I'll use SQLite and keep going in 30 min." |
{
"name": "taskhold_block",
"title": "Block a task with a question",
"description": "Mark a task (or step) blocked when you can't continue without the person (a decision, missing info, access). Returns the question and the exact taskhold_updates call to wait with. Write the reason as one question they can answer from the board in a line, e.g. \"Decide: drop the legacy column or keep it nullable?\". When the answer is a choice, pass 2-4 short options (with recommended and if_no_answer): the person answers with one tap and the reply reads Reply to \"<question>\": chose \"<option>\". The board shows it under Needs you. Wait for the reply with taskhold_updates {task_id, since, wait: 50}; keep working on anything that doesn't depend on it meanwhile. If the reply doesn't settle it, block again with a narrower question; don't guess. Blocking an already-blocked task asks the new question instead, and the earlier question stays in the task's history; an unknown task_id fails with \"Task not found\".",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id",
"reason"
],
"properties": {
"reason": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "One answerable question, e.g. \"Approve: deploy the migration to staging now?\""
},
"options": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 1
},
"maxItems": 4,
"minItems": 2,
"description": "2-4 short choices shown as buttons, e.g. [\"Postgres\", \"SQLite\", \"Ask me later\"]. Omit for an open question."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to block"
},
"recommended": {
"type": "integer",
"maximum": 3,
"minimum": 0,
"description": "Index into options of the one you recommend (0 = the first). Marked on the board."
},
"if_no_answer": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "What you will do if nobody answers, e.g. \"I'll use SQLite and keep going in 30 min.\""
}
}
},
"annotations": {
"title": "Block a task with a question",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Move a blocked task back to todo once the blocker is resolved (taskhold_start resumes it directly). Returns the task with status todo. A task that isn't blocked is left as it is and the reply says its status; an unknown task_id fails with "Task not found".
| Parameter | Type | Description |
|---|---|---|
| task_id * | string | The ID of the task to unblock |
{
"name": "taskhold_unblock",
"title": "Unblock a task",
"description": "Move a blocked task back to todo once the blocker is resolved (taskhold_start resumes it directly). Returns the task with status todo. A task that isn't blocked is left as it is and the reply says its status; an unknown task_id fails with \"Task not found\".",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to unblock"
}
}
},
"annotations": {
"title": "Unblock a task",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Put unfinished work back in To Do, with a note, when you stop and nobody has to answer (e.g. waiting on a captcha). Its steps go too, your label comes off, progress stays. Need the person? taskhold_block. Done tasks are refused.
| Parameter | Type | Description |
|---|---|---|
| note | string | Where it stands and what's next |
| task_id * | string | The ID of the task to hand back |
{
"name": "taskhold_release",
"title": "Hand back a task",
"description": "Put unfinished work back in To Do, with a note, when you stop and nobody has to answer (e.g. waiting on a captcha). Its steps go too, your label comes off, progress stays. Need the person? taskhold_block. Done tasks are refused.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id"
],
"properties": {
"note": {
"type": "string",
"maxLength": 2000,
"description": "Where it stands and what's next"
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to hand back"
}
}
},
"annotations": {
"title": "Hand back a task",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Change a task's title, description, priority, project or repeat; only fields you pass change. Status goes through taskhold_start, taskhold_complete, taskhold_block and taskhold_release. Returns the task. Fails on an unknown task_id or project_id (pass project by name).
| Parameter | Type | Description |
|---|---|---|
| title | string | New title |
| repeat | string | "every monday at 9am" etc.; "off" stops it; "pause", "resume". |
| project | string | Project name, e.g. the repo folder ("api-server"). Move it to this project (matched case-insensitively, created on first use). |
| task_id * | string | The ID of the task to update |
| priority | string | New priority |
| project_id | any | Move to project by id (null to remove) |
| description | string | New description |
{
"name": "taskhold_update",
"title": "Edit a task",
"description": "Change a task's title, description, priority, project or repeat; only fields you pass change. Status goes through taskhold_start, taskhold_complete, taskhold_block and taskhold_release. Returns the task. Fails on an unknown task_id or project_id (pass project by name).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id"
],
"properties": {
"title": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "New title"
},
"repeat": {
"type": "string",
"description": "\"every monday at 9am\" etc.; \"off\" stops it; \"pause\", \"resume\"."
},
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Move it to this project (matched case-insensitively, created on first use)."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to update"
},
"priority": {
"enum": [
"low",
"medium",
"high",
"urgent"
],
"type": "string",
"description": "New priority"
},
"project_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Move to project by id (null to remove)"
},
"description": {
"type": "string",
"maxLength": 10000,
"description": "New description"
}
}
},
"annotations": {
"title": "Edit a task",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}Add a note to a task: findings, decisions, what you tried. The person reads these. Notes are append-only and shown oldest first (taskhold_get shows the latest 10). Returns a one-line confirmation; an unknown task_id fails with "Task not found".
| Parameter | Type | Description |
|---|---|---|
| note * | string | The note |
| task_id * | string | The ID of the task to add a note to |
{
"name": "taskhold_add_note",
"title": "Add a note",
"description": "Add a note to a task: findings, decisions, what you tried. The person reads these. Notes are append-only and shown oldest first (taskhold_get shows the latest 10). Returns a one-line confirmation; an unknown task_id fails with \"Task not found\".",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id",
"note"
],
"properties": {
"note": {
"type": "string",
"maxLength": 5000,
"minLength": 1,
"description": "The note"
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to add a note to"
}
}
},
"annotations": {
"title": "Add a note",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Change a task's priority. Returns the task title and new priority; an unknown task_id fails with "Task not found".
| Parameter | Type | Description |
|---|---|---|
| task_id * | string | The ID of the task to reprioritize |
| priority * | string | New priority |
{
"name": "taskhold_set_priority",
"title": "Set priority",
"description": "Change a task's priority. Returns the task title and new priority; an unknown task_id fails with \"Task not found\".",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id",
"priority"
],
"properties": {
"task_id": {
"type": "string",
"format": "uuid",
"description": "The ID of the task to reprioritize"
},
"priority": {
"enum": [
"low",
"medium",
"high",
"urgent"
],
"type": "string",
"description": "New priority"
}
}
},
"annotations": {
"title": "Set priority",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}What the person changed since you last looked: replies (notes), new tasks, priority changes, unblocks. Call when you resume, between steps, and after blocking (with wait, until the reply lands). Pass the last cursor you got (from any call) as since. Your own changes are hidden unless include_agent is true. Returns one line per change, oldest first (time, who, task, what, task id), then the next cursor, also when nothing is new. An unknown project returns no changes; an unknown task_id fails with "Task not found".
| Parameter | Type | Description |
|---|---|---|
| wait | integer | Seconds to wait for a change when there is none yet (0-50). Use after taskhold_block. |
| since | integer | Cursor from the previous call. Omit the first time (you get the latest 20). |
| project | string | Project name, e.g. the repo folder ("api-server"). Any case, or an id. Unknown names match nothing. |
| task_id | string | Only changes to this task and its steps (e.g. the one you blocked) |
| include_agent | boolean | Also include changes made by agents, yours included (default: the person's changes only) |
{
"name": "taskhold_updates",
"title": "Get the person's updates",
"description": "What the person changed since you last looked: replies (notes), new tasks, priority changes, unblocks. Call when you resume, between steps, and after blocking (with wait, until the reply lands). Pass the last cursor you got (from any call) as since. Your own changes are hidden unless include_agent is true. Returns one line per change, oldest first (time, who, task, what, task id), then the next cursor, also when nothing is new. An unknown project returns no changes; an unknown task_id fails with \"Task not found\".",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"wait": {
"type": "integer",
"maximum": 50,
"minimum": 0,
"description": "Seconds to wait for a change when there is none yet (0-50). Use after taskhold_block."
},
"since": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Cursor from the previous call. Omit the first time (you get the latest 20)."
},
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Any case, or an id. Unknown names match nothing."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "Only changes to this task and its steps (e.g. the one you blocked)"
},
"include_agent": {
"type": "boolean",
"description": "Also include changes made by agents, yours included (default: the person's changes only)"
}
}
},
"annotations": {
"title": "Get the person's updates",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}List projects with their open work, one line each. You rarely need this: every tool takes project as a name. Each line has the name, open counts (working, blocked, todo) and id. With project: that project's notes.
| Parameter | Type | Description |
|---|---|---|
| project | string | Project name, e.g. the repo folder ("api-server"). Any case, or an id. Unknown names match nothing. |
{
"name": "taskhold_list_projects",
"title": "List projects",
"description": "List projects with their open work, one line each. You rarely need this: every tool takes project as a name. Each line has the name, open counts (working, blocked, todo) and id. With project: that project's notes.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\"). Any case, or an id. Unknown names match nothing."
}
}
},
"annotations": {
"title": "List projects",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Create a project (a group of tasks, usually one per repo). Optional: any tool that takes project creates it on first use. A project with this name (any case) comes back unchanged, and the reply says if your description or color wasn't applied. Says whether it was created, restored or already existed, plus its id. Fails on an invalid name or at the project ceiling.
| Parameter | Type | Description |
|---|---|---|
| name * | string | Project name, e.g. the repo folder ("api-server") |
| color | string | Hex color for the board, e.g. "#2f6fdb" (default: picked from the name) |
| description | string | One line about it |
{
"name": "taskhold_create_project",
"title": "Create a project",
"description": "Create a project (a group of tasks, usually one per repo). Optional: any tool that takes project creates it on first use. A project with this name (any case) comes back unchanged, and the reply says if your description or color wasn't applied. Says whether it was created, restored or already existed, plus its id. Fails on an invalid name or at the project ceiling.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Project name, e.g. the repo folder (\"api-server\")"
},
"color": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$",
"description": "Hex color for the board, e.g. \"#2f6fdb\" (default: picked from the name)"
},
"description": {
"type": "string",
"maxLength": 500,
"description": "One line about it"
}
}
},
"annotations": {
"title": "Create a project",
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
}
}Change a project's name, description, color or project notes. Only fields you pass change. Returns the project as it is now. Fails on an unknown project (it is never created here), on a name another project already has, or with nothing to change.
| Parameter | Type | Description |
|---|---|---|
| name | string | New name |
| color | string | New hex color, e.g. "#2f6fdb" |
| project * | string | The project to change: its name (case-insensitive) or id, e.g. "api-server" |
| agent_notes | string | Notes every agent gets with tasks here (stack, commands, done means, avoid). Replaces them; "" clears. The person writes these: add, don't rewrite. |
| description | string | New one-line description ("" clears it) |
{
"name": "taskhold_update_project",
"title": "Edit a project",
"description": "Change a project's name, description, color or project notes. Only fields you pass change. Returns the project as it is now. Fails on an unknown project (it is never created here), on a name another project already has, or with nothing to change.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"project"
],
"properties": {
"name": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "New name"
},
"color": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$",
"description": "New hex color, e.g. \"#2f6fdb\""
},
"project": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "The project to change: its name (case-insensitive) or id, e.g. \"api-server\""
},
"agent_notes": {
"type": "string",
"maxLength": 4000,
"description": "Notes every agent gets with tasks here (stack, commands, done means, avoid). Replaces them; \"\" clears. The person writes these: add, don't rewrite."
},
"description": {
"type": "string",
"maxLength": 500,
"description": "New one-line description (\"\" clears it)"
}
}
},
"annotations": {
"title": "Edit a project",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}
}List the account's labels, one name per line. Labels are created by passing them to taskhold_create or taskhold_begin.
No parameters.
{
"name": "taskhold_list_labels",
"title": "List labels",
"description": "List the account's labels, one name per line. Labels are created by passing them to taskhold_create or taskhold_begin.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"annotations": {
"title": "List labels",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}Task counts by status, priority and who added them (human or agent). Returns the total and one list per grouping; counts top-level tasks only, not steps.
No parameters.
{
"name": "taskhold_get_summary",
"title": "Get a summary",
"description": "Task counts by status, priority and who added them (human or agent). Returns the total and one list per grouping; counts top-level tasks only, not steps.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"annotations": {
"title": "Get a summary",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false
}
}A task list shared between the person and you, with live progress. The person watches a live board while you work and sees every change you make. Pass project: "<repo folder name>" on every call so each repo's work stays together. Projects are matched by name (case-insensitive) and created on first use; you never need an id. Workflow: 1. Session start: taskhold_get_current {project} and taskhold_updates {project}. Keep the cursor. 2. New request from the person: taskhold_begin {title, project, steps, agent} files the task, plans the steps and starts it (and its first step) in one call. To pick up an existing task: taskhold_list {project, status: "todo"}, then taskhold_begin {task_id, steps}. Asked to work the list: taskhold_next {project, agent} takes and starts the next To Do task; repeat. 3. Finish each step with taskhold_complete {task_id: <step id>, start_next: true}; it starts the next step and tells you which one. Steps drive the progress bar. 4. Inside a long step, taskhold_progress {task_id: <step id>, current, total, message} at milestones. Every few minutes at most. 5. Findings and decisions: taskhold_add_note. 6. Need the person: taskhold_block {task_id, reason: one question}, then taskhold_updates {task_id, since: <cursor>, wait: 50} for the reply. Its result has a link to give them. Several decisions: block a step for each; /dashboard/decisions shows them all on one page. 7. Done: taskhold_complete on the task with a short summary (what changed, how you checked). 8. Stopping before it's done, with nothing to ask (out of time, waiting on a captcha or a deploy, not ready yet): taskhold_release {task_id, note: where it stands} puts it back in To Do for the next agent, progress kept, instead of leaving it in progress. Work you find but aren't doing now: taskhold_create {title, project} (or taskhold_create_from_todo). agent label: "<client> in <repo folder>", e.g. "Claude Code in api-server"; just "<client>" outside a repo.
Names, descriptions and schemas were written by the server and are shown as data.