{
  "markdown": "# Claudia\n\n[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=flat&logo=bun&logoColor=white)](https://bun.sh)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)\n\n**A task management system built for AI agents.**\n\nOfficial website: https://claudiacli.com/\n\nClaudia 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.\n\n![Claudia Dashboard Demo](assets/claudia-demo.gif)\n\n## Why Claudia?\n\nAI agents need a way to:\n- **Track progress** across complex, multi-step tasks\n- **Coordinate** when multiple agents work on the same project\n- **Remember context** between sessions (64KB JSON storage per task)\n- **Verify work** against acceptance criteria before completion\n- **Organize work** into sprints and project hierarchies\n\nClaudia provides all of this through both a CLI and MCP server interface.\n\n## Quick Start\n\n```bash\n# Install Bun if you haven't already\ncurl -fsSL https://bun.sh/install | bash\n\n# Clone and build\ngit clone https://github.com/yuvalsuede/claudia.git\ncd claudia\nbun install\nbun run build\n\n# Initialize and start using\n./claudia db init\n./claudia task create --title \"My first task\"\n./claudia task list\n```\n\n### Try the Demo\n\nSee Claudia in action with sample data:\n\n```bash\n# Seed demo project with sample tasks and sprints\nbun run seed:demo\n\n# Open the web dashboard\n./claudia @@ --port 3333\n```\n\nThen open http://localhost:3333 in your browser to explore the kanban board and sprint views.\n\n## Screenshots\n\n### Task Board\n![Claudia Tasks View](assets/claudia-tasks.png)\n\n### Sprint Management\n![Claudia Sprints View](assets/claudia-sprints.png)\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Hierarchical Tasks** | Parent-child relationships with tree visualization |\n| **State Machine** | Validated transitions: pending → in_progress → verification → completed |\n| **Dependencies** | Block tasks until prerequisites complete, with cycle detection |\n| **Sprints** | Group tasks into time-boxed work periods |\n| **Multi-Project** | Isolated task namespaces with auto-detection from working directory |\n| **Agent Memory** | 64KB JSON context storage per task |\n| **Acceptance Criteria** | Define and verify requirements before task completion |\n| **Multi-Agent Coordination** | Atomic task claiming, optimistic locking, conflict detection |\n| **Web Dashboard** | Visual kanban board with project/sprint filtering |\n| **MCP Server** | Drop-in integration with Claude Code and other MCP clients |\n\n## Installation\n\n### Prerequisites\n\n- [Bun](https://bun.sh) runtime (v1.0+)\n\n### From Source\n\n```bash\ngit clone https://github.com/yuvalsuede/claudia.git\ncd claudia\nbun install\n```\n\n### Build Standalone Binary\n\n```bash\nbun run build\n# Creates ./claudia binary\n\n# Optional: install globally\ncp claudia ~/.bun/bin/\n```\n\n## Usage\n\n### CLI Commands\n\n#### Task Management\n\n```bash\n# Create a task\nclaudia task create --title \"Implement feature X\" --priority p1\n\n# Create with acceptance criteria\nclaudia task create --title \"Add login\" --acceptance-criteria \"Has email field\" --acceptance-criteria \"Has password field\"\n\n# List tasks\nclaudia task list\nclaudia task list --status in_progress --priority p0,p1\n\n# Show task details\nclaudia task show <task-id>\n\n# Update a task\nclaudia task update <task-id> --title \"New title\" --priority p0\n\n# Transition status\nclaudia task transition <task-id> --to in_progress\n\n# Delete a task\nclaudia task delete <task-id> --force\n```\n\n#### Task Hierarchy\n\n```bash\n# Create a subtask\nclaudia task create --title \"Subtask\" --parent <parent-id>\n\n# View task tree\nclaudia task tree              # Full tree\nclaudia task tree <task-id>    # Subtree from task\n```\n\n#### Task Context (Agent Memory)\n\n```bash\n# Set context (overwrites)\nclaudia task context-set <task-id> '{\"key\": \"value\"}'\n\n# Merge context (deep merge)\nclaudia task context-merge <task-id> '{\"additional\": \"data\"}'\n\n# Get context\nclaudia task context-get <task-id>\n```\n\n#### Dependencies\n\n```bash\n# Add dependency (task depends on blocker)\nclaudia task depends <task-id> --on <blocker-id>\n\n# Remove dependency\nclaudia task undepends <task-id> --on <blocker-id>\n\n# Show dependencies\nclaudia task deps <task-id>\n\n# List blocked tasks\nclaudia task blocked\n\n# List ready tasks (all deps satisfied)\nclaudia task ready\n```\n\n#### Sprints\n\n```bash\n# Create a sprint\nclaudia sprint create --name \"Sprint 1\" --start 2024-01-15 --end 2024-01-29\n\n# List sprints\nclaudia sprint list\n\n# Show sprint with tasks\nclaudia sprint show <sprint-id>\n\n# Activate a sprint\nclaudia sprint activate <sprint-id>\n```\n\n#### Projects\n\n```bash\n# Create a project\nclaudia project create --name \"My Project\" --path /path/to/project\n\n# List projects\nclaudia project list\n\n# Select active project\nclaudia project select <project-id>\n\n# Show current project\nclaudia project current\n```\n\n### Web Dashboard\n\n```bash\n# Open dashboard in browser\nclaudia @@\n\n# Custom port\nclaudia @@ --port 8080\n```\n\nThe dashboard provides:\n- **Tasks View**: Kanban board with drag-and-drop columns\n- **Sprints View**: Sprint cards with progress indicators\n- **Project Filter**: Scope views to specific projects\n- **Clear Completed**: Archive finished tasks\n\n### MCP Server Integration\n\nStart the MCP server for use with Claude Code:\n\n```bash\nclaudia mcp\n```\n\n#### Claude Code Configuration\n\nAdd to `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"claudia\": {\n      \"command\": \"/path/to/claudia\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nOr for development (without building):\n\n```json\n{\n  \"mcpServers\": {\n    \"claudia\": {\n      \"command\": \"bun\",\n      \"args\": [\"run\", \"/path/to/claudia/src/mcp/server.ts\"],\n      \"cwd\": \"/path/to/claudia\"\n    }\n  }\n}\n```\n\nAfter adding the config, restart Claude Code to connect.\n\n#### Available MCP Tools\n\n**Compound Operations** (Recommended for agents)\n\n| Tool | Description |\n|------|-------------|\n| `task_start` | Create and start a task in one operation |\n| `task_finish` | Complete a task with optional summary |\n| `task_workspace` | Get current agent's workspace context |\n| `task_handoff` | Transfer task to another agent |\n| `task_abandon` | Release task back to pending |\n\n**Task Management**\n\n| Tool | Description |\n|------|-------------|\n| `task_create` | Create a new task |\n| `task_read` | Get task by ID |\n| `task_update` | Update task fields |\n| `task_delete` | Delete a task |\n| `task_list` | Query tasks with filters |\n| `task_transition` | Change task status |\n| `task_tree` | Get hierarchical task view |\n\n**Coordination**\n\n| Tool | Description |\n|------|-------------|\n| `task_claim` | Atomically claim a task |\n| `task_release` | Release a claimed task |\n| `task_blocked` | List blocked tasks |\n| `task_ready` | List ready tasks |\n| `task_dependency_add` | Add task dependency |\n\n**Verification**\n\n| Tool | Description |\n|------|-------------|\n| `task_verify` | Mark criterion as verified |\n| `task_verification_status` | Get verification progress |\n\nSee the [full MCP tools reference](#mcp-tools-reference) below for complete documentation.\n\n## Task Workflow\n\n```\n┌─────────┐     ┌─────────────┐     ┌──────────────┐     ┌───────────┐\n│ pending │────▶│ in_progress │────▶│ verification │────▶│ completed │\n└─────────┘     └─────────────┘     └──────────────┘     └───────────┘\n     │                │                    │                    │\n     ▼                ▼                    ▼                    ▼\n┌─────────┐                         ┌──────────┐\n│ blocked │                         │ archived │ (terminal)\n└─────────┘                         └──────────┘\n```\n\n**Valid transitions:**\n- `pending` → `in_progress`, `blocked`, `archived`\n- `in_progress` → `pending`, `verification`, `completed`, `blocked`, `archived`\n- `verification` → `in_progress`, `completed`, `blocked`, `archived`\n- `blocked` → `pending`, `in_progress`, `archived`\n- `completed` → `in_progress`, `archived`\n- `archived` → (terminal state)\n\nTasks can skip `verification` if no acceptance criteria are defined.\n\n## Multi-Agent Coordination\n\nClaudia supports multiple AI agents working concurrently on the same project.\n\n### Task Claiming\n\n```typescript\n// Claim before working\nconst result = await task_claim({ task_id: \"uuid\", agent_id: \"agent-1\" });\nif (result.success) {\n  // Task is yours - proceed\n} else {\n  // Already claimed by another agent\n}\n\n// Release when done or on failure\nawait task_release({ task_id: \"uuid\", agent_id: \"agent-1\" });\n```\n\n### Optimistic Locking\n\n```typescript\n// Read task first\nconst task = await task_read({ id: \"uuid\" });\n\n// Update with version check\nawait task_update({\n  id: task.id,\n  title: \"Updated\",\n  version: task.version  // Fails if modified by another agent\n});\n```\n\n### Recommended Pattern\n\n1. `task_ready` - List tasks with satisfied dependencies\n2. `task_claim` - Atomically reserve a task\n3. `task_transition` - Move to `in_progress`\n4. `task_context_merge` - Save progress\n5. `task_transition` - Move to `completed`\n6. On failure: `task_release` - Let another agent retry\n\n## Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `CLAUDIA_DB` | Database file path | `~/.claudia/tasks.db` |\n\n## Development\n\n```bash\n# Development mode\nbun run dev\n\n# Run tests\nbun test\n\n# Type checking\nbun run typecheck\n```\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | General error |\n| 2 | Resource not found |\n| 3 | Conflict (version mismatch) |\n| 4 | Validation error |\n| 5 | Storage error |\n\n## MCP Tools Reference\n\n<details>\n<summary><strong>Compound Operations</strong></summary>\n\n#### task_start\nCreate and start a task in one operation. Auto-claims for the current agent.\n\n```json\n{\n  \"title\": \"Task title\",\n  \"description\": \"Optional description\",\n  \"priority\": \"p0|p1|p2|p3\",\n  \"parent_id\": \"optional-parent-uuid\",\n  \"acceptance_criteria\": [\"criterion 1\", \"criterion 2\"]\n}\n```\n\n#### task_finish\nComplete a task with optional summary.\n\n```json\n{\n  \"id\": \"task-uuid\",\n  \"summary\": \"Optional completion summary\"\n}\n```\n\n#### task_workspace\nGet current agent's workspace context including claimed tasks.\n\n```json\n{\n  \"include_completed\": false\n}\n```\n\n#### task_handoff\nTransfer task to another agent.\n\n```json\n{\n  \"task_id\": \"task-uuid\",\n  \"to_agent_id\": \"target-agent\",\n  \"notes\": \"Optional handoff notes\"\n}\n```\n\n#### task_abandon\nRelease task back to pending with reason.\n\n```json\n{\n  \"task_id\": \"task-uuid\",\n  \"reason\": \"Why abandoning\"\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Task CRUD</strong></summary>\n\n#### task_create\n```json\n{\n  \"title\": \"Required title\",\n  \"description\": \"Optional\",\n  \"status\": \"pending\",\n  \"priority\": \"p0|p1|p2|p3\",\n  \"parent_id\": \"uuid\",\n  \"sprint_id\": \"uuid\",\n  \"tags\": [\"tag1\", \"tag2\"],\n  \"assignee\": \"name\",\n  \"acceptance_criteria\": [\"criterion\"]\n}\n```\n\n#### task_read\n```json\n{ \"id\": \"task-uuid\" }\n```\n\n#### task_update\n```json\n{\n  \"id\": \"task-uuid\",\n  \"title\": \"New title\",\n  \"version\": 1\n}\n```\n\n#### task_delete\n```json\n{ \"id\": \"task-uuid\" }\n```\n\n#### task_list\n```json\n{\n  \"status\": [\"pending\", \"in_progress\"],\n  \"priority\": [\"p0\", \"p1\"],\n  \"parent_id\": \"uuid\",\n  \"sprint_id\": \"uuid\",\n  \"assignee\": \"name\",\n  \"limit\": 100,\n  \"offset\": 0\n}\n```\n\n#### task_transition\n```json\n{\n  \"id\": \"task-uuid\",\n  \"to\": \"in_progress\"\n}\n```\n\n#### task_tree\n```json\n{\n  \"id\": \"optional-root-uuid\",\n  \"depth\": 5\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Bulk Operations</strong></summary>\n\n#### task_create_many\n```json\n{\n  \"tasks\": [\n    { \"title\": \"Task 1\" },\n    { \"title\": \"Task 2\" }\n  ],\n  \"parent_id\": \"optional-common-parent\",\n  \"sprint_id\": \"optional-common-sprint\"\n}\n```\n\n#### task_update_many\n```json\n{\n  \"ids\": [\"uuid1\", \"uuid2\"],\n  \"updates\": {\n    \"priority\": \"p1\",\n    \"assignee\": \"agent-1\"\n  }\n}\n```\n\n#### task_transition_many\n```json\n{\n  \"ids\": [\"uuid1\", \"uuid2\"],\n  \"to\": \"completed\",\n  \"skip_invalid\": true\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Dependencies & Coordination</strong></summary>\n\n#### task_dependency_add\n```json\n{\n  \"task_id\": \"blocked-task\",\n  \"depends_on_id\": \"blocking-task\"\n}\n```\n\n#### task_dependency_remove\n```json\n{\n  \"task_id\": \"task-uuid\",\n  \"depends_on_id\": \"dependency-uuid\"\n}\n```\n\n#### task_dependencies\n```json\n{ \"task_id\": \"task-uuid\" }\n```\n\n#### task_blocked\nList all tasks with unsatisfied dependencies.\n\n#### task_ready\nList all tasks ready to work on (dependencies satisfied).\n\n#### task_claim\n```json\n{\n  \"task_id\": \"task-uuid\",\n  \"agent_id\": \"claiming-agent\"\n}\n```\n\n#### task_release\n```json\n{\n  \"task_id\": \"task-uuid\",\n  \"agent_id\": \"releasing-agent\"\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Context Storage</strong></summary>\n\n#### task_context_set\nOverwrite task context (max 64KB).\n```json\n{\n  \"id\": \"task-uuid\",\n  \"context\": { \"any\": \"json data\" }\n}\n```\n\n#### task_context_merge\nDeep merge into existing context.\n```json\n{\n  \"id\": \"task-uuid\",\n  \"context\": { \"additional\": \"data\" }\n}\n```\n\n#### task_context_get\n```json\n{ \"id\": \"task-uuid\" }\n```\n\n</details>\n\n<details>\n<summary><strong>Verification</strong></summary>\n\n#### task_verify\nMark an acceptance criterion as verified.\n```json\n{\n  \"task_id\": \"task-uuid\",\n  \"criterion_id\": \"criterion-uuid\",\n  \"evidence\": \"Optional verification evidence\"\n}\n```\n\n#### task_verification_status\nGet verification progress for a task.\n```json\n{ \"task_id\": \"task-uuid\" }\n```\n\n</details>\n\n<details>\n<summary><strong>Sprints</strong></summary>\n\n#### sprint_create\n```json\n{\n  \"name\": \"Sprint 1\",\n  \"start_at\": \"2024-01-15\",\n  \"end_at\": \"2024-01-29\"\n}\n```\n\n#### sprint_list\n```json\n{ \"include_archived\": false }\n```\n\n#### sprint_show\n```json\n{ \"id\": \"sprint-uuid\" }\n```\n\n#### sprint_update\n```json\n{\n  \"id\": \"sprint-uuid\",\n  \"name\": \"New name\",\n  \"status\": \"active\"\n}\n```\n\n#### sprint_delete\n```json\n{ \"id\": \"sprint-uuid\" }\n```\n\n#### sprint_activate\n```json\n{ \"id\": \"sprint-uuid\" }\n```\n\n</details>\n\n<details>\n<summary><strong>Projects</strong></summary>\n\n#### project_create\n```json\n{\n  \"name\": \"Project name\",\n  \"description\": \"Optional\",\n  \"path\": \"/optional/directory/path\"\n}\n```\n\n#### project_list\nList all projects.\n\n#### project_read\n```json\n{ \"id\": \"project-uuid\" }\n```\n\n#### project_update\n```json\n{\n  \"id\": \"project-uuid\",\n  \"name\": \"New name\"\n}\n```\n\n#### project_delete\n```json\n{ \"id\": \"project-uuid\" }\n```\n\n#### project_select\n```json\n{ \"id\": \"project-uuid\" }\n```\n\n#### project_current\n```json\n{ \"cwd\": \"/optional/path/for/autodetect\" }\n```\n\n</details>\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nGPLv3 - see [LICENSE](LICENSE) for details.\n",
  "bytes": 14849,
  "sha": "0d56f15942e626b0ec4fdf8c05fcada9e9ec78d7ca8a60c113a7ef9d3cdf6e28",
  "repo_slug": "yuvalsuede/claudia",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yuvalsuede_claudia_26fea7c3/readme"
}