Local AI coding orchestration for repo-scale work. LLM councils plan it. Ralph loops recover it. OpenCode worktrees ship it.
LoopTroop helps you turn a coding ticket into a planned, reviewable, agent-executed pull request.
Instead of running one long fragile coding-agent chat, LoopTroop separates the work into planning, approval, isolated execution, recovery, and final review.
Start here: Docs | Getting Started | Ticket Flow | LLM Council | Execution Loop
LoopTroop is a local control plane for AI coding agents.
You give it a local git repository and a ticket. LoopTroop helps turn that ticket into:
- a focused planning interview
- a product-style spec
- a bead-by-bead implementation plan
- an isolated coding workspace
- OpenCode execution
- recovery attempts when the agent gets stuck
- a pull request you review before finishing
The goal is not to make the AI invisible. The goal is to make AI coding work easier to inspect, restart, approve, and trust.
LoopTroop is designed for serious agentic coding experiments.
The coding agent runs through OpenCode and may execute commands for a long time. Depending on your OpenCode and tooling setup, that can mean broad local privileges.
Recommended setup: run LoopTroop inside a disposable VM, cloud dev machine, or sandboxed development environment.
Why:
- git worktrees protect your attached repository checkout
- approval gates protect the workflow
- logs and artifacts help you inspect what happened
- a VM protects the rest of your computer
A good rule: only attach repositories and folders you are comfortable letting an AI coding agent modify.
Ticket
-> file scan
-> LLM Council planning
-> human approval
-> bead-by-bead OpenCode execution
-> Ralph-style recovery when needed
-> final test and PR review
LoopTroop keeps workflow state outside the model, stores durable artifacts, and asks for approval at important boundaries.
Direct coding-agent loops are useful, but they often become hard to control when the work gets large.
| Common problem | What happens | LoopTroop's answer |
|---|---|---|
| Weak planning | One model makes one plan and misses details | LLM Council planning |
| Context rot | A long chat loses important information | Phase-specific context |
| Bad retries | The agent keeps repairing inside a polluted session | Ralph-style fresh retries |
| Risky edits | Work happens in your normal checkout | Isolated git worktrees |
| Hidden state | You cannot see what really happened | SQLite state, JSONL logs, and .ticket/** artifacts |
| Silent automation | The agent keeps moving without you | Human approval gates |
The LLM Council is LoopTroop's planning system.
Instead of asking one model for one answer, LoopTroop can ask multiple models to draft independently, compare options, refine the best direction, and verify coverage before execution.
Used for:
- interview questions
- PRD/spec generation
- bead planning
- plan review
Read more: LLM Council
A bead is a small implementation unit.
LoopTroop breaks bigger work into beads so the coding agent can focus on one concrete task at a time instead of trying to solve the entire feature in one giant pass.
A bead can include:
- purpose
- acceptance criteria
- dependencies
- target files
- expected validation
Read more: Beads
When an agent attempt fails, continuing the same conversation can make things worse.
LoopTroop can preserve a compact note about what failed, reset the worktree to a known point, discard the polluted session, and retry with fresh context.
That is the Ralph-loop idea in LoopTroop:
fail -> write down what failed -> reset -> retry fresh
Read more: Execution Loop
LoopTroop executes ticket work inside isolated git worktrees instead of directly editing your normal project checkout.
This helps keep:
- your main checkout cleaner
- ticket artifacts local to the ticket
- retry/reset behavior more reliable
- diffs easier to inspect before PR delivery
Worktrees are repository isolation, not machine isolation. For host-level safety, use a VM.
Read more: System Architecture
LoopTroop is not a fully unattended "press button and pray" system.
You approve the important transitions, including planning artifacts, execution setup, and final PR outcome.
The model does the work. You keep control of when the workflow moves forward.
Read more: Ticket Flow
Use a VM or disposable development environment first.
git clone https://github.com/looptroop-ai/LoopTroop.git
cd LoopTroop
npm run devnpm run dev starts the local LoopTroop stack and runs the startup preflight. The preflight can refresh the local OpenCode CLI, sync direct npm dependencies, and run safe audit remediation during local development.
The app starts:
| Service | Default address |
|---|---|
| Dashboard | http://localhost:5173 |
| Backend API | http://localhost:3000 |
| Docs | http://localhost:5174 |
| OpenCode | http://127.0.0.1:4096 |
Once the dashboard is open:
- click Add Project
- select a local git repository with a GitHub origin
- create a ticket
- review the plan
- approve execution
- inspect the final PR result
Full setup: Getting Started
LoopTroop expects:
- Node.js and npm
- git
- a local repository with a GitHub origin
- OpenCode available locally
- model/provider configuration through OpenCode
- a VM or sandboxed dev environment for safer agent execution
LoopTroop is for developers experimenting with agentic coding workflows who want more control than a single coding chat.
It is especially useful if you care about:
- repo-scale AI coding
- multi-model planning
- LLM orchestration
- agent orchestration
- isolated execution
- fresh-context retries
- human-gated PR delivery
- auditable logs and artifacts
LoopTroop is not a magic autopilot.
It does not remove the need to review code, inspect diffs, protect secrets, or run work in a safe environment.
It is best understood as an orchestration layer around coding agents: planning, state, approvals, execution boundaries, retries, and delivery.
The README gives the first-glance overview. The full docs live at:
Useful pages:
| Page | What it explains |
|---|---|
| Getting Started | Setup, ports, environment variables, first project attach |
| Ticket Flow | End-to-end workflow from ticket to PR result |
| LLM Council | Multi-model draft, vote, refine, and coverage planning |
| Execution Loop | Bead execution, retries, resets, context wipe notes |
| Beads | The execution-unit model |
| System Architecture | Runtime actors, storage, worktrees, artifacts |
| OpenCode Integration | Session ownership, reconnects, streaming, health checks |
| FAQ | Common questions and terminology |
When the app is running, the same docs are also available from the dashboard.
LoopTroop is early alpha software.
The current focus is making local AI coding orchestration more durable, understandable, and recoverable.
Expect active changes around:
- planning quality
- execution reliability
- OpenCode integration
- retry behavior
- review surfaces
- workflow safety
- documentation
Roadmap: Roadmap
Contributions, ideas, bug reports, and workflow feedback are welcome.