> ## Documentation Index > Fetch the complete documentation index at: https://docs.namastex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Task Commands > Managing tasks in Automagik Forge ## Overview Forge tasks are managed primarily through the **Web UI** at `http://localhost:3000`. While there's no dedicated CLI for task operations, you can interact with tasks programmatically via REST API or MCP tools. *** ## Web UI Task Management The primary way to work with tasks: ```bash theme={null} # Start Forge automagik-forge # Open browser at http://localhost:3000 # Use the visual Kanban board to: # - Create tasks # - Drag & drop to change status # - Assign to AI agents # - Monitor execution # - Review results ``` *** ## Task Lifecycle Tasks flow through these states: ```mermaid theme={null} graph LR A[Backlog] --> B[Todo] B --> C[In Progress] C --> D[In Review] D --> E[Done] D --> C C --> F[Blocked] F --> C ``` **Initial State**: Tasks waiting to be prioritized * Created but not yet scheduled * Can be refined and estimated * Not assigned to agents yet **Ready for Work**: Prioritized and ready to execute * Clear acceptance criteria * Assigned to agent (optional) * Dependencies resolved **Active Execution**: AI agent working on task * Git worktree created * Agent executing code changes * Real-time logs streaming **Awaiting Approval**: Implementation complete * Code changes ready * Tests passing (ideally) * Waiting for human review **Completed**: Merged to main branch * Changes merged * Worktree cleaned up * Task archived **Waiting**: Dependencies or issues blocking progress * Missing information * External dependencies * Technical blockers *** ## Task Properties Each task has these fields: ```typescript theme={null} interface Task { id: string; // Unique identifier title: string; // Short description description: string; // Detailed requirements status: TaskStatus; // Current lifecycle state priority: "low" | "medium" | "high" | "critical"; labels: string[]; // Tags for organization assignee?: string; // AI agent or human createdAt: Date; updatedAt: Date; dueDate?: Date; // Execution details attempts: TaskAttempt[]; // Multiple AI agent tries worktreePath?: string; // Git worktree location branchName?: string; // Associated git branch // Integration githubIssue?: number; // Linked GitHub issue dependsOn?: string[]; // Task dependencies } ``` *** ## REST API Task Operations Interact with tasks programmatically when Forge is running: ### List Tasks ```bash theme={null} # Get all tasks curl http://localhost:5000/api/tasks # Filter by status curl "http://localhost:5000/api/tasks?status=in_progress" # Filter by label curl "http://localhost:5000/api/tasks?labels=bug,high-priority" ``` ### Create Task ```bash theme={null} curl -X POST http://localhost:5000/api/tasks \ -H "Content-Type: application/json" \ -d '{ "title": "Add user authentication", "description": "Implement JWT-based authentication with login and signup", "priority": "high", "labels": ["feature", "backend", "security"] }' ``` ### Get Task Details ```bash theme={null} curl http://localhost:5000/api/tasks/{task-id} ``` ### Update Task ```bash theme={null} curl -X PATCH http://localhost:5000/api/tasks/{task-id} \ -H "Content-Type: application/json" \ -d '{ "status": "in_progress", "assignee": "claude-code" }' ``` ### Delete Task ```bash theme={null} curl -X DELETE http://localhost:5000/api/tasks/{task-id} ``` *** ## MCP Task Tools When running in MCP mode (`--mcp` or `--mcp-advanced`), use these tools: **List and filter tasks** ```json theme={null} { "tool": "list_tasks", "arguments": { "project_id": "uuid-here", "status": "in_progress", "labels": ["bug"] } } ``` Returns array of tasks matching filters. **Create new task** ```json theme={null} { "tool": "create_task", "arguments": { "project_id": "uuid-here", "title": "Fix memory leak in WebSocket handler", "description": "Connections not cleaned up on disconnect", "priority": "high", "labels": ["bug", "performance"] } } ``` Returns created task with ID. **Get task details** ```json theme={null} { "tool": "get_task", "arguments": { "task_id": "task-uuid-here" } } ``` Returns complete task object with attempts and execution history. **Modify task properties** ```json theme={null} { "tool": "update_task", "arguments": { "task_id": "task-uuid-here", "status": "done", "labels": ["bug", "performance", "fixed"] } } ``` Returns updated task. **Remove task** ```json theme={null} { "tool": "delete_task", "arguments": { "task_id": "task-uuid-here" } } ``` Returns success confirmation. *** ## Task Attempts Each task can have multiple attempts from different AI agents. ### Creating Attempts ```bash theme={null} # Via Web UI: Click "New Attempt" button # Select agent: Claude Code, Gemini, Cursor CLI, etc. # Via API curl -X POST http://localhost:5000/api/tasks/{task-id}/attempts \ -H "Content-Type: application/json" \ -d '{ "agent": "claude-code", "prompt": "Implement this feature following best practices" }' ``` ### Comparing Attempts ```bash theme={null} # Get all attempts for a task curl http://localhost:5000/api/tasks/{task-id}/attempts # Get specific attempt curl http://localhost:5000/api/task-attempts/{attempt-id} # Stream diff for attempt curl http://localhost:5000/api/events/task-attempts/{attempt-id}/diff ``` ### Attempt States * **pending**: Queued for execution * **running**: AI agent actively working * **completed**: Finished successfully * **failed**: Execution failed * **cancelled**: Manually stopped *** ## Common Task Workflows ### Feature Development ```bash theme={null} # 1. Create feature task POST /api/tasks { "title": "Add dark mode toggle", "type": "feature", "labels": ["frontend", "ui"] } # 2. Try with multiple agents (via UI) # - Attempt 1: Claude Code # - Attempt 2: Cursor CLI # 3. Compare results (via UI) # Choose best implementation # 4. Merge to main PATCH /api/tasks/{id} { "status": "done" } ``` ### Bug Fix ```bash theme={null} # 1. Create bug task POST /api/tasks { "title": "Fix API timeout", "type": "bug", "priority": "high", "description": "API returns 504 after 30 seconds" } # 2. Assign to agent PATCH /api/tasks/{id} { "assignee": "claude-code" } # 3. Monitor execution GET /api/events/processes/{process-id}/logs # 4. Review and merge # Via Web UI ``` ### Code Refactoring ```bash theme={null} # 1. Create refactor task POST /api/tasks { "title": "Extract AuthService from UserController", "type": "refactor", "labels": ["backend", "cleanup"] } # 2. Try multiple approaches # Attempt 1: Extract methods # Attempt 2: Strategy pattern # Attempt 3: Service layer # 3. Compare and choose # Via Web UI comparison view # 4. Verify tests still pass # Check attempt test results # 5. Merge chosen approach ``` *** ## Task Labels Organize tasks with labels: * `feature` - New functionality * `bug` - Bug fixes * `refactor` - Code improvements * `docs` - Documentation * `test` - Testing * `chore` - Maintenance * `frontend` - UI/React code * `backend` - API/server code * `database` - Schema/queries * `devops` - Infrastructure * `security` - Security issues * `critical` - Urgent, blocking * `high` - Important, soon * `medium` - Normal priority * `low` - Nice to have Create your own: * `sprint-24` - Sprint tracking * `customer-reported` - Source * `technical-debt` - Cleanup * `experiment` - Exploratory *** ## Task Templates Create reusable task templates: ```json theme={null} // API Endpoint Template { "title": "Add {resource} API endpoint", "description": "Create REST API endpoint for {resource}\n\nRequirements:\n- Input validation\n- Error handling\n- Tests\n- Documentation", "labels": ["feature", "backend", "api"], "checklist": [ "Create route handler", "Add validation", "Write tests", "Update OpenAPI spec" ] } ``` *** ## Next Steps Manage projects and repositories Complete API documentation MCP integration details Task workflow examples