GitHub - purplefish-ai/factory-factory: Workspace-based coding environment for running multiple Claude Code and Codex sessions in parallel.

8 min read Original article ↗

Factory Factory

Run multiple ACP agent sessions in parallel with isolated git worktrees.

Work on multiple features simultaneously, each in its own branch. Let ACP-connected agents progress PRs automatically.

npm CI License Website

Factory Factory Screenshot

Table of Contents

Installation

Prerequisites:

  • Node.js 20.19+ (or 22.12+, or 24+)
  • GitHub CLI (gh) - authenticated
  • Claude Code (for Claude provider) - authenticated via claude login
  • ChatGPT/Codex account (for Codex provider)
  • Linear API key (optional, only if using Linear issue intake)

Option 1: Run with npx (Recommended)

No installation needed! Run Factory Factory directly:

npx factory-factory@latest serve

Option 2: Install globally

npm install -g factory-factory
ff serve

Option 3: Install from source (for development)

git clone https://github.com/purplefish-ai/factory-factory.git
cd factory-factory
pnpm install
pnpm link --global

Web App

# Using npx (no install required)
npx factory-factory@latest serve

# Using installed CLI
ff serve

# Development mode with hot reload
ff serve --dev
# or with pnpm (for local development)
pnpm dev

The server automatically:

  • Creates the data directory (~/factory-factory/)
  • Runs database migrations
  • Finds available ports if defaults are in use
  • Opens your browser when ready

Desktop App (Electron)

# Development with hot reload
pnpm dev:electron

# Build distributable
pnpm build:electron

The Electron app stores data in the standard location for your OS:

  • macOS: ~/Library/Application Support/Factory Factory/
  • Windows: %APPDATA%/Factory Factory/
  • Linux: ~/.config/Factory Factory/

CLI Reference

# Start the server
ff serve [options]
# or
npx factory-factory@latest serve [options]

Options:
  -p, --port <port>           Frontend port (default: 3000)
  --backend-port <port>       Backend port in --dev mode (default: 3001)
  -d, --database-path <path>  SQLite database path (default: ~/factory-factory/data.db)
  --host <host>               Host to bind to (default: localhost)
  --dev                       Development mode with hot reloading
  --no-open                   Don't open browser automatically
  -v, --verbose               Enable verbose logging

In production mode (ff serve without --dev), Factory Factory serves frontend and API on a single port.

# Start a public Cloudflare tunnel (starts server + tunnel)
ff proxy [options]
# or
npx factory-factory@latest proxy [options]

Options:
  --private                   Enable generated-password auth

Other CLI commands:

ff proxy        # Start a public tunnel to your local FF server
ff build        # Build for production
ff db:migrate   # Run database migrations
ff db:studio    # Open Prisma Studio

Examples:

# Quick start with npx
npx factory-factory@latest serve

# Development mode with custom port
ff serve --dev --port 8080

# Production mode without auto-opening browser
ff serve --no-open

# Custom database location
ff serve --database-path /path/to/data.db

# Public tunnel with password auth
ff proxy --private

Tunnel prerequisite (ff proxy): cloudflared must be installed and available in your PATH.

Quick Start

  1. Authenticate required tools:

    gh auth login        # GitHub CLI
