Loop Orchestrator helps you run a persistent AI software engineering team inside tmux: CTO/planner, frontend engineer, backend engineer, full-stack engineer, QA reviewer, scout, and release lead. Each role gets a project brief, assigned repositories, model/provider settings, safety rules, and a repeatable operating loop.

Use it as a lightweight open-source alternative to hard-coded agent scripts when you want multi-agent coding workflows, terminal AI teams, Claude Code orchestration, Codex automation, Gemini CLI scouting, and tmux-based background execution.

⚡ Autonomous SME Team (3 commands)

Point it at a repo, give it a goal, and watch a project-trained team of subject-matter experts deliver it — a Product Manager decomposes the goal, an Architect shapes it, and Frontend / Backend / QA / CT / Security SMEs (each on its best-fit model) implement, test, and review, coordinating through a shared blackboard.

loop learn                         # train the team on your codebase → PROJECT-INTELLIGENCE.md
loop run "add rate limiting to the /login endpoint"   # decompose → assign → drive the loop
loop monitor                       # single-screen mission control: board + every agent, live

How it works:

• Trained on your project. loop learn scans the repo and writes PROJECT-INTELLIGENCE.md (stack, frameworks, layout, and the real test/build/lint commands). Every SME is grounded in it, so agents never invent commands.
• 27 built-in SME roles. Architect, Product Manager, Frontend, Backend, Full-stack, QA, CT/Test-Automation, DevOps, SRE, Security, DBA, Performance, Accessibility, Mobile, Data, ML, and more — each with a deep, discipline-specific system prompt and a best-fit provider (loop roles lists them). Set sme: backend on a role and it inherits the expert prompt.
• Real autonomy, not one-shot. A planner agent decomposes the goal into assigned tasks on a shared JSONL blackboard (.loop/board/). The loop dispatches each task to the right SME, detects completion from the agent's exit code and structured output, then runs your project's test command as a verification gate before marking it done.
• tmux is the viewport; agents run headless. Each SME gets a tiled pane so you can watch the whole team on one screen, but control flow spawns a fresh headless claude -p / codex exec / gemini -p child per task — reliable completion detection, no screen-scraping.
• Safe by default. loop run is a dry-run that drives the board with no spend; add --execute to actually launch the agents.

Verified, self-healing, parallel — the part that separates a real team from a demo:

• Independent critic. A reviewer SME (a different model than the implementer) reviews the actual git diff against the acceptance criteria and can reject — no rubber-stamping. Rejections go back with reasons.
• Self-healing. Failed tasks are retried with the captured error injected into the next attempt, up to maxRepairs, then escalated to a human instead of stranded.
• Regression-gated. HEAD is snapshotted before each task; a change that turns a green suite red is reverted. Test/CI files are hashed so an agent can't weaken its own grader to pass (reward-hacking guard).
• True parallelism. Each role works in its own git worktree on its own branch, so SMEs run concurrently (maxParallel) without clobbering each other; accepted work merges back to main through the critic gate.
• Budgeted. Per-task spend is tracked to .loop/board/costs.jsonl; the run stops at budgetUsd.

Proven end-to-end. A real run of two engineer SMEs (Claude) implementing two functions in parallel in isolated git worktrees, reviewed by an independent QA critic:

$ loop run "Add subtract(a,b) and multiply(a,b) to math.js, each with a test" --execute
🛰  Run … · sandbox — decomposed into 3 tasks across 4 SMEs
  [done] t1 (be) Accepted by qa. Merged to main. math.js exports subtract(a, b) …
  [done] t2 (be) Accepted by qa. Merged to main. math.js exports multiply(a, b) …
# both worktree branches merged to main → node --test → 5/5 pass → $0.56 (budget $2.00)

See docs/autonomous-team.md for the full guide.

Live dashboard

loop dashboard opens a local mission control that answers, at a glance, is it working, where is it stuck, and what's it costing:

• KPI bar — progress %, agents active, in-progress/blocked counts, retries, estimated time left, and spend vs budget (turns amber/red as you approach the cap).
• Needs-attention strip — every blocked / rejected / escalated task with the reason (e.g. "webhook signature check failing"), so you know what to fix.
• Agent swimlanes — each SME's current task, live idle timer (goes amber/red when stuck), spend, and an expandable peek at its terminal output.
• Dependency-aware task board — kanban by status with dependency chips and critical-path markers, so you see what's actually gating completion.
• Activity timeline — the live event + inter-agent message feed (handoffs, rejections, merges).

It polls JSON endpoints every 2.5s — zero build step, just loop dashboard. (loop monitor is the single-screen terminal version.)

Example: a todo app the team built

examples/todo-app is a real, zero-dependency todo app (Node node:http API + vanilla-JS UI + node:test tests) built by the SME team via loop run — a Backend SME wrote the store and API in an isolated worktree, a Frontend SME built the UI, and a QA critic reviewed each diff before merging to main. The loop.config.yaml and brief.md that produced it are included so you can reproduce it.

