io.github.yuvalsuede/claudia

Install

Config snippet generator goes here (5 client tabs)

README

# Claudia

[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=flat&logo=bun&logoColor=white)](https://bun.sh)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)

**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.

![Claudia Dashboard Demo](assets/claudia-demo.gif)

## 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

```bash
# 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:

```bash
# 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
![Claudia Tasks View](assets/claudia-tasks.png)

### Sprint Management
![Claudia Sprints View](assets/claudia-sprints.png)

## Features

| Feature | Description |
|---------|-------------|
| **Hierarchical Tasks** | Parent-child relationships with tree visualization |
| **State Machine** | Validated transitions: pending → in_progress → verification → completed |
| **Dependencies** | Block tasks until prerequisites complete, with cycle detection |
| **Sprints** | Group tasks into time-boxed work periods |
| **Multi-Project** | Isolated task namespaces with auto-detection from working directory |
| **Agent Memory** | 64KB JSON context storage per task |
| **Acceptance Criteria** | Define and verify requirements before task completion |
| **Multi-Agent Coordination** | Atomic task claiming, optimistic locking, conflict detection |
| **Web Dashboard** | Visual kanban board with project/sprint filtering |
| **MCP Server** | Drop-in integration with Claude Code and other MCP clients |

## Installation

### Prerequisites

- [Bun](https://bun.sh) runtime (v1.0+)

### From Source

```bash
git clone https://github.com/yuvalsuede/claudia.git
cd claudia
bun install
```

### Build Standalone Binary

```bash
bun run build
# Creates ./claudia binary

# Optional: install globally
cp claudia ~/.bun/bin/
```

## Usage

### CLI Commands

#### Task Management

```bash
# 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 <task-id>

# Update a task
claudia task update <task-id> --title "New title" --priority p0

# Transition status
claudia task transition <task-id> --to in_progress

# Delete a task
claudia task delete <task-id> --force
```

#### Task Hierarchy

```bash
# Create a subtask
claudia task create --title "Subtask" --parent <parent-id>

# View task tree
claudia task tree              # Full tree
claudia task tree <task-id>    # Subtree from task
```

#### Task Context (Agent Memory)

```bash
# Set context (overwrites)
claudia task context-set <task-id> '{"key": "value"}'

# Merge context (deep merge)
claudia task context-merge <task-id> '{"additional": "data"}'

# Get context
claudia task context-get <task-id>
```

#### Dependencies

```bash
# Add dependency (task depends on blocker)
claudia task depends <task-id> --on <blocker-id>

# Remove dependency
claudia task undepends <task-id> --on <blocker-id>

# Show dependencies
claudia task deps <task-id>

# List blocked tasks
claudia task blocked

# List ready tasks (all deps satisfied)
claudia task ready
```

#### Sprints

```bash
# 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 <sprint-id>

# Activate a sprint
claudia sprint activate <sprint-id>
```

#### Projects

```bash
# Create a project
claudia project create --name "My Project" --path /path/to/project

# List projects
claudia project list

#