Dead-simple Bun CLI that runs Codex and Claude Code in a loop.
# Add to your Claude Code skills
git clone https://github.com/axeldelafosse/loopGuides for using cli tools skills like loop.
Dead-simple Bun CLI that runs codex and claude in a loop. Uses tmux to run the interactive TUIs side-by-side. Codex and Claude talk to each other through the Codex App Server and Claude Code Channels.
Install:
curl -fsSL https://raw.githubusercontent.com/axeldelafosse/loop/main/install.sh | bash
Run:
loop
or
loop --prompt "Implement {feature}" --proof "Use {skill} to verify your changes" --tmux
By default loop uses Codex as the main worker and Claude as a reviewer. To run Claude as the main worker instead:
loop --agent claude --tmux
One agent is the main worker, the other acts as a reviewer. They work together on a PLAN.md and iterate until they both agree the task is done. Then the main worker creates a draft PR.
This is a "meta agent loop" to help coding agents become long-running agents. Stop baby sitting your agents: let them iterate on tasks with clear proof requirements until they are done. Run multiple reviews to continue the feedback loop.
This is not an "agent harness" and the goal isn't to re-invent the wheel: loop leverages existing agent harnesses like codex and claude, with their own implementation of the "agent teams" orchestration. The models are getting better very quickly and they are highly optimized for their respective harnesses.
No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
~/.loop/runs/... so runs can be resumed by run id or session/thread idIMPORTANT: you SHOULD run this inside a VM. It is NOT safe to run this on your host machine. The agents are running in YOLO mode!
bun x playwright install chromiumlume clone)curl -fsSL https://raw.githubusercontent.com/axeldelafosse/loop/main/install.sh | bash
Installer currently supports macOS and Linux and installs loop, claude-loop, and codex-loop to ~/.local/bin by default.
# run from source
./loop.ts --prompt "Implement {feature}" --proof "Use {skill} to verify your changes"
# start paired interactive tmux workspace with no task yet
./loop.ts
# open live panel of running claude/codex instances
./loop.ts dashboard
# build executable
bun run build
./loop --prompt "Implement {feature}" --proof "Use {skill} to verify your changes"
# start paired interactive tmux workspace with no task yet
./loop
# open live panel explicitly
./loop dashboard
Some notes:
--agent selects the primary worker and the other model stays available as reviewer/support.loop "Implement {feature}") or via --prompt.--proof is strongly recommended for autonomous task runs and should describe how to prove the task works (tests, commands, and checks to run). Be specific.loop --tmux and waits for you to provide the first task in the TUIs.loop --tmux still works explicitly and behaves the same as the default loop command..md path), loop first runs a planning step to create PLAN.md, then uses PLAN.md for the main loop.loop dashboard opens the live panel for active sessions, recent paired runs, and tmux sessions.loop will use PLAN.md if it exists.Paired mode is the default. loop starts one primary worker (--agent, default: codex) and keeps the other model available as a persistent reviewer/support agent. They coordinate directly through the built-in bridge instead of asking the human to relay messages.
Each paired run gets a run id and a manifest under ~/.loop/runs/<repo-id>/<run-id>/.
--run-id <id> to resume a specific paired run.--session <id> to resolve an existing paired run from its run id, Claude session id, or Codex thread id.--session <id> still works as a raw Claude/Codex session resume flag.--worktree or --tmux, resumed paired runs keep the same run id so worktree and tmux naming stay aligned.bun run install:global
loop --help
This creates loop, claude-loop, and codex-loop in ~/.local/bin on Unix, and loop.exe plus claude-loop.cmd/codex-loop.cmd on Windows.
If loop is not found, add this to ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
Then reload your shell:
source ~/.zshrc
.github/workflows/ci.yml)main (.github/workflows/release.yml)package.json (v${version})Example release:
# bump patch version and push commit + tag
bun run release:patch
# equivalent to:
# npm version patch && git push --follow-tags
Prebuilt binaries check for updates automatically on startup and download new versions in the background. The update is applied on the next startup.
# manually check for updates
loop update
# same thing (alias)
loop upgrade
When running from source (bun src/loop.ts), auto-update is disabled — use git pull instead.
For a real tmux + real Codex app-server reconnect check, run:
bun tests/loop/codex-tmux-proxy.manual.ts --model gpt-5.4-mini
This is a manual harness only. It is not part of bun test.
It restarts against a fresh Codex thread after the app-server drop.
claude-loop: shorthand for loop --claude-onlycodex-loop: shorthand for loop --codex-onlydashboard: open the live panel for active sessions, recent paired runs, and tmux sessions-a, --agent <claude|codex>: agent to run (default: codex)--claude-only: use Claude for work, review, and plan review--codex-only: use Codex for work, review, and plan review-p, --prompt <text|.md file>: prompt text or a .md prompt file path. Plain text auto-creates PLAN.md first.--proof <text>: optional proof criteria for task completion--codex-model <model>: set the model passed to codex (LOOP_CODEX_MODEL can also set this by default)--codex-reviewer-model <model>: set the model used when Codex is acting as a reviewer. This applies to both --review and --review-plan, and falls back to --codex-model when omitted.--claude-reviewer-model <model>: set the model used when Claude is acting as a reviewer. This applies to both --review and --review-plan.-m, --max-iterations <number>: max loop count (default: 20)-d, --done <signal>: done signal string (default: <promise>DONE</promise>)--format <pretty|raw>: output format (default: pretty)--review [claude|codex|claudex]: run a review when done (default: claudex; bare --review also uses claudex). With claudex, both reviews run in parallel, then both comments are passed back to the original agent so it can decide what to address. If both reviews found the same issue, that is a stronger signal to fix it.--review-plan [other|claude|codex|none]: reviewer for the automatic plan review pass that runs after plain-text prompts create PLAN.md (default: other, the non-primary model). Use none to skip plan review.--run-id <id>: reuse a specific run id. In paired mode this resumes the stored run state and keeps tmux/worktree naming aligned to that id.--session <id>: resume from a paired run id or stored Claude/Codex session id. In single-agent mode, raw session/thread ids are passed through directly.--tmux: run loop in a detached tmux session so it survives SSH disconnects. In paired mode, Claude and Codex open side-by-side in the same tmux workspace. With no prompt and no proof, paired mode starts an interactive workspace and waits for the first task. Session name format: repo-loop-X--worktree: create and run inside a fresh git worktree + branch automatically. Resumed run ids re-enter or recreate the matching worktree when possible. Worktree/branch format: repo-loop-X-h, --help: helpUse --agent claude.
You might be surprised by how often a good model pushes back on comments. And if they both agree, that is in fact a strong signal. A model can make a mistake and catch