Why This Exists

Most agent workflows are either one-off prompts or hard-coded scripts. Loop Orchestrator gives you a portable repo-level control plane:

• Role-based tmux sessions for long-running agents
• Per-role provider and model selection
• First-class unsafe-mode switches for tools that support them
• Project briefs, repo scope, and guardrails
• Prompt-only mode for safe setup, execute mode for launching agents
• Local dashboard for session status and logs
• Generic YAML config that works across teams and projects

Who It Is For

• Solo developers running multiple coding agents in parallel
• Engineering leads assigning planner, frontend, backend, QA, and release roles
• Teams using Claude Code, Codex, Gemini CLI, or custom terminal agents
• Developers who want tmux sessions that keep running on a VM after disconnecting
• Open-source maintainers who want repeatable AI code review and release workflows

What You Can Build

• AI software engineering team in tmux
• Multi-agent coding workflow for frontend and backend repos
• Automated PR planning, implementation, QA, and release review loops
• Long-running background agent sessions on a devbox or VM
• Configurable coding-agent dashboard for local teams

Keywords

AI agents, agent orchestrator, tmux orchestrator, Claude Code, Codex, OpenAI Codex, Gemini CLI, multi-agent coding, agentic coding, autonomous coding agents, terminal agents, software engineering agents, AI devtools, developer tools, workflow automation, GitHub automation, code review agents, LLM agents.

Prerequisites

Install the tools you want Loop Orchestrator to control:

# Required
brew install tmux

# Optional providers. Install and log in to whichever ones you use.
claude
codex
gemini

You can use subscription/OAuth CLI login or API keys. Loop Orchestrator detects local CLI state and API-key env vars, but it never stores secret values in config.

Install

npm install -g loop-orchestrator
loop --version

For local development:

npm install
npm run build
npm link

Step-by-Step Setup

1. Open Your Project

Run Loop Orchestrator from the repo or workspace where you want the team config to live.

cd /path/to/your/repo

For a full-stack setup, you can also create one orchestration folder and point it at multiple repos:

mkdir ai-team
cd ai-team

2. Initialize Config

loop init

This creates:

• loop.config.yaml: providers, repositories, roles, and loops
• brief.md: project brief sent to every role
• .loop/: generated prompts and run metadata

3. Detect Local Provider Auth

loop auth status
loop auth configure --write

This checks your machine for:

• claude
• codex
• gemini
• agy
• API env vars such as ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY

It writes auth metadata into loop.config.yaml, for example:

providers:
  frontend:
    type: claude
    command: claude
    auth:
      mode: subscription
      configured: true

4. Edit Your Project Brief

Open brief.md and describe the product, coding rules, test expectations, release rules, and any hard constraints.

Example:

# Project Brief

Build changes in small PRs.
Use worktrees for parallel tasks.
Run tests before reporting completion.
Do not run destructive database commands.

5. Configure Repositories

Edit loop.config.yaml and point repositories to real local paths:

repositories:
  - name: frontend-app
    path: ~/work/frontend-app
    role: frontend
    defaultBranch: main
    protectedBranches: [main, production]

  - name: backend-api
    path: ~/work/backend-api
    role: backend
    defaultBranch: main
    protectedBranches: [main, production]

6. Configure Providers

Use the provider best suited for each role:

providers:
  planner:
    type: claude
    model: claude-opus-4-8
    command: claude
    auth:
      mode: subscription
      configured: true

  frontend:
    type: claude
    model: claude-sonnet-4-6
    command: claude
    dangerouslySkipPermissions: true
    auth:
      mode: subscription
      configured: true

  backend:
    type: codex
    model: gpt-5.4
    effort: medium
    command: codex
    yolo: true
    auth:
      mode: subscription
      configured: true

  scout:
    type: gemini
    model: gemini-3.5-flash
    command: gemini
    auth:
      mode: subscription
      configured: true

Unsafe switches:

• dangerouslySkipPermissions: true adds Claude --dangerously-skip-permissions
• yolo: true adds Codex --yolo

Use these only in trusted local/VM worktrees.

7. Configure Roles

Roles decide which tmux sessions start and what each agent is responsible for.

roles:
  - name: cto
    title: Technical lead and architecture reviewer
    provider: planner
    repositories: [frontend-app, backend-api]
    responsibilities:
      - Convert issues into acceptance criteria and implementation plans.
      - Review architecture, risk, rollback, and backward compatibility.

  - name: fe1
    title: Frontend engineer
    provider: frontend
    repositories: [frontend-app]
    responsibilities:
      - Implement responsive UI changes.
      - Run browser smoke tests and capture screenshots.

  - name: be1
    title: Backend engineer
    provider: backend
    repositories: [backend-api]
    responsibilities:
      - Implement APIs, migrations, and tests.
      - Avoid destructive database operations.

  - name: qa1
    title: QA and release reviewer
    provider: backend
    repositories: [frontend-app, backend-api]
    responsibilities:
      - Verify acceptance criteria.
      - Produce final merge readiness notes.