claude login         # Claude provider (required for CLAUDE sessions)

    For CODEX sessions, ensure your ChatGPT/Codex credentials are configured.

  2. Run Factory Factory:

    npx factory-factory@latest serve

  3. Create your first workspace:

    • Open the web UI (automatically opens at http://localhost:3000)
    • Configure your project with a local git repository
    • Optional: in Admin, choose an issue provider per project (GitHub Issues or Linear Issues)
    • Click "New Workspace" to create your first isolated worktree
    • Start chatting with your selected ACP provider (CLAUDE or CODEX)

Development

Development Commands

# Server
pnpm dev                     # Start dev server with hot reload
pnpm dev -- --no-open        # Without browser auto-open
pnpm dev -- --verbose        # With detailed logging
pnpm build                   # Build for production
pnpm start                   # Start production server

# Electron
pnpm dev:electron            # Start Electron with hot reload
pnpm build:electron          # Build distributable package

# Quality
pnpm test                    # Run tests
pnpm test:watch              # Run tests in watch mode
pnpm test:coverage           # Run tests with coverage
pnpm typecheck               # TypeScript checking
pnpm check:fix               # Lint + format with Biome

# Database
pnpm db:migrate              # Run migrations
pnpm db:studio               # Open Prisma Studio
pnpm db:generate             # Regenerate Prisma client

# Other
pnpm storybook               # Start Storybook for UI components
pnpm deps:check              # Check dependency rules

Architecture

Project (repository configuration)
    └── Workspace (isolated git worktree)
            ├── Session (ACP provider session: CLAUDE or CODEX)
            └── Terminal (PTY terminal)

Key capabilities:

  • Isolated workspaces: Each workspace gets its own git worktree and branch for true parallel development
  • Real-time streaming: WebSocket-based communication with ACP adapter subprocesses
  • ACP runtime: Each session runs through ACP (@agentclientprotocol/sdk) and negotiates provider capabilities (models/modes/config options) at runtime
  • Persistent sessions: Resume and review previous conversations
  • Terminal access: Full PTY terminal per workspace
  • Issue tracking integration: Use GitHub or Linear as the per-project issue provider
  • Kanban board: Visual project management with provider-specific issue intake

Feature Highlights

🔄 Ratchet (Automatic PR Progression)

Ratchet automatically moves pull requests toward merge by monitoring and fixing issues.

  • Automatic monitoring: Checks READY workspaces with open PRs every minute
  • Smart PR classification: Tracks PR state as CI_RUNNING, CI_FAILED, REVIEW_PENDING, READY, or MERGED
  • Auto-fix agents: Creates agent sessions to automatically fix CI failures and address review comments
  • Conflict resolution: Agents sync with main branch before applying fixes
  • Configurable behavior: Control CI fixes, review fixes, allowed reviewers, and auto-merge in Admin → Ratchet

🔗 GitHub Integration

Seamless integration with GitHub via the authenticated gh CLI.

  • Issue import: Start workspaces directly from GitHub issues with one-click import
  • PR tracking: Automatic PR state monitoring and status updates
  • Linked workspaces: Issues are automatically linked to their workspaces (prevents duplicates)
  • Kanban intake: GitHub Issues column shows issues assigned to @me for easy triage

📐 Linear Integration

Configure Linear as the issue provider per project in Admin settings.

  • Per-project provider: Choose GitHub Issues or Linear Issues per project
  • Secure API key storage: Linear API keys are encrypted at rest in project issue tracker config
  • Team-scoped intake: Kanban intake uses your assigned Linear issues for the configured team
  • Linked workspaces: Starting from a Linear issue stores linearIssueId, linearIssueIdentifier, and linearIssueUrl
  • State sync: Linear issues are best-effort transitioned when work starts and when PRs merge

📋 Kanban Board

Real-time visual project management with automatic column placement.

  • Smart columns: Issues intake (GitHub Issues or Linear Issues) → Working → Waiting → Done
  • Auto-categorization:
    • Working: Provisioning, new, failed, or actively running sessions
    • Waiting: Idle workspaces that have completed at least one session
    • Done: Workspaces with merged PRs
  • Live updates: Real-time workspace status and PR state changes
  • Mobile responsive: Optimized layout for mobile devices

⚡ Quick Actions

One-click prompts for common workflows, fully customizable via markdown.

  • Agent-driven: Each action creates a new ACP session with a predefined prompt
  • Extensible: Add custom actions by creating markdown files in prompts/quick-actions/
  • Built-in actions: Review code, simplify implementations, sync with main, rename branches, and more

Security Considerations

⚠️ Important: Factory Factory runs ACP adapters (for example Claude Code ACP and Codex ACP) with automatic command execution enabled by default. Agents can execute bash commands, write and modify files, and perform operations without manual confirmation.

This design enables seamless parallel workflows, but you should understand:

  • Workspace isolation: Each workspace operates in its own git worktree with a dedicated branch
  • Filesystem access: Active agent runtimes have full access to files within each workspace
  • Automatic execution: Commands run without approval prompts for uninterrupted operation
  • System-level access: Isolation is at the git worktree level, not containerized

Best practices:

  • ✅ Only use with repositories you trust
  • ✅ Review changes carefully before merging PRs
  • ✅ Keep your GitHub authentication secure
  • ✅ Keep Linear API keys scoped and rotated if using Linear integration
  • ✅ Monitor Ratchet auto-fix behavior in Admin settings
  • ✅ Consider running in a VM or container for untrusted code

Brand

Color Hex Usage
Factory Yellow #FFE500 Primary accent
White #FAFAFA Light backgrounds
Black #0A0A0A Dark backgrounds

Typography:

  • Inter Black - Headlines and logotype
  • IBM Plex Mono SemiBold - Code and app icon

Troubleshooting

Authentication Issues

GitHub CLI not authenticated:

gh auth status          # Check authentication status
gh auth login           # Login to GitHub

Claude Code not authenticated:

claude login            # Authenticate Claude Code CLI
claude --version        # Verify installation

Codex authentication/config issues:

  • Verify your ChatGPT/Codex account can access the selected model.
  • Recreate the session and confirm provider-specific model options appear in the chat bar.

Database Issues

Migration failures or corrupt database:

# Run migrations manually
ff db:migrate

# Optional reset (⚠️ destroys all local data; creates a backup first)
mv ~/factory-factory/data.db ~/factory-factory/data.db.bak
ff db:migrate

# View database in Prisma Studio
ff db:studio

Port Conflicts

The server automatically finds available ports if defaults are in use. Use --verbose to see which ports are selected:

Or specify custom ports:

ff serve --dev --port 8080 --backend-port 8081

Common Issues

"Command not found: ff"

  • Install globally: npm install -g factory-factory
  • Or use npx: npx factory-factory@latest serve

Workspace stuck in "Provisioning" state:

  • Check logs in the Terminal tab
  • Ensure git worktree creation succeeded
  • Verify repository has no uncommitted changes

Agent not responding:

  • Verify the selected provider is installed/authenticated (Claude/Codex)
  • Check adapter/runtime errors in backend logs (acp-runtime-manager, session)
  • Review session logs for error messages

PR state not updating:

  • Ensure GitHub CLI is authenticated: gh auth status
  • Manually refresh using the Refresh button in Kanban view
  • Check that repository has correct GitHub remote configured

Acknowledgements

This project was inspired by:

  • Conductor - Mac app for running coding agents in parallel
  • VibeKanban - Visual kanban for AI-assisted development
  • Gastown - Steve Yegge's multi-agent coding environment
  • Multiclaude - Dan Lorenc's parallel Claude sessions tool

License

MIT