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

$3

`bash
paean login
`

$3

The standard mode for day-to-day assistance.

`bash


Start interactive chat

paean

With planning mode (analyzes project before starting)

paean --plan
`

$3

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
`

$3

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.

$3

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
`

$3

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

`bash
paean worker start
`

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

$3

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

🔍 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

$3

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
`

$3

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

$3

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