Loopflow

Loopflow helps you maintain flow and craft using coding agents (Claude Code, Codex, OpenCode) at high scale.

Loopflow helps you create and run Waves. Waves are chains of coding agents working together in pre-defined ways.

Waves are first built manually through more interactive exploration. Eventually waves become autonomous through looping, scheduling, and watching for changes.

Waves

A wave is area × direction × flow.

# wave/designer/designer.yaml
flow: build
mode: loop
direction:
  - ux
area:
  - designs/
triggers:
  - signal: wave
    source_wave_id: infra
    flow: build

Modes

The wave's mode controls its execution pattern.

Triggers

A trigger pairs a signal (what changed) with a flow (what to run). Triggers are a list — multiple triggers of the same signal are fine.

Every new wave ships with two default triggers: repo (whole repo → integrate) and ci_failure → ci-fix. These don't need to be declared in the YAML.

Steps

lf debug -c    # paste an error, watch it fix
lf design      # interactive design session
lf npx:explain-code   # fetch from npx skills ecosystem and run

Steps are prompts that run coding agents. Add your own in .lf/steps/.

Planning steps (plan/)

Code steps (code/)

Interactive steps (interactive/)

Scan steps (scan/)

Ops steps (ops/)

Flows

lf design && lf implement && lf gate    # chain steps manually
lf build                                # or use a named flow

Steps chain into flows. Flows feed into waves.

Flows can include mechanical ops items directly:

- implement
- gate
- ops: land --create-pr

Code flows (code/)

Plan flows (plan/)

Scan flows (scan/)

Forks

Forks run a step in parallel with different directions, then synthesize the results.

lf wave-reduce    # runs reduce 3x with different perspectives

wave-reduce forks reduce across infra, ux, and ceo directions, then reconciles results with update-wave.

Branches

Branches route a flow based on an agent's assessment of the current state.

# flow: qa-deploy
- qa
- triage
- branch:
    paths:
      fix:
        flow: qa-fix
        description: "Blocking issues found, fix before deploy"
      deploy:
        flow: deploy
        description: "Clean enough to ship"

The branch construct runs a routing agent that reads scratch/ and chooses a path. The selected sub-flow runs inline. Combined with cron scheduling and loop iteration, this enables cycles like daily QA → fix → deploy.

Playing in the Waves

Once you have played with chaining steps into flows, you're ready to ride some waves.

lfq create engbot .                # create a wave
lfq run engbot                            # ride a wave

Configure flow/area/direction with loopflow.update_wave(...), then ride it with loopflow.run_wave(...).

python - <<'PY'
import loopflow.api as loopflow

loopflow.update_wave("engbot", flow="build", direction=["ux"], area=["designs/"])
loopflow.run_wave("engbot")
PY

You can compose multiple directions to add additional nuance or perspectives.

lf research -d ux,clarity
lf research -d ceo

Install

curl -fsSL https://github.com/loopflowstudio/loopflow/releases/latest/download/install.sh | sh

Default install location is ~/.local/bin. Override with LF_INSTALL_DIR=/path.

First install guides you through connecting Claude, GitHub, and optional providers. Use --no-interactive to skip (CI, Docker, scripted installs).

Built-in steps and flows included. lf init sets up your coding agent and preferences.

cargo install --git https://github.com/loopflowstudio/loopflow --bin lf --bin lfd

Install the Rust binaries directly with cargo.

Query lfd (lfq)

uv tool install loopflow
lfq                  # status overview
lfq list             # list waves
lfq show engbot      # show wave details
lfq logs engbot      # tail agent output
lfq stop engbot      # stop a running wave
lfq delete engbot    # remove wave and history
lfq usage            # token usage summary (group by wave)
lfq usage --wave engbot  # usage for one wave (group by step)
lfq providers        # list providers with auth status and models
lfq auth status      # provider auth status (GitHub / Claude / Codex / OpenCode Zen)
lfq auth github      # connect GitHub in your browser
lfq auth claude      # connect Claude in your browser
lfq auth codex       # connect Codex in your browser
lfq auth zen         # connect OpenCode Zen in your browser
lfq auth disconnect github
lfq token revoke abc123   # revoke connection tokens by hash prefix
lfq token revoke --all    # revoke all connection tokens

uv tool install loopflow installs the Python CLI (lfq) and Python API only.
Use the install script or cargo to install lf and lfd.

Python API

uv pip install loopflow

import loopflow.api as loopflow

loopflow.waves()
loopflow.create_wave("engbot", repo=".", flow="build", direction=["clarity"])
loopflow.create_wave("ux", repo=".", flow="build", direction=["ux"], area=["docs/"])
loopflow.create_wave("infra", repo=".", flow="grind", direction=["infra"], area=["rust/"])
loopflow.add_trigger("ux", signal="wave", source_wave_id="infra")
loopflow.run_wave("ux")

import loopflow.api as loopflow

chord = loopflow.create_chord("frontend")
waves = loopflow.waves()
loopflow.add_chord_member(chord.id, waves[0].id)
loopflow.list_chord_members(chord.id)
loopflow.list_wave_chords(waves[0].id)
loopflow.remove_chord_member(chord.id, waves[0].id)

Documentation →

tmux Plugin

# Add to .tmux.conf
set -g @plugin 'loopflowstudio/loopflow.tmux'
run '~/.tmux/plugins/tpm/tpm'

Status bar shows wave state: [lf: main] or [lf: 3 waves | engbot]. Customize the format:

# .tmux.conf
set -g @loopflow_status_format '⚡#{status}'       # change wrapper
set -g @loopflow_status_format '[#{branch}]'        # branch only
set -g @loopflow_status_format '[lf: #{status}]'    # default

Variables: #{status} (computed text), #{branch}, #{step}, #{waves}, #{wave}.

Keybindings start with prefix+l:

Two built-in layouts: lf-dev (editor + agent + shell), lf-swarm (monitor + 3 worktree workers).

Works without lf or lfq installed — status shows placeholder, keybindings display clear messages.

Integrations

Coding Agents

• Claude Code — Anthropic's coding agent (default)
• Codex CLI — OpenAI's coding agent
• OpenCode — Open source coding agent

Skill Libraries

• npx skills — install/search skills (lf npx:<skill>)
• superpowers — prompt library (lf sp:<skill>)
• SkillRegistry — remote skill directory (lf sr:<skill>)
• rams — accessibility and visual design review

Requirements

• macOS or Linux
• Claude Code, Codex, or OpenCode
• Concerto (visual app) is macOS-only

License

MIT