Paean CLI

Claude Code-like AI agent with local autonomous workers, MCP integration, and task management

Paean CLI is a next-generation AI command-line interface designed for autonomous development. It combines interactive chat with powerful background workers and intelligent task routing.

✨ Key Features

• 🤖 Interactive Agent Mode: Chat with AI that understands your project context
• 👷 Autonomous Worker: Background service for continuous task execution (24/7 operation)
• 🧠 Planning & Analysis: Pre-flight project analysis and risk assessment
• 🔗 Local MCP Integration: Connect any Model Context Protocol server
• 🚦 Intelligent Routing: Auto-routes tasks to the best executor (Internal, Claude, Gemini, Cursor)
• 📊 Observability: Full execution tracing and token cost tracking

Installation

# Install globally with bun (recommended)
bun add -g paean

# Or use npm
npm install -g paean

# Or run directly
npx paean

Quick Start

1. Authenticate

paean login

2. Interactive Agent (Default)

The standard mode for day-to-day assistance.

# Start interactive chat
paean

# With planning mode (analyzes project before starting)
paean --plan

3. Autonomous Worker

Offload long-running or complex tasks to the background worker.

# Execute a task using natural language (auto-detects strategy)
paean worker prompt "Refactor the authentication module to use JWT"

# Start the worker loop to process background tasks
paean worker start

4. Conversation History

Manage and resume previous conversations.

# List recent conversations
paean ls

# List more conversations
paean ls -n 50

# Resume the latest conversation
paean resume

# Resume a specific conversation
paean resume 8f3a9b2c
# Or use the original flag
paean --resume=8f3a9b2c

🚀 Intelligent Worker System

The new Paean Worker allows for autonomous task execution with intelligent routing.

Quick Prompts (paean prompt / paean worker prompt)

Execute tasks without entering a chat session. The supervisor agent analyzes your request and decides the best execution strategy:

• Direct: Simple tasks executed immediately
• Chain: Sequential dependent steps for complex flows
• Batch: Parallel independent tasks for bulk operations

# Simple usage
paean prompt "Analyze the current project structure"

# Force specific executor
paean prompt "Fix the login bug" --executor cursor

# Create a planned chain of tasks
paean prompt "Refactor utils, then update tests, then run build" --chain

Continuous Worker Mode

Start a persistent worker that polls for and executes tasks 24/7.

paean worker start

Options:

• --interval <ms>: Polling interval (default: 30000ms)
• --max-retries <n>: Max retry attempts per task
• --no-verification: Disable the post-execution verification step

Available Executors

The supervisor routes tasks to specialized executors:

• Internal: Built-in Paean agent (default)
• Claude: Uses claude CLI for complex logic
• Cursor: Uses Cursor Agent for context-aware edits
• Gemini: Specialized for large context analysis
• Codex: Optimized for code generation

5. CLI Gateway (Cross-Device Relay)

Use your local CLI as a gateway for remote web/mobile clients. This allows you to send messages from your phone or a web browser that are processed on your local PC with full access to local MCP tools, filesystem, and shell.

# Start the gateway relay
paean gateway start

# Start with debug logging
paean gateway start --debug

# Check if a gateway is running
paean gateway status

# Stop the gateway
paean gateway stop

Once the gateway is running, web and Android clients will detect it automatically and offer a "CLI" mode toggle. Messages sent through the gateway are processed locally and streamed back in real time.

See zero-api/docs/CLI_GATEWAY.md for full architecture details.

🔍 Observability & Trace

Debug and analyze your agent's performance with the built-in trace system.

# View latest execution trace
paean trace --latest

# List all traces
paean trace

# Generate a usage report (success rates, token usage)
paean trace --report

🛠️ Utility Commands

Context Generation

Generate a comprehensive context file for your AI agents (useful for manual prompt engineering).

# Generate Markdown context
paean context -o .agent/context.md

# Generate JSON for tools
paean context --json

Task Validation

Verify if pending tasks have been completed by recent changes.

# Check status
paean validate

# Check and auto-complete valid tasks
paean validate --auto-complete

Configuration

Config stored in ~/.paean/:

• config.json - Auth and preferences
• mcp_config.json - MCP server configuration
• traces/ - Execution logs and debug data

MCP Configuration

Add servers to ~/.paean/mcp_config.json:

{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"]
    }
  }
}

Architecture

┌───────────────┐      ┌───────────────┐
│  Interactive  │      │  Autonomous   │
│   Agent UI    │      │    Worker     │
└───────┬───────┘      └───────┬───────┘
        │                      │
        ▼                      ▼
┌──────────────────────────────────────┐
│           Supervisor Agent           │
│  (Grooming, Routing, Verification)   │
└──────────────────┬───────────────────┘
                   │
         ┌─────────┴──────────┐
         ▼                    ▼
   ┌───────────┐        ┌───────────┐
   │ Internal  │        │ External  │
   │ Executor  │        │ Executor  │
   └─────┬─────┘        └─────┬─────┘
         │                    │
         ▼                    ▼
   ┌───────────┐        ┌───────────┐
   │ Local MCP │        │ 3rd Party │
   │  Servers  │        │ CLI Tools │
   └───────────┘        └───────────┘

Requirements

• Node.js 18+ or Bun
• Paean AI account

Links

• Website: https://paean.ai
• Support: [email protected]