# LoopTroop

> A free, open-source local GUI orchestrator that uses LLM councils, Ralph loops, and OpenCode worktrees to automate complex, multi-file coding tasks from ticket to merged code.

LoopTroop is a free, MIT-licensed local GUI orchestrator for long-running, high-correctness AI software delivery. Built in TypeScript and released under the MIT License, it takes a raw coding ticket all the way to a reviewable, agent-executed pull request by breaking the job into clean, isolated stages rather than relying on a single endless AI chat session. The project is currently at v0.3.1 and self-described as early alpha software that is usable for real work.

## What It Is

LoopTroop sits between you and an AI coding agent (OpenCode), acting as a structured orchestration layer that owns workflow state, artifact boundaries, retries, approvals, and delivery mechanics around model calls. It is designed specifically for **complex, multi-file feature work** where alignment and correctness matter more than raw speed. The tool intentionally sacrifices immediate response time in favor of a "slow and perfect" paradigm — ensuring the final result matches the developer's original intent.

## Three-Layer Architecture

The system is organized into three distinct architectural layers, each with a clear mission:

- **Planning (LLM Councils Plan It):** Human input flows through an AI interview, a Product Requirements Document (PRD), and atomic bead decomposition. Multiple independent LLM instances draft plans, score each other with a weighted rubric, vote anonymously, and the winner synthesizes the strongest ideas from losing proposals.
- **Execution (Ralph Loops Perfect It):** Each bead — the smallest independently implementable unit of work — runs inside an isolated Git worktree. On failure, the Ralph Loop preserves a compact error trace, discards the contaminated session entirely, and retries with fresh context. This cycle can run unattended for 10+ hours by design.
- **Shipping (OpenCode Worktrees Ship It):** After a final verification pass, code is handed off to the main branch only after explicit human sign-off.

## Context Engineering as a Core Primitive

LoopTroop treats context rot — the degradation of AI output caused by bloated conversational history — as the primary enemy of autonomous agents. The engine isolates payloads to the active status at every stage: during execution, the agent sees only the specific active bead, its immediate file target, and the test file. During planning phases, it receives only the minimum context relevant to the current step. This approach eliminates conversation pollution, prevents LLM drift, and keeps model focus high across multi-hour engineering cycles.

## Workflow and Human Gates

A ticket's lifecycle moves through five stages:

- **Draft State:** Define the task ticket with a clear description.
- **Council Review:** Multiple LLM models collaborate, draft, vote, and refine a plan.
- **Bead Decomposition:** The approved plan is split into atomic, verifiable tasks with explicit acceptance criteria, target files, and validation steps.
- **Execution Sandbox:** OpenCode executes each bead inside isolated Git worktrees; the Ralph Loop handles failures.
- **Human Approval:** Every change requires explicit developer sign-off before code is committed or merged.

## Setup Path and Requirements

LoopTroop is cloned directly from GitHub and started with `npm run dev`, serving a local GUI at `localhost:5173`. It requires Node.js, npm, Git, OpenCode with at least one configured model provider, and a local repository with a GitHub origin. Because the orchestrator runs OpenCode in `dangerously-skip-permissions` mode to enable unattended execution, the project strongly recommends running inside a disposable VM, cloud dev machine, or sandboxed environment. Git worktrees isolate code changes but do not sandbox the command execution process itself.

## Update: v0.3.1

The latest release is v0.3.1, published on June 22, 2026, with the repository last pushed on June 25, 2026. The GitHub repository lists the project as early alpha with the full ticket lifecycle implemented and core primitives — planning, execution, and retries — functional. The roadmap and changelog are maintained in the docs at looptroop.ovh/docs/. Contributions, bug reports, and workflow feedback are welcomed via GitHub.

## Features
- LLM Council multi-model planning with anonymous voting and winner refinement
- Bead decomposition into atomic, independently verifiable coding tasks
- Ralph Loop: discard degraded sessions and retry with fresh context
- Isolated Git worktree execution for each bead
- Context engineering: minimal per-status context to prevent LLM drift
- Human approval gates at planning, execution, and PR stages
- Adaptive interview phase for requirement clarification
- PRD (Product Requirements Document) generation from interview answers
- 10+ hour unattended execution support
- Local GUI at localhost:5173
- SQLite state storage with JSONL logs and YAML artifacts
- OpenCode integration for agent-driven code execution
- Multi-model council support across providers (Anthropic, OpenAI, NVIDIA NIM, etc.)
- Real-time live execution log streaming
- Diff review and bead-level approval before commit

## Integrations
OpenCode, Git, GitHub, Node.js, Anthropic Claude, OpenAI, NVIDIA NIM

## Platforms
LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.3.1

## Links
- Website: https://www.looptroop.ovh
- Documentation: https://www.looptroop.ovh/docs/
- Repository: https://github.com/looptroop-ai/LoopTroop
- EveryDev.ai: https://www.everydev.ai/tools/looptroop