agent-teams 0.1.0

# agent-teams

[![Crates.io](https://img.shields.io/crates/v/agent-teams.svg)](https://crates.io/crates/agent-teams)
[![Docs.rs](https://docs.rs/agent-teams/badge.svg)](https://docs.rs/agent-teams)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A generic Rust **Agent Teams** framework replicating the [Claude Code Agent Teams](https://docs.anthropic.com/en/docs/claude-code) architecture (lead, teammates, task list, mailbox), with **pluggable backends** for Claude Code, Codex, and Gemini CLI.

[English](#overview) | [中文](#概述)

---

## Overview

`agent-teams` provides the building blocks for orchestrating multi-agent workflows:

- **Team Management** — Create teams, add/remove members (leads + teammates), file-based persistence compatible with `~/.claude/teams/`
- **Task Management** — CRUD tasks with status transitions, dependency tracking (DAG), cycle detection, critical path analysis
- **Messaging** — Inbox-based inter-agent messaging with structured message types (shutdown, plan approval, idle notifications)
- **Pluggable Backends** — Claude Code (via `cc-sdk`), Codex (JSON-RPC 2.0 subprocess), Gemini CLI — all behind a unified `AgentBackend` trait
- **Smart Routing** — Route prompts to the best backend based on keywords, capabilities, or prompt complexity
- **CLI Delegation** — Agents can shell out to Codex/Gemini/custom tools via Bash for hybrid execution
- **Consensus** — Multi-agent voting: majority, weighted, unanimous, human-in-the-loop
- **Conversation Memory** — Per-agent context management with configurable budgets
- **Checkpoints** — Git notes-based audit trail attaching agent session context to commits
- **TUI Dashboard** — Terminal UI for browsing team status, checkpoints, and token costs

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                  TeamOrchestrator                    │
│                                                     │
│  ┌──────────┐  ┌──────────┐  ┌────────────────┐    │
│  │ TeamMgr  │  │ TaskMgr  │  │  InboxManager  │    │
│  │ (files)  │  │ (files)  │  │   (files)      │    │
│  └──────────┘  └──────────┘  └────────────────┘    │
│                                                     │
│  ┌──────────────────────────────────────────────┐   │
│  │            AgentBackend (trait)               │   │
│  │                                              │   │
│  │  ┌────────────┐ ┌───────┐ ┌──────────────┐  │   │
│  │  │ClaudeCode  │ │ Codex │ │  Gemini CLI  │  │   │
│  │  │(cc-sdk)    │ │(JSONRPC)│ │ (subprocess)│  │   │
│  │  └────────────┘ └───────┘ └──────────────┘  │   │
│  └──────────────────────────────────────────────┘   │
│                                                     │
│  ┌──────────┐  ┌───────────┐  ┌────────────────┐   │
│  │ DAG /    │  │ Consensus │  │ Conversation   │   │
│  │ Graph    │  │ (voting)  │  │ Memory         │   │
│  └──────────┘  └───────────┘  └────────────────┘   │
│                                                     │
│  ┌──────────────────┐  ┌───────────────────────┐   │
│  │  Checkpoint       │  │  TUI Dashboard       │   │
│  │  (Git notes)      │  │  (ratatui)           │   │
│  └──────────────────┘  └───────────────────────┘   │
└─────────────────────────────────────────────────────┘
```

## Installation

### As a library

```toml
[dependencies]
agent-teams = "0.1"
```

With optional features:

```toml
[dependencies]
agent-teams = { version = "0.1", features = ["checkpoint"] }
```

### As a CLI tool

```bash
# Core CLI (DAG analysis, team management)
cargo install agent-teams --features cli

# With checkpoints (Git notes audit trail)
cargo install agent-teams --features "cli,checkpoint"

# Full features (checkpoints + TUI dashboard)
cargo install agent-teams --features "cli,tui"
```

## Features

| Feature | Default | Description |
|---------|---------|-------------|
| `cli` | No | CLI binary with `clap` — team/task/dag/checkpoint subcommands |
| `dashboard` | No | Web dashboard with axum REST API + SSE events |
| `checkpoint` | No | Git notes-based checkpoint system (`git2`, `sha2`) |
| `tui` | No | Terminal UI dashboard (`ratatui`, `crossterm`) — implies `checkpoint` |

## Quick Start

### Library Usage

```rust
use agent_teams::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Build orchestrator with Claude Code backend
    let orch = TeamOrchestrator::builder()
        .backend(BackendType::ClaudeCode, ClaudeCodeBackend::new())
        .build()?;

    // Create a team
    orch.create_team("my-project", Some("Code review team")).await?;

    // Create tasks with dependencies
    let t1 = orch.create_task("my-project", CreateTaskRequest {
        subject: "Design API schema".into(),
        description: Some("Define REST endpoints".into()),
        ..Default::default()
    }).await?;

    let t2 = orch.create_task("my-project", CreateTaskRequest {
        subject: "Implement endpoints".into(),
        ..Default::default()
    }).await?;

    // Set up dependency: t2 blocked by t1
    orch.update_task("my-project", &t2.id, TaskUpdate {
        add_blocked_by: Some(vec![t1.id.clone()]),
        ..Default::default()
    }).await?;

    // Spawn an agent
    let config = SpawnConfig::builder("coder", "You are a Rust developer.")
        .model("sonnet")
        .build();
    orch.spawn_teammate("my-project", config).await?;

    Ok(())
}
```

### CLI Delegation (Hybrid Execution)

```rust
use agent_teams::prelude::*;

// Claude agent that delegates code generation to Codex
let config = SpawnConfig::builder("coder", "You are a developer.")
    .delegate(CliDelegation::codex().with_description("Use for code generation."))
    .delegate(CliDelegation::gemini("gemini-2.5-pro").with_description("Use for analysis."))
    .build();
```

### Smart Routing

```rust
use agent_teams::prelude::*;

// Route prompts to the best backend based on complexity
let router = SmartRouter::default();
let backend = router.route("Fix the typo in README", &available_backends);
// → Routes simple prompts to faster/cheaper backends
```

### CLI Usage

```bash
# Team management
agent-teams team create my-project --description "Sprint 42"
agent-teams team list

# Task management
agent-teams task create my-project --subject "Fix auth bug"
agent-teams task list my-project

# DAG analysis
agent-teams dag show my-project          # Terminal visualization
agent-teams dag validate my-project      # Cycle detection
agent-teams dag critical-path my-project # Longest dependency chain
agent-teams dag next my-project          # Show unblocked tasks

# Checkpoints (requires --features checkpoint)
agent-teams checkpoint create --agent coder --team my-project
agent-teams checkpoint list --agent coder -n 10
agent-teams checkpoint show HEAD
agent-teams checkpoint diff HEAD~3 HEAD
agent-teams checkpoint cost              # Token cost summary
agent-teams checkpoint hook install      # Auto-checkpoint on git commit

# TUI dashboard (requires --features tui)
agent-teams tui --team my-project
```

### Claude Code Plugin

This crate includes a Claude Code plugin (`plugin/`) with slash commands:

```
/team-delegate <task description>   — Free-form multi-agent delegation
/team-review <files>                — 5+1 agent code review pipeline
/team-implement <task>              — 4-phase implementation pipeline
/teams-dag <team>                   — DAG visualization and analysis
/checkpoint                         — Git checkpoint management
/tui                                — Launch TUI dashboard
```

Install: `claude --plugin-dir /path/to/agent-teams/plugin`

## File Layout

The framework uses the same file layout as Claude Code:

```
~/.claude/
  teams/{team-name}/
    config.json          # TeamConfig
    inboxes/{agent}.jsonl # Per-agent messages
  tasks/{team-name}/
    {id}.json            # TaskFile
```

Git checkpoints are stored as notes under `refs/notes/agent-checkpoints`.

---

## 概述

`agent-teams` 是一个通用的 Rust **智能体团队**框架，复刻了 [Claude Code Agent Teams](https://docs.anthropic.com/en/docs/claude-code) 的架构（队长、队友、任务列表、消息邮箱），支持 Claude Code、Codex 和 Gemini CLI 等**可插拔后端**。

## 核心功能

- **团队管理** — 创建团队、添加/移除成员（队长 + 队友），基于文件系统持久化，兼容 `~/.claude/teams/` 目录格式
- **任务管理** — 任务 CRUD、状态流转、依赖追踪（DAG 有向无环图）、环路检测、关键路径分析
- **消息通信** — 基于收件箱的智能体间通信，支持结构化消息类型（关闭请求、计划审批、空闲通知）
- **可插拔后端** — Claude Code（通过 `cc-sdk`）、Codex（JSON-RPC 2.0 子进程）、Gemini CLI，统一在 `AgentBackend` trait 之下
- **智能路由** — 根据关键词、能力或 prompt 复杂度自动选择最优后端
- **CLI 委派** — 智能体可通过 Bash 调用 Codex/Gemini/自定义工具，实现混合执行
- **共识机制** — 多智能体投票：多数、加权、全票、人工介入
- **对话记忆** — 每个智能体独立的上下文管理，可配置 token 预算
- **检查点** — 基于 Git notes 的审计追踪，将智能体会话上下文附加到 commit
- **TUI 仪表盘** — 终端 UI，浏览团队状态、检查点和 token 费用

## 安装

### 作为库使用

```toml
[dependencies]
agent-teams = "0.1"
```

带可选功能：

```toml
[dependencies]
agent-teams = { version = "0.1", features = ["checkpoint"] }
```

### 作为 CLI 工具安装

```bash
# 核心 CLI（DAG 分析、团队管理）
cargo install agent-teams --features cli

# 带检查点（Git notes 审计追踪）
cargo install agent-teams --features "cli,checkpoint"

# 全部功能（检查点 + TUI 仪表盘）
cargo install agent-teams --features "cli,tui"
```

## Feature Flags

| Feature | 默认 | 说明 |
|---------|------|------|
| `cli` | 否 | CLI 二进制，基于 `clap` — 团队/任务/DAG/检查点子命令 |
| `dashboard` | 否 | Web 仪表盘，axum REST API + SSE 事件流 |
| `checkpoint` | 否 | Git notes 检查点系统（`git2`、`sha2`） |
| `tui` | 否 | 终端 UI 仪表盘（`ratatui`、`crossterm`）— 隐含 `checkpoint` |

## 快速开始

### 库用法

```rust
use agent_teams::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // 构建编排器，配置 Claude Code 后端
    let orch = TeamOrchestrator::builder()
        .backend(BackendType::ClaudeCode, ClaudeCodeBackend::new())
        .build()?;

    // 创建团队
    orch.create_team("my-project", Some("代码审查团队")).await?;

    // 创建任务并设置依赖
    let t1 = orch.create_task("my-project", CreateTaskRequest {
        subject: "设计 API schema".into(),
        description: Some("定义 REST 端点和数据模型".into()),
        ..Default::default()
    }).await?;

    let t2 = orch.create_task("my-project", CreateTaskRequest {
        subject: "实现 API 端点".into(),
        ..Default::default()
    }).await?;

    // 设置依赖：t2 被 t1 阻塞
    orch.update_task("my-project", &t2.id, TaskUpdate {
        add_blocked_by: Some(vec![t1.id.clone()]),
        ..Default::default()
    }).await?;

    // 启动智能体
    let config = SpawnConfig::builder("coder", "你是一个 Rust 开发者。")
        .model("sonnet")
        .build();
    orch.spawn_teammate("my-project", config).await?;

    Ok(())
}
```

### CLI 委派（混合执行模式）

```rust
use agent_teams::prelude::*;

// Claude 智能体将代码生成委派给 Codex，分析委派给 Gemini
let config = SpawnConfig::builder("coder", "你是一个开发者。")
    .delegate(CliDelegation::codex().with_description("用于代码生成。"))
    .delegate(CliDelegation::gemini("gemini-2.5-pro").with_description("用于代码分析。"))
    .build();
```

### CLI 用法

```bash
# 团队管理
agent-teams team create my-project --description "Sprint 42"
agent-teams team list

# 任务管理
agent-teams task create my-project --subject "修复认证 bug"
agent-teams task list my-project

# DAG 分析
agent-teams dag show my-project          # 终端可视化
agent-teams dag validate my-project      # 环路检测
agent-teams dag critical-path my-project # 关键路径
agent-teams dag next my-project          # 显示未阻塞的任务

# 检查点（需要 --features checkpoint）
agent-teams checkpoint create --agent coder --team my-project
agent-teams checkpoint list --agent coder -n 10
agent-teams checkpoint cost              # Token 费用汇总
agent-teams checkpoint hook install      # 安装 Git 提交后自动检查点

# TUI 仪表盘（需要 --features tui）
agent-teams tui --team my-project
```

### Claude Code 插件

本项目包含 Claude Code 插件（`plugin/` 目录），提供斜杠命令：

```
/team-delegate <任务描述>   — 自由形式的多智能体委派
/team-review <文件>         — 5+1 智能体代码审查流水线
/team-implement <任务>      — 4 阶段实现流水线
/teams-dag <团队>           — DAG 可视化和分析
/checkpoint                 — Git 检查点管理
/tui                        — 启动 TUI 仪表盘
```

安装方式：`claude --plugin-dir /path/to/agent-teams/plugin`

## 文件布局

框架使用与 Claude Code 相同的文件布局：

```
~/.claude/
  teams/{team-name}/
    config.json          # 团队配置
    inboxes/{agent}.jsonl # 每个智能体的消息收件箱
  tasks/{team-name}/
    {id}.json            # 任务文件
```

Git 检查点存储为 `refs/notes/agent-checkpoints` 下的 notes。

---

## License

MIT