# 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

```bash
# 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

```bash
paean login
```

### 2. Interactive Agent (Default)

The standard mode for day-to-day assistance.

```bash
# 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.

```bash
# 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.

```bash
# 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

```bash
# 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.

```bash
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.

```bash
# 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](../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.

```bash
# 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).

```bash
# 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.

```bash
# 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`:

```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**: support@paean.ai