claudia

Claudia

专为 AI Agent 打造的任务管理系统。

官方网站：https://claudiacli.com/

Claudia 提供结构化任务跟踪，并内置 Model Context Protocol（MCP）服务，让 Claude 等 AI 助手能够通过分层任务、依赖关系、冲刺和验收标准验证来管理自己的工作。

为什么选择 Claudia？

AI Agent 需要以下能力：

• 跟踪进度，处理复杂的多步骤任务
• 协同工作，支持多个 Agent 在同一项目上协作
• 记住上下文，跨会话保留信息（每个任务可存储 64KB JSON）
• 验证工作，在完成前根据验收标准进行检查
• 组织工作，按冲刺和项目层级进行管理

Claudia 通过 CLI 和 MCP 服务接口提供上述所有功能。

快速开始

# 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

试用演示

通过示例数据体验 Claudia：

# Seed demo project with sample tasks and sprints
bun run seed:demo

# Open the web dashboard
./claudia @@ --port 3333

然后在浏览器中打开 http://localhost:3333，探索看板和冲刺视图。

截图

任务看板

冲刺管理

功能

安装

前置条件

• Bun 运行时（v1.0+）

从源代码安装

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

构建独立二进制文件

bun run build
# Creates ./claudia binary

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

使用方法

CLI 命令

任务管理

# 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

任务层级

# 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

任务上下文（Agent 记忆）

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

依赖关系

# 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

冲刺

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

项目

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

# List projects
claudia project list

# Select active project
claudia project select <project-id>

# Show current project
claudia project current

Web 仪表板

# Open dashboard in browser
claudia @@

# Custom port
claudia @@ --port 8080

仪表板提供：

• 任务视图：支持拖放列的看板
• 冲刺视图：显示进度指示器的冲刺卡片
• 项目筛选器：将视图限定到特定项目
• 清除已完成项：归档已完成的任务

MCP 服务集成

启动 MCP 服务，以便与 Claude Code 配合使用：

claudia mcp

Claude Code 配置

将以下内容添加到项目根目录中的 .mcp.json：

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

或者用于开发（无需构建）：

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

添加配置后，重启 Claude Code 以建立连接。

可用的 MCP 工具

复合操作（建议 Agent 使用）

任务管理

协作

验证

如需完整文档，请参阅下方的完整 MCP 工具参考。

任务工作流

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

有效的状态转换：

• 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 →（终止状态）

如果未定义验收标准，任务可以跳过 verification。

多 Agent 协作

Claudia 支持多个 AI Agent 在同一项目上并行工作。

认领任务

// 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" });

乐观锁

// 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
});

建议的模式

1. task_ready - 列出依赖项均已满足的任务
2. task_claim - 以原子方式预留任务
3. task_transition - 将任务移至 in_progress
4. task_context_merge - 保存进度
5. task_transition - 将任务移至 completed
6. 失败时：task_release - 让另一个 Agent 重试

配置

开发

# Development mode
bun run dev

# Run tests
bun test

# Type checking
bun run typecheck

退出代码

MCP 工具参考

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

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

{
  "include_completed": false
}

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

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

{
  "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"]
}

{ "id": "task-uuid" }

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

{ "id": "task-uuid" }

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

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

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

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

{
  "ids": ["uuid1", "uuid2"],
  "updates": {
    "priority": "p1",
    "assignee": "agent-1"
  }
}

{
  "ids": ["uuid1", "uuid2"],
  "to": "completed",
  "skip_invalid": true
}

{
  "task_id": "blocked-task",
  "depends_on_id": "blocking-task"
}

{
  "task_id": "task-uuid",
  "depends_on_id": "dependency-uuid"
}

{ "task_id": "task-uuid" }

{
  "task_id": "task-uuid",
  "agent_id": "claiming-agent"
}

{
  "id": "task-uuid",
  "context": { "any": "json data" }
}

{
  "id": "task-uuid",
  "context": { "additional": "data" }
}

{ "id": "task-uuid" }

{
  "task_id": "task-uuid",
  "criterion_id": "criterion-uuid",
  "evidence": "Optional verification evidence"
}

{ "task_id": "task-uuid" }

{
  "name": "Sprint 1",
  "start_at": "2024-01-15",
  "end_at": "2024-01-29"
}

{ "include_archived": false }

{ "id": "sprint-uuid" }

{
  "id": "sprint-uuid",
  "name": "New name",
  "status": "active"
}

{ "id": "sprint-uuid" }

{ "id": "sprint-uuid" }

{
  "name": "Project name",
  "description": "Optional",
  "path": "/optional/directory/path"
}

{ "id": "project-uuid" }

{
  "id": "project-uuid",
  "name": "New name"
}

{ "id": "project-uuid" }

{ "id": "project-uuid" }

{ "cwd": "/optional/path/for/autodetect" }

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

许可证

GPLv3 - 详情请参阅 LICENSE。