8. Validate Config

loop validate

Fix any config errors before starting sessions.

9. Start in Safe Mode First

Safe mode creates tmux sessions and prompt files, but does not launch provider CLIs.

loop start --run issue-123
tmux ls

Open one session:

tmux attach -t loop-demo-product-issue-123-cto

10. Launch Real Agents

After safe mode looks right, launch configured provider commands:

loop start --run issue-123 --execute

Start only specific roles:

loop start --run issue-123 --role fe1 qa1 --execute

11. Use the Dashboard

loop dashboard

Open:

http://localhost:4318

The dashboard shows active sessions and lets you inspect recent tmux output.

12. Check Logs and Stop Runs

loop status
loop logs loop-demo-product-issue-123-fe1
loop stop issue-123

Core Commands

loop init                 # create loop.config.yaml and brief.md (autonomous SME team)
loop learn                # scan the repo → PROJECT-INTELLIGENCE.md (trains the team)
loop roles                # list the 27 built-in SME disciplines
loop run "<goal>"         # decompose a goal, launch the team, drive the autonomy loop
loop run "<goal>" --execute  # ...and actually launch the agent CLIs (default is dry-run)
loop monitor              # single-screen mission control: board + every agent pane, live
loop auth status          # inspect local provider CLI/API-key readiness
loop auth configure --write # write detected local auth mode into config
loop validate             # validate config
loop start --run bug-42   # start role sessions in tmux (manual, prompt-only)
loop status               # list loop sessions
loop logs <session>       # capture recent tmux pane output
loop stop bug-42          # kill sessions for a run
loop dashboard            # open local web dashboard (now includes the board)

Common Workflows

One Repo

cd ~/work/backend-api
loop init
loop auth configure --write
loop validate
loop start --run fix-login-bug --execute

Frontend + Backend

mkdir ~/work/product-team
cd ~/work/product-team
loop init

Then edit loop.config.yaml:

repositories:
  - name: frontend-app
    path: ~/work/frontend-app
    role: frontend
  - name: backend-api
    path: ~/work/backend-api
    role: backend

Run:

loop auth configure --write
loop validate
loop start --run issue-456 --execute

VM Setup

Install once on the VM user that will run the agents:

npm install -g loop-orchestrator
claude
codex
gemini

Then:

cd ~/work/product-team
loop init
loop auth configure --write
loop start --run overnight-batch --execute

Because sessions run in tmux, they keep running if your laptop disconnects.

Update Package

npm install -g loop-orchestrator@latest
loop --version

Example Roles

Provider flags can be configured without raw argument strings:

providers:
  frontend:
    type: claude
    model: claude-sonnet-4-6
    auth:
      mode: subscription
      configured: true
    dangerouslySkipPermissions: true
  backend:
    type: codex
    model: gpt-5.4
    effort: medium
    auth:
      mode: subscription
      configured: true
    yolo: true

Local Auth Setup

Loop Orchestrator can inspect your machine and write provider auth hints into config:

loop auth status
loop auth configure --write

It detects:

• Claude CLI from claude, or API env vars ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN
• Codex CLI from codex, or API env var OPENAI_API_KEY
• Gemini CLI from gemini or agy, or env vars GEMINI_API_KEY, GOOGLE_API_KEY, GOOGLE_CLOUD_PROJECT

The command stores only metadata such as auth mode, command name, and env var name. It does not write secret values into loop.config.yaml.

roles:
  - name: cto
    title: Technical lead and architecture reviewer
    provider: planner
    repositories: [frontend-app, backend-api]
  - name: fe1
    title: Frontend engineer
    provider: frontend
    repositories: [frontend-app]
  - name: be1
    title: Backend engineer
    provider: backend
    repositories: [backend-api]
  - name: qa1
    title: QA and release reviewer
    provider: backend
    repositories: [frontend-app, backend-api]

Safety Model

Loop Orchestrator never edits your repositories by itself. It creates tmux sessions and role prompts. The agents you configure do the work, so your safety posture depends on provider flags and local permissions.

Recommended defaults:

• Use prompt-only mode until the team config is correct.
• Assign narrow repository scopes per role.
• Enable dangerouslySkipPermissions or yolo only for disposable worktrees or trusted environments.
• Keep production branches protected.
• Require tests before release review.
• Avoid destructive database commands in all prompts.

Dashboard

loop dashboard --port 4318

The dashboard shows active sessions and lets you inspect recent tmux output from the browser.

Troubleshooting

No loop.config.yaml found

Run:

loop init
loop auth status

tmux: command not found

Install tmux:

brew install tmux

On Ubuntu:

sudo apt-get update
sudo apt-get install -y tmux

Provider Not Detected

Install and log in to the provider CLI, then rerun:

loop auth status
loop auth configure --write

Start Fresh for a Run

loop stop issue-123
loop start --run issue-123 --execute

Inspect Generated Prompts

Prompts are written under:

.loop/runs/<run-id>/prompts/

License

MIT