Paula

A new approach to software development and human-AI collaboration, enabling concurrent work with multiple AI Agents in secure sandbox environments.

Features

• 🐳 Provides secure sandboxed development environments for each AI Agent using Docker
• 🐙 Collaborate with multiple AI Agents simultaneously on GitHub to complete development tasks
• 🤖 Supports Claude Code and Codex CLI

Installation

Development Environment

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test              # Run all tests (unit tests + integration tests)
pnpm test:unit         # Run unit tests only
pnpm test:integration  # Run integration tests only

Global Installation

# Method 1: Using the installation script (recommended)
./install-global.sh

# Method 2: Manual installation
pnpm build
cd packages/cli
pnpm link --global

# Verify installation
paula --help

Usage

1. Initialize Paula Configuration

paula init

Follow the prompts to provide GitHub configuration and access token, then adjust the configuration files in the .paula directory (Dockerfile and paula.yaml, etc.) according to your project needs.

2. Start Paula Manager

Paula manager supports two running modes:

Background Mode (Recommended)

# Start manager (runs in background)
paula manager start

# Check manager status
paula manager status

# View manager logs
paula manager logs
paula manager logs -f  # Follow logs in real-time

# Stop manager
paula manager stop

# Restart manager (using stop and start combination)
paula manager stop && paula manager start

Foreground Mode

# Run in the current terminal foreground (for debugging)
paula manager start --foreground

3. Create GitHub Issue

Create an issue in the corresponding GitHub project and add the paula-todo label. Paula manager will automatically assign a worker to handle the issue.

GitHub Label Workflow

Paula uses five GitHub labels to manage the issue lifecycle:

1. paula-todo: Add this label when creating an issue to indicate it's waiting for worker assignment
2. paula-doing: After Paula assigns a worker, the label is automatically changed to this status, and worker information is commented on the issue
3. paula-pending: The AI agent within the worker adds this label when human confirmation is needed (e.g., work plan needs confirmation, guidance needed for issues)
4. paula-done: After the AI agent within the worker completes the work, the label is changed to this status, waiting for human review
5. paula-continue: Human users can add this label to let the AI agent continue working (typically transitioning from paula-done or paula-pending)

Standard Workflow

Issue (paula-todo)
  → Paula assign worker
  → Issue (paula-doing) + Worker comment
  → AI agent analyzes and posts plan
  → Issue (paula-pending)
  → Human confirms plan (paula-continue)
  → AI agent works
  → Issue (paula-done) + MR created
  → Human reviews and closes issue
  → Paula cleans up worker

Continue Workflow

If a human needs the AI agent to continue improving or modifying:

Issue (paula-done/pending)
  → Human adds feedback comment
  → Human changes label to (paula-continue)
  → Paula interrupts current task (if running)
  → AI agent reads recent feedback
  → AI agent continues working
  → Issue (paula-done) + MR updated

Task Interruption Mechanism: When a user actively adds the paula-continue label, if the AI agent within the worker is executing a task, Paula will automatically interrupt the current task, then restart the task and read the latest feedback. This ensures that the AI agent can respond promptly to the user's new instructions.

Worker Recovery Mechanism

If a worker stops unexpectedly, it can be recovered by removing the completion label:

Issue (paula-done)
  → Human removes paula-done label
  → Issue (paula-doing)
  → Paula detects and resumes worker
  → Worker continues from where it left off

Paula Worker Usage

List All Workers

paula worker ps

Create and Start a Worker

paula worker up worker-1

Stop and Remove a Worker

paula worker down worker-1

View Worker Logs

# View logs (default shows last 100 lines)
paula worker logs worker-1

# Follow logs in real-time
paula worker logs -f worker-1

# View last 50 lines of logs
paula worker logs --tail 50 worker-1

# Show timestamps
paula worker logs -t worker-1

Enter Worker Shell

paula worker shell worker-1

Execute Command in Worker

paula worker exec worker-1 ls -la