Claudia

Claudia

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.

Why Claudia?

AI agents need a way to:

• Track progress across complex, multi-step tasks
• Coordinate when multiple agents work on the same project
• Remember context between sessions (64KB JSON storage per task)
• Verify work against acceptance criteria before completion
• Organize work into sprints and project hierarchies

Claudia provides all of this through both a CLI and MCP server interface.

Quick Start

# Install Bun if you haven't already

curl -fsSL https://bun.sh/install | bash

Clone and build

git clone https://github.com/yuvalsuede/claudia.git cd claudia bun install bun run build

Initialize and start using

./claudia db init ./claudia task create --title "My first task" ./claudia task list

Try the Demo

See Claudia in action with sample data:

# Seed demo project with sample tasks and sprints

bun run seed:demo

Open the web dashboard

./claudia @@ --port 3333

Then open http://localhost:3333 in your browser to explore the kanban board and sprint views.

Screenshots

Task Board

Sprint Management

Features

Installation

Prerequisites

• Bun runtime (v1.0+)

From Source

git clone https://github.com/yuvalsuede/claudia.git

cd claudia bun install

Build Standalone Binary

bun run build

Creates ./claudia binary

Optional: install globally

cp claudia ~/.bun/bin/

Usage

CLI Commands

Task Management

# Create a task

claudia task create --title "Implement feature X" --priority p1

Create with acceptance criteria

claudia task create --title "Add login" --acceptance-criteria "Has email field" --acceptance-criteria "Has password field"

List tasks

claudia task list claudia task list --status in_progress --priority p0,p1

Show task details

claudia task show

Update a task

claudia task update --title "New title" --priority p0

Transition status

claudia task transition --to in_progress

Delete a task

claudia task delete --force

Task Hierarchy

# Create a subtask

claudia task create --title "Subtask" --parent

View task tree

claudia task tree # Full tree claudia task tree # Subtree from task

Task Context (Agent Memory)

# Set context (overwrites)

claudia task context-set '{"key": "value"}'

Merge context (deep merge)

claudia task context-merge '{"additional": "data"}'

Get context

claudia task context-get

Dependencies

# Add dependency (task depends on blocker)

claudia task depends --on

Remove dependency

claudia task undepends --on

Show dependencies

claudia task deps

List blocked tasks

claudia task blocked

List ready tasks (all deps satisfied)

claudia task ready

Sprints

# Create a sprint

claudia sprint create --name "Sprint 1" --start 2024-01-15 --end 2024-01-29

List sprints

claudia sprint list

Show sprint with tasks

claudia sprint show

Activate a sprint

claudia sprint activate

Projects

# Create a project

claudia project create --name "My Project" --path /path/to/project

List projects

claudia project list

Select active project

claudia project select

Show current project

claudia project current

Web Dashboard

# Open dashboard in browser

claudia @@

Custom port

claudia @@ --port 8080

The dashboard provides:

• Tasks View: Kanban board with drag-and-drop columns
• Sprints View: Sprint cards with progress indicators
• Project Filter: Scope views to specific projects
• Clear Completed: Archive finished tasks

MCP Server Integration

Start the MCP server for use with Claude Code:

claudia mcp

Claude Code Configuration

Add to .mcp.json in your project root:

{

"mcpServers": { "claudia": { "command": "/path/to/claudia", "args": ["mcp"] } } }

Or for development (without building):

{

"mcpServers": { "claudia": { "command": "bun", "args": ["run", "/path/to/claudia/src/mcp/server.ts"], "cwd": "/path/to/claudia" } } }

After adding the config, restart Claude Code to connect.

Available MCP Tools

Compound Operations (Recommended for agents)

Task Management

Coordination

Verification

See the full MCP tools reference below for complete documentation.

Task Workflow

┌─────────┐     ┌─────────────┐     ┌──────────────┐     ┌───────────┐

│ pending │────▶│ in_progress │────▶│ verification │────▶│ completed │ └─────────┘ └─────────────┘ └──────────────┘ └───────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ │ blocked │ │ archived │ (terminal) └─────────┘ └──────────┘

Valid transitions:

• pending → in_progress, blocked, archived
• in_progress → pending, verification, completed, blocked, archived
• verification → in_progress, completed, blocked, archived
• blocked → pending, in_progress, archived
• completed → in_progress, archived
• archived → (terminal state)

Tasks can skip verification if no acceptance criteria are defined.

Multi-Agent Coordination

Claudia supports multiple AI agents working concurrently on the same project.

Task Claiming

// Claim before working

const result = await task_claim({ task_id: "uuid", agent_id: "agent-1" }); if (result.success) { // Task is yours - proceed } else { // Already claimed by another agent }

// Release when done or on failure await task_release({ task_id: "uuid", agent_id: "agent-1" });

Optimistic Locking

// Read task first

const task = await task_read({ id: "uuid" });

// Update with version check await task_update({ id: task.id, title: "Updated", version: task.version // Fails if modified by another agent });

Recommended Pattern

1. task_ready - List tasks with satisfied dependencies
2. task_claim - Atomically reserve a task
3. task_transition - Move to in_progress
4. task_context_merge - Save progress
5. task_transition - Move to completed
6. On failure: task_release - Let another agent retry

Configuration

Development

# Development mode

bun run dev

Run tests

bun test

Type checking

bun run typecheck

Exit Codes

MCP Tools Reference

Compound Operations

task_start

Create and start a task in one operation. Auto-claims for the current agent.

{

"title": "Task title", "description": "Optional description", "priority": "p0|p1|p2|p3", "parent_id": "optional-parent-uuid", "acceptance_criteria": ["criterion 1", "criterion 2"] }

task_finish

Complete a task with optional summary.

{

"id": "task-uuid", "summary": "Optional completion summary" }

task_workspace

Get current agent's workspace context including claimed tasks.

{

"include_completed": false }

task_handoff

Transfer task to another agent.

{

"task_id": "task-uuid", "to_agent_id": "target-agent", "notes": "Optional handoff notes" }

task_abandon

Release task back to pending with reason.

{

"task_id": "task-uuid", "reason": "Why abandoning" }

Task CRUD

task_create

{

"title": "Required title", "description": "Optional", "status": "pending", "priority": "p0|p1|p2|p3", "parent_id": "uuid", "sprint_id": "uuid", "tags": ["tag1", "tag2"], "assignee": "name", "acceptance_criteria": ["criterion"] }

task_read

{ "id": "task-uuid" }

task_update

{

"id": "task-uuid", "title": "New title", "version": 1 }

task_delete

{ "id": "task-uuid" }

task_list

{

"status": ["pending", "in_progress"], "priority": ["p0", "p1"], "parent_id": "uuid", "sprint_id": "uuid", "assignee": "name", "limit": 100, "offset": 0 }

task_transition

{

"id": "task-uuid", "to": "in_progress" }

task_tree

{

"id": "optional-root-uuid", "depth": 5 }

Bulk Operations

task_create_many

{

"tasks": [ { "title": "Task 1" }, { "title": "Task 2" } ], "parent_id": "optional-common-parent", "sprint_id": "optional-common-sprint" }

task_update_many

{

"ids": ["uuid1", "uuid2"], "updates": { "priority": "p1",