Cleo

🚀 CLEO Claude代码插件

CLEO Claude代码插件是一款用于多智能体集成的工具，采用混合架构，结合注入系统和插件系统，为用户提供灵活的任务管理和终端集成功能。

🚀 快速开始

仅使用注入系统（默认）

# 安装支持多智能体的CLEO
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash

# 设置智能体配置（自动发现已安装的智能体）
cleo init

# 验证注入情况
cleo doctor

高级安装（注入系统 + 插件）

# 安装带有Claude代码插件的CLEO
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --with-plugin

# 设置智能体配置
cleo init

# 验证注入和插件情况
cleo doctor

✨ 主要特性

• 混合架构：结合注入系统和插件系统，实现多智能体集成。
• 多智能体支持：支持16种以上的智能体，包括Claude、Cursor、Windsurf、Gemini等。
• Claude代码特定钩子：插件为Claude代码提供特定的钩子，实现自动会话绑定和TTY集成。
• 任务管理：提供全面的任务管理功能，支持多会话和编排。

📦 安装指南

默认安装（仅注入系统）

# 安装支持多智能体的CLEO
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash

# 设置智能体配置（自动发现已安装的智能体）
cleo init

# 验证注入情况
cleo doctor

高级安装（注入系统 + 插件）

# 安装带有Claude代码插件的CLEO
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --with-plugin

# 设置智能体配置
cleo init

# 验证注入和插件情况
cleo doctor

💻 使用示例

仅使用注入系统

# 手动启动会话
cleo session start --scope epic:T1074 --auto-focus

# 使用带有CLEO_SESSION环境变量的cleo命令
export CLEO_SESSION="session_20260127_123456_abc123"
cleo list --parent T1074
cleo complete T1087

# 结束会话
cleo session end --note "Completed plugin docs"

使用插件

# 启动会话（手动或通过编排器）
cleo session start --scope epic:T1074 --auto-focus

# Claude代码启动 → 插件自动导出CLEO_SESSION
# ✓ CLEO会话已绑定：session_20260127_123456_abc123

# 使用cleo命令（无需手动导出）
cleo list --parent T1074
cleo complete T1087

# 结束会话
cleo session end --note "Completed plugin docs"

📚 详细文档

概述

CLEO采用混合方法进行多智能体集成：

架构

主要：注入系统

注入系统通过基于注册表的自动发现为所有大语言模型智能体提供CLEO任务管理：

• 位置：schemas/agent-registry.json
• 支持的智能体：claude-code、cursor、windsurf、gemini、copilot、roo-code、cline、continue、aider、bolt、replit、lovable、v0、devin等。
• 工作原理：
  1. cleo init自动发现已安装的智能体。
  2. 将任务管理指令注入到智能体配置文件中。
  3. 智能体通过@~/.cleo/docs/TODO_Task_Management.md引用外部文档。
  4. 适用于任何支持配置文件注入的智能体。
• 支持的文件：CLAUDE.md、CURSOR.md、.windsurfrules、GEMINI.md等。

可选：插件系统

插件为终端集成添加Claude代码特定的钩子：

• 位置：.claude-plugin/
• 功能：会话启动钩子，用于自动会话绑定。
• 限制：仅适用于Claude代码（不可移植到其他智能体）。
• 插件提供的功能：
  • 会话启动钩子：通过CLEO_SESSION环境变量将CLEO会话自动绑定到Claude终端。
  • TTY集成：在Claude代码重启时实现无缝会话连续性。
• 插件不提供的功能：
  • ❌ 斜杠命令（未来增强功能）
  • ❌ 自定义智能体（未来增强功能）
  • ❌ 可移植到其他智能体（注入系统处理此功能）

何时使用插件

仅使用注入系统（默认） ✓

• 推荐人群：
  • 多智能体工作流（Cursor、Windsurf、Gemini等）
  • 标准Claude代码使用场景
  • 不需要自动会话绑定的用户
