Platypus is an open-source, provider-agnostic coding agent CLI. Spawn AI agents, orchestrate multi-agent workflows, and automate your development process — all from your terminal. Think Claude Code or Cursor, but fully open and under your control.

Installation

npm install -g platypus-cli

Also works with pnpm, yarn, or bun — any npm-compatible package manager.

Requires Node.js 20+.

Quick Start

# 1. Add an API key
platypus keys add openai       # or: anthropic, google

# 2. Start chatting
platypus

That's it. Platypus opens an interactive REPL where you can talk to your chosen LLM, run tools, and apply changes to your codebase.

# Single-shot task execution
platypus run "Add input validation to the signup form" --wait 120

# Check system health
platypus doctor

Features

| | | | ----------------------------- | -------------------------------------------------------------------------------------------- | | Multi-Agent Orchestration | Spawn teams of specialized AI agents with role-based routing and parallel execution via TMUX | | Provider Agnostic | OpenAI, Anthropic, and Google Gemini — switch with a single flag | | Encrypted Key Storage | AES-256-GCM encryption with OS keychain integration (keytar) | | 15 Built-in Tools | Read, write, patch, search, list files, run commands, JSON ops, MCP bridge, LSP requests | | Staged Changes | Review diffs before applying — nothing hits disk until you approve | | Plan & Build Modes | Read-only "plan" mode for analysis, full-access "build" mode for changes | | Workflows | Pre-built workflows for code review, dev stories, and quick specs | | TMUX Integration | Run agents in parallel terminal sessions with split panes and layouts | | State Persistence | SQLite-backed storage for agents, tasks, and workflow state | | Redis Message Bus | Optional inter-agent communication via Redis pub/sub |

Commands

Core

| Command | Description | | ----------------------- | --------------------------------------- | | platypus | Interactive chat REPL (default) | | platypus chat | Explicit chat mode with flags | | platypus run "<task>" | Execute a single task non-interactively | | platypus doctor | Check system health and dependencies | | platypus stats | Show usage statistics | | platypus upgrade | Upgrade to the latest version |

Agent Management

platypus agent spawn-team --prefix myapp --agents frontend,backend,qa
platypus agent list
platypus agent create --name reviewer --role qa
platypus agent start <id>
platypus agent stop <id>
platypus agent destroy <id>

Key Management

platypus keys add <provider>        # openai | anthropic | google
platypus keys list
platypus keys validate
platypus keys remove <provider>

Workflows

platypus workflow code-review --branch feature/auth
platypus workflow dev-story --feature "User authentication"
platypus workflow quick-spec --prompt "REST API for user management"

Screen / TMUX

platypus screen list
platypus screen attach <session>
platypus screen split --layout tiled
platypus screen layout <name>

REPL Commands

Inside the interactive chat, these slash commands are available:

| Command | Description | | --------------------- | ---------------------------------- | | /mode <plan\|build> | Switch between plan and build mode | | /provider <name> | Switch LLM provider | | /model <name> | Switch model | | /cd <path> | Change working directory | | /diff | Show pending staged changes | | /apply [indices] | Apply staged changes to disk | | /discard [indices] | Discard staged changes | | /clear | Clear conversation history | | /exit | Exit the REPL |

Configuration

API Keys

Keys are encrypted with AES-256-GCM and stored securely in your OS keychain via keytar, with a SQLite fallback.

platypus keys add openai
platypus keys add anthropic
platypus keys add google

Profiles

Create custom profiles for different workflows:

# ~/.platypus/config/profiles/review.yaml
name: review
mode: plan
provider: anthropic
model: claude-3-5-sonnet-20241022
autoApprove: false
allowedTools:
  - read_file
  - list_files
  - search_files
  - run_command

platypus chat --profile review

Environment Variables

| Variable | Description | | ----------------------- | ---------------------------------------------------- | | PLATYPUS_BANNER | 0 to disable startup banner | | NO_COLOR | 1 to disable colors | | PLATYPUS_MASTER_KEY | Master encryption key (32 bytes hex) | | OPENAI_API_KEY | OpenAI API key (alternative to keys add) | | ANTHROPIC_API_KEY | Anthropic API key | | GOOGLE_API_KEY | Google API key | | PLATYPUS_MODEL | Default model name | | PLATYPUS_PROVIDER | Default provider (openai / anthropic / google) | | PLATYPUS_MODE | Default mode (plan / build) | | PLATYPUS_AUTO_APPROVE | 1 to auto-approve tool actions |

Architecture

┌─────────────────────────────────────────────┐
│                  CLI Layer                   │
│         oclif commands + REPL engine         │
├─────────────────────────────────────────────┤
│                Engine Layer                  │
│    Chat session · Tool orchestration · MCP   │
├──────────────┬──────────────┬───────────────┤
│   LLM Layer  │  State Layer │  Agent Layer  │
│  OpenAI      │  SQLite DB   │  Multi-agent  │
│  Anthropic   │  Redis bus   │  runtime &    │
│  Google      │  Workflows   │  TMUX manager │
├──────────────┴──────────────┴───────────────┤
│              Security Layer                  │
│    AES-256-GCM · OS Keychain · Key store    │
└─────────────────────────────────────────────┘

Development

git clone https://github.com/firfircelik/platypus-cli.git
cd platypus-cli
npm install

npm run build          # Compile TypeScript + generate oclif manifest
npm run dev            # Watch mode
npm test               # Run all tests (vitest)
npm run test:coverage  # With coverage report
npm run lint           # ESLint
npm run format         # Prettier

See CONTRIBUTING.md for guidelines on submitting changes.

Documentation

• User Guide — Comprehensive usage documentation
• API Reference — Extensibility and plugin development
• Examples — Sample workflows and configurations

License

MIT