cluoop

A desktop orchestrator for Claude Code harness engineering. Run multiple Claude Code sessions side-by-side, or let the Planner → Generator → Evaluator loop build projects autonomously.

Install

npm install -g cluoop

Requires Claude Code CLI installed and authenticated.

Usage

cluoop       # Launch the app
cluoop run    # Same as above
cluoop build  # Build without launching

Modes

Harness Mode

Automated build loop with three agents:

1. Planner — Creates plan.md and sprint-contract.md from your project brief
2. Generator — Implements the current sprint based on the contract
3. Evaluator — Tests the implementation, checks design quality, verifies architecture compliance

The loop: Planner → Generator → Evaluator → FAIL? → Planner revises → retry. PASS? → git commit → back to you for the next sprint.

You brainstorm with Agent 1 (interactive Claude session), then click Start Harness to kick off the loop. After each sprint passes, you discuss next steps with Agent 1 and start another sprint in the same project.

Normal Mode

Two Claude Code terminals side-by-side sharing the same workspace. No harness automation — just parallel sessions.

Features

• Background sessions — Switch between sessions without killing processes. Output buffers replay on switch.
• Real terminals — Each panel is a real PowerShell + Claude Code PTY via node-pty. Full ANSI color, cursor control, interactive input.
• Image paste — Ctrl+V pastes clipboard images to a temp file and types the path into the terminal.
• Copy/paste — Ctrl+V for text paste, Ctrl+C with selection to copy, Ctrl+Shift+C always copies.
• Git integration — Auto git init on project creation, auto commit on each sprint PASS.
• Toast notifications — Agent completion and harness cycle alerts with optional sound.
• Resume on restart — If the app closes mid-harness, it resumes from the interrupted phase.
• Multi-window — Open additional Normal or Harness windows sharing the same workspace.
• Per-agent model config — Set model (Opus/Sonnet/Haiku) per agent role in Settings.

Settings

Open via the gear icon in the sidebar:

• General — Output directory, max sprint iterations, notification sound toggle
• Models — Model selection per agent (Brainstormer, Planner, Generator, Evaluator)
• Big Goal — Set a high-level objective for the brainstormer context

Architecture

Electron Main Process          React Renderer (Vite)
┌────────────────────┐         ┌──────────────────────┐
│ AgentManager       │◄──IPC──►│ Sidebar (sessions)   │
│   ClaudeProcess ×N │         │ BrainstormPanel      │
│ Orchestrator (FSM) │         │ HarnessPanel (×3)    │
│ SessionStore       │         │ or NormalPanel (×2)   │
│ SettingsStore      │         │ Toast, StatusBar     │
└────────────────────┘         └──────────────────────┘

• AgentManager — Manages PTY processes per session×role. Buffers output for background sessions.
• Orchestrator — State machine driving Planner → Generator → Evaluator loop with git commits.
• ClaudeProcess — Spawns PowerShell + claude via node-pty. Detects done markers for harness agents.

Evaluator Standards

The evaluator is strict by design:

1. Boot check — Code must compile and run
2. Visual-first testing — Opens the app in a browser before reading any code
3. Design quality — Rejects generic AI-looking designs. Expects distinctive typography, cohesive palettes, intentional spatial composition, and polished micro-interactions
4. Sprint scope — Every acceptance criterion must work in the running app
5. Architecture compliance — Files must match plan.md, no future-sprint code

Any single failure → immediate VERDICT: FAIL → Planner revises → loop retries.

Requirements

• Windows 10+ (PowerShell terminal)
• Node.js 20+
• Claude Code CLI installed and authenticated
• Visual Studio Build Tools (for node-pty, though prebuilds usually work)

License

MIT