Popeye CLI

A fully autonomous TypeScript CLI tool that transforms your ideas into complete, tested, deployable code projects using AI-powered code generation and review.

Overview

Popeye orchestrates two AI systems to ensure high-quality code generation:

• Claude (via Claude Agent SDK): Primary code execution engine that generates, implements, and tests code
• OpenAI: Review and validation partner that ensures plans meet quality standards through consensus

The workflow ensures 95%+ consensus between both AI systems before code execution begins, resulting in well-planned, thoroughly vetted implementations.

Features

• Dual-AI Consensus System: Plans are iteratively refined until both Claude and OpenAI agree on the approach
• Multi-Language Support: Generate projects in Python or TypeScript
• Secure Authentication: Browser-based OAuth for Claude, secure API key storage for OpenAI
• Interactive Mode: REPL-style interface with slash commands for ongoing work
• One-Shot Creation: popeye create command for quick project generation
• Progress Tracking: Visual feedback with spinners and progress bars
• Automatic Testing: Generated code includes tests that are run and verified

Installation

npm install -g popeye-cli

Or use directly with npx:

npx popeye-cli create "my project idea"

Quick Start

1. Authenticate

First, set up authentication with both AI services:

# Authenticate with Claude (browser-based OAuth)
popeye auth claude

# Authenticate with OpenAI (API key)
popeye auth openai

2. Create a Project

Generate a complete project from an idea:

# Create a Python project
popeye create "A REST API for managing todo items with SQLite storage" --language python

# Create a TypeScript project
popeye create "A React component library for data visualization" --language typescript

3. Interactive Mode

For ongoing work and experimentation:

popeye

In interactive mode, use slash commands:

/help              Show available commands
/create <idea>     Start a new project
/status            Check current project status
/auth              Manage authentication
/config            View/edit configuration
/exit              Exit interactive mode

Commands

popeye create <idea>

Create a new project from an idea.

Options:

• -n, --name <name>: Project name (default: derived from idea)
• -l, --language <lang>: Output language: python or typescript (default: python)
• -d, --directory <dir>: Output directory (default: current directory)
• -m, --model <model>: OpenAI model for consensus (default: gpt-4o)

Example:

popeye create "A CLI tool for converting markdown to PDF" --name md2pdf --language python

popeye auth <service>

Authenticate with Claude or OpenAI.

Services:

• claude: Opens browser for OAuth authentication
• openai: Prompts for API key entry via local web interface

Options:

• --check: Verify stored credentials without re-authenticating
• --logout: Remove stored credentials

popeye status

Check the status of the current project.

Options:

• -p, --project <dir>: Project directory to check

popeye resume

Resume an interrupted project from where it left off.

Options:

• -p, --project <dir>: Project directory to resume

popeye config

View or modify configuration.

Subcommands:

• config show: Display current configuration
• config set <key> <value>: Set a configuration value
• config reset: Reset to default configuration

Workflow

Plan Mode

1. Idea Expansion: Your brief idea is expanded into a detailed specification by OpenAI
2. Plan Creation: Claude creates a structured development plan with milestones and tasks
3. Consensus Loop:
   • OpenAI reviews the plan and provides feedback
   • Claude revises based on concerns
   • Repeats until 95%+ consensus is reached
4. Plan Documentation: The approved plan is saved to PLAN.md

Execution Mode

1. Task Execution: Claude implements each task sequentially
2. Test Creation: Tests are generated alongside implementation
3. Test Verification: Tests are run after each task
4. Error Recovery: Failed tests trigger automatic fix attempts (up to 3 retries)
5. Completion: Project marked complete when all tasks pass

Configuration

Popeye looks for configuration in the following order:

1. Environment variables (highest priority)
2. Project-level popeye.config.yaml or .popeyerc.yaml
3. Global ~/.popeye/config.yaml
4. Built-in defaults (lowest priority)

Configuration File

# popeye.config.yaml
consensus:
  threshold: 95
  max_disagreements: 5
  escalation_action: pause

apis:
  openai:
    model: gpt-4o
    temperature: 0.3
    max_tokens: 4096

project:
  default_language: python

output:
  verbose: false
  timestamps: true
  show_consensus_dialog: true

Environment Variables

POPEYE_OPENAI_KEY=sk-...           # OpenAI API key
POPEYE_DEFAULT_LANGUAGE=python     # Default output language
POPEYE_OPENAI_MODEL=gpt-4o         # OpenAI model
POPEYE_CONSENSUS_THRESHOLD=95      # Consensus threshold (0-100)
POPEYE_MAX_DISAGREEMENTS=5         # Max iterations before escalation
POPEYE_LOG_LEVEL=debug             # Enable verbose logging

Generated Project Structure

Python Projects

my-project/
├── src/
│   ├── __init__.py
│   └── main.py
├── tests/
│   ├── __init__.py
│   └── conftest.py
├── pyproject.toml
├── requirements.txt
├── README.md
├── .gitignore
├── .env.example
├── Dockerfile
└── .popeye/
    └── state.json

TypeScript Projects

my-project/
├── src/
│   └── index.ts
├── tests/
│   └── index.test.ts
├── package.json
├── tsconfig.json
├── README.md
├── .gitignore
├── .env.example
├── Dockerfile
└── .popeye/
    └── state.json

State Management

Project state is persisted in .popeye/state.json, allowing you to:

• Resume interrupted projects
• Track progress across sessions
• Review consensus history
• Debug issues

Requirements

• Node.js 18.0 or higher
• npm or yarn
• Claude CLI access (for code generation)
• OpenAI API key (for consensus review)

Development

# Clone the repository
git clone https://github.com/your-org/popeye-cli.git
cd popeye-cli

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Run in development mode
npm run dev

Architecture

src/
├── index.ts              # Entry point
├── cli/                  # CLI interface
│   ├── index.ts          # Command setup
│   ├── output.ts         # Output formatting
│   ├── interactive.ts    # REPL mode
│   └── commands/         # Individual commands
├── adapters/             # AI service adapters
│   ├── claude.ts         # Claude Agent SDK
│   └── openai.ts         # OpenAI API
├── auth/                 # Authentication
│   ├── keychain.ts       # Credential storage
│   └── server.ts         # OAuth callback server
├── config/               # Configuration
│   ├── schema.ts         # Zod schemas
│   ├── defaults.ts       # Default values
│   └── index.ts          # Config loading
├── generators/           # Project generators
│   ├── python.ts         # Python scaffolding
│   ├── typescript.ts     # TypeScript scaffolding
│   └── templates/        # File templates
├── state/                # State management
│   ├── persistence.ts    # File operations
│   └── index.ts          # State API
├── workflow/             # Workflow engine
│   ├── consensus.ts      # Consensus loop
│   ├── plan-mode.ts      # Planning phase
│   ├── execution-mode.ts # Execution phase
│   └── test-runner.ts    # Test execution
└── types/                # TypeScript types
    ├── project.ts        # Project types
    ├── workflow.ts       # Workflow types
    └── consensus.ts      # Consensus types

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.