OpenPaean

Open source AI agent CLI with fullscreen TUI and local MCP integration

Project Overview & Vision — Architecture, roadmap, and the full story behind Open Paean.

OpenPaean is a powerful command-line AI agent that provides:

• 🖥️ Fullscreen TUI: Immersive terminal experience like opencode and claude-code
• 🤖 Agent Mode: Interactive AI chat with streaming responses
• 🔗 Local MCP Integration: Connect to local MCP servers for tool calling
• 📋 Task Management: View, create, and manage tasks from the command line

Installation

# Quick install (recommended)
curl -fsSL https://paean.ai/openpaean/install.sh | bash

Or install manually with a package manager:

# Install globally with bun
bun add -g openpaean

# Or use npm
npm install -g openpaean

# Or use directly with npx
npx openpaean

Update

openpaean update

Quick Start

1. Authenticate

openpaean login

2. Start Agent Mode

# Start fullscreen TUI mode (default)
openpaean

# Disable fullscreen mode
openpaean --no-fullscreen

# Send a single message
openpaean -m "What can you help me with?"

# Select model tier
openpaean --tier lite     # Paean Lite (fastest, lowest cost)
openpaean --tier flash    # Paean Flash (default, balanced)
openpaean --tier pro      # Paean Pro (most capable)

3. Configure Local MCP Servers

Create ~/.openpaean/mcp_config.json:

{
  "mcpServers": {
    "vibe_kanban": {
      "command": "npx",
      "args": ["-y", "vibe-kanban@latest", "--mcp"]
    }
  }
}

Options

openpaean                       # Start fullscreen TUI mode
openpaean --no-fullscreen      # Disable fullscreen mode
openpaean --no-mcp             # Disable local MCP integration
openpaean -d, --debug          # Enable debug logging
openpaean -m "message"         # Send a single message
openpaean -t, --tier <tier>    # Model tier: lite, flash (default), pro
openpaean update                # Update to the latest version
openpaean update --check        # Check for updates without installing

Configuration

Config stored in ~/.openpaean/:

• config.json - Auth and preferences
• mcp_config.json - MCP server configuration

Environment Variables

# Override API endpoint (for self-hosted backends)
OPENPAEAN_API_URL=https://your-api.com

# Override Web URL (for OAuth callbacks)
OPENPAEAN_WEB_URL=https://your-web.com

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   You (CLI)     │────▶│   API Backend   │────▶│   AI Agent      │
│   (Fullscreen)  │     │                 │     │   (ADK)         │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         │                       │ SSE: mcp_tool_call    │
         ▼                       ▼                       │
┌─────────────────┐◀────────────────────────────────────┘
│  Local MCP      │
│  Servers        │ ← Executes locally, returns result
└─────────────────┘

Security

• No hardcoded secrets: All credentials stored locally in ~/.openpaean/
• Environment variable support: Override API URLs for self-hosted deployments
• MCP server trust: Only configure MCP servers from trusted sources

See SECURITY.md for vulnerability reporting.

Documentation

• Project Overview & Vision — Architecture deep-dive, design philosophy, and roadmap.
• Contributing Guide — Development setup and guidelines.
• Security Policy — Vulnerability reporting.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Requirements

• Node.js 18+ or Bun
• Paean AI account (or self-hosted backend)

License

MIT © Paean AI