This project provides a "meta agent loop" for automating coding tasks using AI agents like Codex and Claude. It enables these agents to work collaboratively in a persistent, iterative loop, reviewing each other's work until a task is proven complete, ultimately generating draft pull requests. This is beneficial for users who want to offload complex or repetitive coding tasks to AI agents without constant supervision.

How It Works

The core approach involves pairing two AI agents, typically Codex and Claude, where one acts as the primary worker and the other as a reviewer. They communicate directly via a built-in bridge, iterating on a PLAN.md or a provided prompt until predefined proof criteria are met. The system leverages tmux for side-by-side interactive terminal interfaces and stores run states for seamless resumption. This design allows agents to self-correct and refine solutions over multiple iterations, mimicking a pair programming workflow.

Quick Start & Requirements

• Primary install / run command:
  • Prebuilt binary: curl -fsSL https://raw.githubusercontent.com/axeldelafosse/loop/main/install.sh | bash
  • From source: bun run build then ./loop
• Non-default prerequisites and dependencies:
  • Codex and Claude installed and logged in.
  • tmux (for interactive TUIs).
  • Bun (for building from source).
  • git and gh CLI.
  • GitHub fine-grained personal access token.
  • Crucially: Recommended to run inside a VM (e.g., Docker, Lume) due to agents running in "YOLO mode".
  • Optional: Playwright (bun x playwright install chromium).
• Links:
  • Install script: https://raw.githubusercontent.com/axeldelafosse/loop/main/install.sh
  • Examples and detailed options are provided within the README.

Highlighted Details

• Paired Agent Collaboration: Default mode runs Codex and Claude side-by-side, with one working and the other reviewing, communicating directly.
• Persistence and Resumption: Run states are saved under ~/.loop/runs/, allowing tasks to be resumed by run ID or session/thread ID.
• Automated Workflow: Iterates until task completion is proven, then triggers reviews and creates draft PRs.
• Worktree Integration: Option to automatically create and manage tasks within a fresh Git worktree and branch.
• Detached Sessions: Supports running in detached tmux sessions (--tmux), surviving SSH disconnects.
• Auto-Update: Prebuilt binaries automatically check for and download updates.

Maintenance & Community

Continuous Integration and release pipelines are defined in .github/workflows/, ensuring automated testing and builds for Linux, macOS, and Windows. Release artifacts include compiled binaries. No specific community links (Discord, Slack) were found in the provided README.

Licensing & Compatibility

The project is released under the MIT License. This permissive license generally allows for broad use, including integration into commercial and closed-source projects without significant restrictions.

Limitations & Caveats

The project strongly advises running within a sandboxed environment like a VM due to the "YOLO mode" operation of the AI agents, implying potential risks if run directly on a host system. The setup requires significant prerequisites, including the installation and configuration of specific AI models (Codex, Claude) and related developer tools.