Cleo

🚀 CLEO Claude Code Plugin

CLEO is a tool that uses a hybrid approach for multi - agent integration, providing task management and optional Claude Code - specific hooks.

🚀 Quick Start

CLEO offers two installation methods: a default one with only injection for multi - agent support and an advanced one with both injection and a plugin for enhanced Claude Code features.

Default Installation (Injection Only)

# Install CLEO with multi - agent support
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash

# Setup agent configurations (auto - discovers installed agents)
cleo init

# Verify injection
cleo doctor

Result: CLEO works in all supported agents via the injection system.

Advanced Installation (Injection + Plugin)

# Install CLEO with Claude Code plugin
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --with - plugin

# Setup agent configurations
cleo init

# Verify both injection and plugin
cleo doctor

Result: CLEO works in all agents + Claude Code gets the SessionStart hook.

✨ Features

Hybrid Approach for Multi - Agent Integration

CLEO uses a hybrid approach for multi - agent integration:

Most users need injection only. The plugin adds optional Claude Code - specific hooks for advanced users.

Injection System Features

• Auto - discovery: The injection system provides CLEO task management to all LLM agents via registry - based auto - discovery.
• Agent Support: Supports agents like claude - code, cursor, windsurf, gemini, copilot, etc.
• Working Mechanism:
  1. cleo init discovers installed agents automatically.
  2. Injects task management instructions to agent config files.
  3. Agents reference external docs via @~/.cleo/docs/TODO_Task_Management.md.
  4. Works with any agent that supports config file injection.
• Supported Files: CLAUDE.md, CURSOR.md, .windsurfrules, GEMINI.md, etc.

Plugin System Features

• Claude Code - specific Hooks: Adds Claude Code - specific hooks for terminal integration.
• Capabilities: Provides a SessionStart hook for automatic session binding.
• What it Provides:
  • SessionStart Hook: Auto - binds CLEO session to Claude terminal via CLEO_SESSION env var.
  • TTY Integration: Seamless session continuity across Claude Code restarts.
• What it Does Not Provide:
  • ❌ Slash commands (future enhancement)
  • ❌ Custom agents (future enhancement)
  • ❌ Portability to other agents (injection system handles this)

📦 Installation

The installation details are provided in the "Quick Start" section.

💻 Usage Examples

With Injection Only

# Start session manually
cleo session start --scope epic:T1074 --auto - focus

# Use cleo commands with CLEO_SESSION env var
export CLEO_SESSION="session_20260127_123456_abc123"
cleo list --parent T1074
cleo complete T1087

# End session
cleo session end --note "Completed plugin docs"

With Plugin

# Start session (manually or via orchestrator)
cleo session start --scope epic:T1074 --auto - focus

# Claude Code starts → plugin auto - exports CLEO_SESSION
# ✓ CLEO session bound: session_20260127_123456_abc123

# Use cleo commands (no manual export needed)
cleo list --parent T1074
cleo complete T1087

# End session
cleo session end --note "Completed plugin docs"

Key difference: The plugin eliminates the manual export CLEO_SESSION=... step.

📚 Documentation

Plugin Structure

.claude - plugin/
├── plugin.json           # Plugin manifest
├── hooks/
│   ├── hooks.json       # Hook configuration
│   └── scripts/
│       └── session - start.sh   # SessionStart hook implementation
└── README.md            # This file

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

This script auto - binds the active CLEO session to the Claude terminal.

• What it does:
  1. Checks for an active CLEO session (.cleo/.current - session).
  2. Verifies the session is active via cleo session status.
  3. Exports CLEO_SESSION env var for the terminal.
  4. Creates .cleo/.session - env for manual sourcing (if needed).
• Exit conditions (silent):
  • CLEO not installed.
  • No .cleo directory (not a CLEO project).
  • No active session.
  • Session inactive/ended.

Hybrid Benefits

Philosophy: Injection provides portability, and the plugin provides polish.

Decision Tree

Do you use Claude Code exclusively?
├─ Yes
│   └─ Do you want automatic session binding?
│       ├─ Yes → Install with --with - plugin
│       └─ No  → Install default (injection only)
└─ No (multi - agent workflow)
    └─ Install default (injection only)

Troubleshooting

Plugin Not Working

Symptom: SessionStart hook not firing Check:

1. Plugin installed: ls .claude - plugin/
2. Hooks enabled: cat .claude - plugin/plugin.json | jq '.hooks.enabled'
3. CLEO session active: cleo session status
4. Claude Code version: Plugin requires Claude Code 1.0.0+

Session Not Auto - Binding

Symptom: CLEO_SESSION not set after Claude Code start Check:

1. Active session exists: cat .cleo/.current - session
2. Session is active: cleo session status
3. Hook script executable: ls -l .claude - plugin/hooks/scripts/session - start.sh
4. Manual test: bash .claude - plugin/hooks/scripts/session - start.sh

Injection vs Plugin Conflict

Symptom: Duplicate task management instructions Resolution: No conflict. Injection and the plugin are complementary:

• Injection: Provides task management docs to the agent.
• Plugin: Provides terminal integration hooks. Both can coexist safely.

Future Enhancements

Planned plugin features (not in v0.70.1):

• Slash commands (/cleo add "Task")
• Custom agents (ct - orchestrator, ct - epic - architect)
• Agent - to - agent communication (consensus protocol)
• Git workflow integration

Current status: The plugin provides the SessionStart hook only. All other features use the standard CLI.

References

• Injection System: schemas/agent - registry.json
• Setup Guide: docs/guides/AGENT - REGISTRATION.md
• Subagent Architecture: docs/architecture/CLEO - SUBAGENT.md
• Protocol Stack: src/protocols/

🔧 Technical Details

CLEO uses injection for portability, allowing it to work with multiple LLM agents. The injection system discovers agents through a registry - based mechanism and injects task management instructions into their configuration files. The plugin, on the other hand, is designed specifically for Claude Code, providing features like automatic session binding and TTY continuity. This hybrid architecture ensures that CLEO can be used in a wide range of scenarios, from multi - agent workflows to specialized Claude Code usage.