JSPM

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.

Table of Contents

• Installation
• Running
• Quick Start
• CLI Reference
• Architecture
• Feature Highlights
  • Ratchet (Automatic PR Progression)
  • GitHub Integration
  • Kanban Board
  • Quick Actions
• Development
• Desktop App (Electron)
• Security Considerations
• Troubleshooting
• Acknowledgements

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)

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

Running

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 (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

# 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
   • 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
• GitHub integration: Import issues, track PR state, automatic PR progression via Ratchet
• Kanban board: Visual project management with GitHub 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

📋 Kanban Board

Real-time visual project management with automatic column placement.

• Smart columns: GitHub 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
• ✅ Monitor Ratchet auto-fix behavior in Admin settings
• ✅ Consider running in a VM or container for untrusted code

Brand

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

# Reset database (⚠️ destroys all data)
ff db:reset

# 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:

ff serve --verbose

Or specify custom ports:

ff serve --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