agent-teams

A generic Rust Agent Teams framework replicating the Claude Code Agent Teams architecture (lead, teammates, task list, mailbox), with pluggable backends for Claude Code, Codex, and Gemini CLI.

English | 中文

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

[dependencies]
agent-teams = "0.1"

With optional features:

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

As a CLI tool

# 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

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)

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

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

# 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 的架构（队长、队友、任务列表、消息邮箱），支持 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 费用

安装

作为库使用

[dependencies]
agent-teams = "0.1"

带可选功能：

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

作为 CLI 工具安装

# 核心 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`

快速开始

库用法

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 委派（混合执行模式）

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 用法

# 团队管理
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

agent-teams 0.1.0