• 你将获得：
  • 完整的CLEO任务管理（cleo命令行界面）
  • 多会话支持
  • 编排和子智能体
  • 适用于所有支持的智能体

添加插件（高级） ⚡

• 推荐人群：
  • 重度Claude代码用户
  • 多会话高级用户
  • 需要自动会话绑定的用户
• 你将获得：
  • 注入系统的所有功能
  • 额外：会话启动钩子，用于自动绑定CLEO_SESSION
  • 额外：支持TTY的会话连续性

插件结构

.claude-plugin/
├── plugin.json           # 插件清单
├── hooks/
│   ├── hooks.json       # 钩子配置
│   └── scripts/
│       └── session-start.sh   # 会话启动钩子实现
└── README.md            # 此文件

plugin.json

插件清单定义功能：

{
  "name": "cleo",
  "version": "0.70.1",
  "capabilities": {
    "task_management": true,
    "multi_session": true,
    "orchestration": true
  },
  "hooks": {
    "enabled": true,
    "directory": "hooks",
    "manifest": "hooks/hooks.json"
  }
}

hooks.json

会话启动事件的钩子配置：

{
  "SessionStart": [{
    "matcher": "*",
    "hooks": [{
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh",
      "timeout": 10
    }]
  }]
}

session-start.sh

将活动的CLEO会话自动绑定到Claude终端：

• 功能：
  1. 检查活动的CLEO会话（.cleo/.current-session）。
  2. 通过cleo session status验证会话是否活动。
  3. 为终端导出CLEO_SESSION环境变量。
  4. 创建.cleo/.session-env，以便手动导入（如果需要）。
• 退出条件（静默）：
  • CLEO未安装
  • 没有.cleo目录（不是CLEO项目）
  • 没有活动会话
  • 会话不活动/已结束

混合架构的优势

决策树

你是否仅使用Claude代码？
├─ 是
│   └─ 你是否需要自动会话绑定？
│       ├─ 是 → 使用 --with-plugin 安装
│       └─ 否  → 默认安装（仅注入系统）
└─ 否（多智能体工作流）
    └─ 默认安装（仅注入系统）

故障排除

插件无法工作

• 症状：会话启动钩子未触发
• 检查：
  1. 插件是否安装：ls .claude-plugin/
  2. 钩子是否启用：cat .claude-plugin/plugin.json | jq '.hooks.enabled'
  3. CLEO会话是否活动：cleo session status
  4. Claude代码版本：插件需要Claude代码1.0.0及以上版本

会话未自动绑定

• 症状：Claude代码启动后CLEO_SESSION未设置
• 检查：
  1. 是否存在活动会话：cat .cleo/.current-session
  2. 会话是否活动：cleo session status
  3. 钩子脚本是否可执行：ls -l .claude-plugin/hooks/scripts/session-start.sh
  4. 手动测试：bash .claude-plugin/hooks/scripts/session-start.sh

注入系统与插件冲突

• 症状：出现重复的任务管理指令
• 解决方案：无冲突。注入系统和插件是互补的：
  • 注入系统：为智能体提供任务管理文档
  • 插件：提供终端集成钩子

两者可以安全共存。

未来增强功能

• 计划中的插件功能（v0.70.1中未包含）：
  • 斜杠命令（/cleo add "Task"）
  • 自定义智能体（ct-orchestrator、ct-epic-architect）
  • 智能体间通信（共识协议）
  • Git工作流集成
• 当前状态：插件仅提供会话启动钩子。所有其他功能使用标准命令行界面。

参考资料

• 注入系统：schemas/agent-registry.json
• 设置指南：docs/guides/AGENT-REGISTRATION.md
• 子智能体架构：docs/architecture/CLEO-SUBAGENT.md
• 协议栈：src/protocols/

关键洞察：CLEO使用注入系统实现可移植性，使用插件为Claude代码提供优化。大多数用户仅需要注入系统。