A task management system built for AI agents. Official website: https://claudiacli.com/ Claudia provides structured task tracking with a Model Context Protocol (MCP) server, enabling AI assistants like Claude to manage their own work through hierarchical tasks, dependencies, sprints, and acceptance criteria verification. AI agents need a way to: - Track progress across complex, multi-step tasks -
Add this skill
npx mdskills install yuvalsuede/claudiaComprehensive task management system with MCP integration, multi-agent coordination, and rich CLI/web interface
1# Claudia23[](https://www.gnu.org/licenses/gpl-3.0)4[](https://bun.sh)5[](https://modelcontextprotocol.io)67**A task management system built for AI agents.**89Official website: https://claudiacli.com/1011Claudia provides structured task tracking with a Model Context Protocol (MCP) server, enabling AI assistants like Claude to manage their own work through hierarchical tasks, dependencies, sprints, and acceptance criteria verification.12131415## Why Claudia?1617AI agents need a way to:18- **Track progress** across complex, multi-step tasks19- **Coordinate** when multiple agents work on the same project20- **Remember context** between sessions (64KB JSON storage per task)21- **Verify work** against acceptance criteria before completion22- **Organize work** into sprints and project hierarchies2324Claudia provides all of this through both a CLI and MCP server interface.2526## Quick Start2728```bash29# Install Bun if you haven't already30curl -fsSL https://bun.sh/install | bash3132# Clone and build33git clone https://github.com/yuvalsuede/claudia.git34cd claudia35bun install36bun run build3738# Initialize and start using39./claudia db init40./claudia task create --title "My first task"41./claudia task list42```4344### Try the Demo4546See Claudia in action with sample data:4748```bash49# Seed demo project with sample tasks and sprints50bun run seed:demo5152# Open the web dashboard53./claudia @@ --port 333354```5556Then open http://localhost:3333 in your browser to explore the kanban board and sprint views.5758## Screenshots5960### Task Board616263### Sprint Management646566## Features6768| Feature | Description |69|---------|-------------|70| **Hierarchical Tasks** | Parent-child relationships with tree visualization |71| **State Machine** | Validated transitions: pending → in_progress → verification → completed |72| **Dependencies** | Block tasks until prerequisites complete, with cycle detection |73| **Sprints** | Group tasks into time-boxed work periods |74| **Multi-Project** | Isolated task namespaces with auto-detection from working directory |75| **Agent Memory** | 64KB JSON context storage per task |76| **Acceptance Criteria** | Define and verify requirements before task completion |77| **Multi-Agent Coordination** | Atomic task claiming, optimistic locking, conflict detection |78| **Web Dashboard** | Visual kanban board with project/sprint filtering |79| **MCP Server** | Drop-in integration with Claude Code and other MCP clients |8081## Installation8283### Prerequisites8485- [Bun](https://bun.sh) runtime (v1.0+)8687### From Source8889```bash90git clone https://github.com/yuvalsuede/claudia.git91cd claudia92bun install93```9495### Build Standalone Binary9697```bash98bun run build99# Creates ./claudia binary100101# Optional: install globally102cp claudia ~/.bun/bin/103```104105## Usage106107### CLI Commands108109#### Task Management110111```bash112# Create a task113claudia task create --title "Implement feature X" --priority p1114115# Create with acceptance criteria116claudia task create --title "Add login" --acceptance-criteria "Has email field" --acceptance-criteria "Has password field"117118# List tasks119claudia task list120claudia task list --status in_progress --priority p0,p1121122# Show task details123claudia task show <task-id>124125# Update a task126claudia task update <task-id> --title "New title" --priority p0127128# Transition status129claudia task transition <task-id> --to in_progress130131# Delete a task132claudia task delete <task-id> --force133```134135#### Task Hierarchy136137```bash138# Create a subtask139claudia task create --title "Subtask" --parent <parent-id>140141# View task tree142claudia task tree # Full tree143claudia task tree <task-id> # Subtree from task144```145146#### Task Context (Agent Memory)147148```bash149# Set context (overwrites)150claudia task context-set <task-id> '{"key": "value"}'151152# Merge context (deep merge)153claudia task context-merge <task-id> '{"additional": "data"}'154155# Get context156claudia task context-get <task-id>157```158159#### Dependencies160161```bash162# Add dependency (task depends on blocker)163claudia task depends <task-id> --on <blocker-id>164165# Remove dependency166claudia task undepends <task-id> --on <blocker-id>167168# Show dependencies169claudia task deps <task-id>170171# List blocked tasks172claudia task blocked173174# List ready tasks (all deps satisfied)175claudia task ready176```177178#### Sprints179180```bash181# Create a sprint182claudia sprint create --name "Sprint 1" --start 2024-01-15 --end 2024-01-29183184# List sprints185claudia sprint list186187# Show sprint with tasks188claudia sprint show <sprint-id>189190# Activate a sprint191claudia sprint activate <sprint-id>192```193194#### Projects195196```bash197# Create a project198claudia project create --name "My Project" --path /path/to/project199200# List projects201claudia project list202203# Select active project204claudia project select <project-id>205206# Show current project207claudia project current208```209210### Web Dashboard211212```bash213# Open dashboard in browser214claudia @@215216# Custom port217claudia @@ --port 8080218```219220The dashboard provides:221- **Tasks View**: Kanban board with drag-and-drop columns222- **Sprints View**: Sprint cards with progress indicators223- **Project Filter**: Scope views to specific projects224- **Clear Completed**: Archive finished tasks225226### MCP Server Integration227228Start the MCP server for use with Claude Code:229230```bash231claudia mcp232```233234#### Claude Code Configuration235236Add to `.mcp.json` in your project root:237238```json239{240 "mcpServers": {241 "claudia": {242 "command": "/path/to/claudia",243 "args": ["mcp"]244 }245 }246}247```248249Or for development (without building):250251```json252{253 "mcpServers": {254 "claudia": {255 "command": "bun",256 "args": ["run", "/path/to/claudia/src/mcp/server.ts"],257 "cwd": "/path/to/claudia"258 }259 }260}261```262263After adding the config, restart Claude Code to connect.264265#### Available MCP Tools266267**Compound Operations** (Recommended for agents)268269| Tool | Description |270|------|-------------|271| `task_start` | Create and start a task in one operation |272| `task_finish` | Complete a task with optional summary |273| `task_workspace` | Get current agent's workspace context |274| `task_handoff` | Transfer task to another agent |275| `task_abandon` | Release task back to pending |276277**Task Management**278279| Tool | Description |280|------|-------------|281| `task_create` | Create a new task |282| `task_read` | Get task by ID |283| `task_update` | Update task fields |284| `task_delete` | Delete a task |285| `task_list` | Query tasks with filters |286| `task_transition` | Change task status |287| `task_tree` | Get hierarchical task view |288289**Coordination**290291| Tool | Description |292|------|-------------|293| `task_claim` | Atomically claim a task |294| `task_release` | Release a claimed task |295| `task_blocked` | List blocked tasks |296| `task_ready` | List ready tasks |297| `task_dependency_add` | Add task dependency |298299**Verification**300301| Tool | Description |302|------|-------------|303| `task_verify` | Mark criterion as verified |304| `task_verification_status` | Get verification progress |305306See the [full MCP tools reference](#mcp-tools-reference) below for complete documentation.307308## Task Workflow309310```311┌─────────┐ ┌─────────────┐ ┌──────────────┐ ┌───────────┐312│ pending │────▶│ in_progress │────▶│ verification │────▶│ completed │313└─────────┘ └─────────────┘ └──────────────┘ └───────────┘314 │ │ │ │315 ▼ ▼ ▼ ▼316┌─────────┐ ┌──────────┐317│ blocked │ │ archived │ (terminal)318└─────────┘ └──────────┘319```320321**Valid transitions:**322- `pending` → `in_progress`, `blocked`, `archived`323- `in_progress` → `pending`, `verification`, `completed`, `blocked`, `archived`324- `verification` → `in_progress`, `completed`, `blocked`, `archived`325- `blocked` → `pending`, `in_progress`, `archived`326- `completed` → `in_progress`, `archived`327- `archived` → (terminal state)328329Tasks can skip `verification` if no acceptance criteria are defined.330331## Multi-Agent Coordination332333Claudia supports multiple AI agents working concurrently on the same project.334335### Task Claiming336337```typescript338// Claim before working339const result = await task_claim({ task_id: "uuid", agent_id: "agent-1" });340if (result.success) {341 // Task is yours - proceed342} else {343 // Already claimed by another agent344}345346// Release when done or on failure347await task_release({ task_id: "uuid", agent_id: "agent-1" });348```349350### Optimistic Locking351352```typescript353// Read task first354const task = await task_read({ id: "uuid" });355356// Update with version check357await task_update({358 id: task.id,359 title: "Updated",360 version: task.version // Fails if modified by another agent361});362```363364### Recommended Pattern3653661. `task_ready` - List tasks with satisfied dependencies3672. `task_claim` - Atomically reserve a task3683. `task_transition` - Move to `in_progress`3694. `task_context_merge` - Save progress3705. `task_transition` - Move to `completed`3716. On failure: `task_release` - Let another agent retry372373## Configuration374375| Environment Variable | Description | Default |376|---------------------|-------------|---------|377| `CLAUDIA_DB` | Database file path | `~/.claudia/tasks.db` |378379## Development380381```bash382# Development mode383bun run dev384385# Run tests386bun test387388# Type checking389bun run typecheck390```391392## Exit Codes393394| Code | Meaning |395|------|---------|396| 0 | Success |397| 1 | General error |398| 2 | Resource not found |399| 3 | Conflict (version mismatch) |400| 4 | Validation error |401| 5 | Storage error |402403## MCP Tools Reference404405<details>406<summary><strong>Compound Operations</strong></summary>407408#### task_start409Create and start a task in one operation. Auto-claims for the current agent.410411```json412{413 "title": "Task title",414 "description": "Optional description",415 "priority": "p0|p1|p2|p3",416 "parent_id": "optional-parent-uuid",417 "acceptance_criteria": ["criterion 1", "criterion 2"]418}419```420421#### task_finish422Complete a task with optional summary.423424```json425{426 "id": "task-uuid",427 "summary": "Optional completion summary"428}429```430431#### task_workspace432Get current agent's workspace context including claimed tasks.433434```json435{436 "include_completed": false437}438```439440#### task_handoff441Transfer task to another agent.442443```json444{445 "task_id": "task-uuid",446 "to_agent_id": "target-agent",447 "notes": "Optional handoff notes"448}449```450451#### task_abandon452Release task back to pending with reason.453454```json455{456 "task_id": "task-uuid",457 "reason": "Why abandoning"458}459```460461</details>462463<details>464<summary><strong>Task CRUD</strong></summary>465466#### task_create467```json468{469 "title": "Required title",470 "description": "Optional",471 "status": "pending",472 "priority": "p0|p1|p2|p3",473 "parent_id": "uuid",474 "sprint_id": "uuid",475 "tags": ["tag1", "tag2"],476 "assignee": "name",477 "acceptance_criteria": ["criterion"]478}479```480481#### task_read482```json483{ "id": "task-uuid" }484```485486#### task_update487```json488{489 "id": "task-uuid",490 "title": "New title",491 "version": 1492}493```494495#### task_delete496```json497{ "id": "task-uuid" }498```499500#### task_list501```json502{503 "status": ["pending", "in_progress"],504 "priority": ["p0", "p1"],505 "parent_id": "uuid",506 "sprint_id": "uuid",507 "assignee": "name",508 "limit": 100,509 "offset": 0510}511```512513#### task_transition514```json515{516 "id": "task-uuid",517 "to": "in_progress"518}519```520521#### task_tree522```json523{524 "id": "optional-root-uuid",525 "depth": 5526}527```528529</details>530531<details>532<summary><strong>Bulk Operations</strong></summary>533534#### task_create_many535```json536{537 "tasks": [538 { "title": "Task 1" },539 { "title": "Task 2" }540 ],541 "parent_id": "optional-common-parent",542 "sprint_id": "optional-common-sprint"543}544```545546#### task_update_many547```json548{549 "ids": ["uuid1", "uuid2"],550 "updates": {551 "priority": "p1",552 "assignee": "agent-1"553 }554}555```556557#### task_transition_many558```json559{560 "ids": ["uuid1", "uuid2"],561 "to": "completed",562 "skip_invalid": true563}564```565566</details>567568<details>569<summary><strong>Dependencies & Coordination</strong></summary>570571#### task_dependency_add572```json573{574 "task_id": "blocked-task",575 "depends_on_id": "blocking-task"576}577```578579#### task_dependency_remove580```json581{582 "task_id": "task-uuid",583 "depends_on_id": "dependency-uuid"584}585```586587#### task_dependencies588```json589{ "task_id": "task-uuid" }590```591592#### task_blocked593List all tasks with unsatisfied dependencies.594595#### task_ready596List all tasks ready to work on (dependencies satisfied).597598#### task_claim599```json600{601 "task_id": "task-uuid",602 "agent_id": "claiming-agent"603}604```605606#### task_release607```json608{609 "task_id": "task-uuid",610 "agent_id": "releasing-agent"611}612```613614</details>615616<details>617<summary><strong>Context Storage</strong></summary>618619#### task_context_set620Overwrite task context (max 64KB).621```json622{623 "id": "task-uuid",624 "context": { "any": "json data" }625}626```627628#### task_context_merge629Deep merge into existing context.630```json631{632 "id": "task-uuid",633 "context": { "additional": "data" }634}635```636637#### task_context_get638```json639{ "id": "task-uuid" }640```641642</details>643644<details>645<summary><strong>Verification</strong></summary>646647#### task_verify648Mark an acceptance criterion as verified.649```json650{651 "task_id": "task-uuid",652 "criterion_id": "criterion-uuid",653 "evidence": "Optional verification evidence"654}655```656657#### task_verification_status658Get verification progress for a task.659```json660{ "task_id": "task-uuid" }661```662663</details>664665<details>666<summary><strong>Sprints</strong></summary>667668#### sprint_create669```json670{671 "name": "Sprint 1",672 "start_at": "2024-01-15",673 "end_at": "2024-01-29"674}675```676677#### sprint_list678```json679{ "include_archived": false }680```681682#### sprint_show683```json684{ "id": "sprint-uuid" }685```686687#### sprint_update688```json689{690 "id": "sprint-uuid",691 "name": "New name",692 "status": "active"693}694```695696#### sprint_delete697```json698{ "id": "sprint-uuid" }699```700701#### sprint_activate702```json703{ "id": "sprint-uuid" }704```705706</details>707708<details>709<summary><strong>Projects</strong></summary>710711#### project_create712```json713{714 "name": "Project name",715 "description": "Optional",716 "path": "/optional/directory/path"717}718```719720#### project_list721List all projects.722723#### project_read724```json725{ "id": "project-uuid" }726```727728#### project_update729```json730{731 "id": "project-uuid",732 "name": "New name"733}734```735736#### project_delete737```json738{ "id": "project-uuid" }739```740741#### project_select742```json743{ "id": "project-uuid" }744```745746#### project_current747```json748{ "cwd": "/optional/path/for/autodetect" }749```750751</details>752753## Contributing754755We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.756757## License758759GPLv3 - see [LICENSE](LICENSE) for details.760
Full transparency — inspect the skill content before installing.