claim_task
Assign yourself to available tasks in Task Trellis MCP. Use to claim the next ready task, select by ID, or filter by project scope. Essential for AI agents to dynamically pick up and execute work items.
Instructions
Claims a task in the task trellis system
Use this tool to assign yourself to available tasks for execution. Essential for AI agents to pick up work items from the task queue and begin execution.
Claiming behavior:
Without 'taskId': Claims the next available task based on priority and readiness
With 'taskId': Claims a specific task by ID if available and ready
'scope': Limits claiming to tasks within a specific project or area
'force': Overrides normal claiming restrictions (use with caution)
Task readiness criteria:
Task status allows claiming (typically 'draft' or 'open' states)
All prerequisites are satisfied (prerequisite tasks completed)
Task is not already claimed by another agent
Task falls within specified scope if provided
Claiming workflow:
System evaluates available tasks against readiness criteria
Selects highest priority task that meets requirements
Updates task status to 'in-progress
Associates task with the claiming agent
Returns claimed task details for execution
Common patterns:
Claim any ready task: (no parameters)
Claim from project: scope='P-project-name'
Claim specific task: taskId='T-specific-task-id'
Force claim blocked task: taskId='T-task-id', force=true
Essential for autonomous task execution workflows where agents need to discover and claim work items dynamically.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Force claim flag (defaults to false) | |
| scope | No | Scope to claim task from (optional) | |
| taskId | No | Specific task ID to claim (optional) |
Input Schema (JSON Schema)
Implementation Reference
- src/tools/claimTaskTool.ts:56-72 (handler)The handler function for the 'claim_task' tool. It parses the input arguments and delegates to the TaskTrellisService.claimTask method.export async function handleClaimTask( service: TaskTrellisService, repository: Repository, args: unknown, ) { const { scope, taskId, force = false, } = args as { scope?: string; taskId?: string; force?: boolean; }; return service.claimTask(repository, scope, taskId, force); }
- src/tools/claimTaskTool.ts:4-54 (schema)Tool definition including name 'claim_task', detailed description, and input schema for parameters scope, taskId, force.export const claimTaskTool = { name: "claim_task", description: `Claims a task in the task trellis system Use this tool to assign yourself to available tasks for execution. Essential for AI agents to pick up work items from the task queue and begin execution. Claiming behavior: - Without 'taskId': Claims the next available task based on priority and readiness - With 'taskId': Claims a specific task by ID if available and ready - 'scope': Limits claiming to tasks within a specific project or area - 'force': Overrides normal claiming restrictions (use with caution) Task readiness criteria: - Task status allows claiming (typically 'draft' or 'open' states) - All prerequisites are satisfied (prerequisite tasks completed) - Task is not already claimed by another agent - Task falls within specified scope if provided Claiming workflow: 1. System evaluates available tasks against readiness criteria 2. Selects highest priority task that meets requirements 3. Updates task status to 'in-progress 4. Associates task with the claiming agent 5. Returns claimed task details for execution Common patterns: - Claim any ready task: (no parameters) - Claim from project: scope='P-project-name' - Claim specific task: taskId='T-specific-task-id' - Force claim blocked task: taskId='T-task-id', force=true Essential for autonomous task execution workflows where agents need to discover and claim work items dynamically.`, inputSchema: { type: "object", properties: { scope: { type: "string", description: "Scope to claim task from (optional)", }, taskId: { type: "string", description: "Specific task ID to claim (optional)", }, force: { type: "boolean", description: "Force claim flag (defaults to false)", default: false, }, }, }, } as const;
- src/server.ts:176-197 (registration)Registers the claimTaskTool in the list of tools provided by the ListToolsRequestHandler.server.setRequestHandler(ListToolsRequestSchema, () => { const tools: unknown[] = [ createObjectTool, updateObjectTool, getObjectTool, deleteObjectTool, listObjectsTool, appendObjectLogTool, appendModifiedFilesTool, claimTaskTool, getNextAvailableIssueTool, completeTaskTool, ]; // Only include activate tool if server is not properly configured from command line // (i.e., local mode without projectRootFolder specified) if (serverConfig.mode === "local" && !serverConfig.planningRootFolder) { tools.push(activateTool); } return { tools }; });
- src/server.ts:270-271 (registration)In the CallToolRequestHandler switch statement, dispatches the 'claim_task' tool call to handleClaimTask.case "claim_task": return handleClaimTask(_getService(), repository, args);
- Core implementation of task claiming logic: finds or claims specific task, validates, updates status to in-progress, handles hierarchy.export async function claimTask( repository: Repository, scope?: string, taskId?: string, force: boolean = false, ): Promise<{ content: Array<{ type: string; text: string }> }> { try { let claimedTask: TrellisObject; if (taskId) { claimedTask = await claimSpecificTask(taskId, force, repository); } else { claimedTask = await findNextAvailableTask(scope, repository); } const updatedTask = await updateTaskStatus(claimedTask, repository); return { content: [ { type: "text", text: `Successfully claimed task: ${JSON.stringify( { ...updatedTask, affectedFiles: Object.fromEntries(updatedTask.affectedFiles), }, null, 2, )}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error claiming task: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } }