loopflow 0.8.6
Run LLM coding agents from reusable prompt files
Requires Python: >=3.8
Keywords: agents, ai, automation, claude, cli, codex, coding, gemini, llm, prompts, workflow

# Loopflow

Loopflow helps you maintain flow and craft using coding agents (Claude Code, Codex, Gemini CLI, 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

Waves are objects with 4 primary fields.

| Field | Usage | Form |
|-------|------|------|
| **Area** | Scope and context | pathset |
| **Flow** | Process followed / steps taken | sequence of prompts |
| **Direction** | Defines success, quality, and aesthetics | prompt |
| **Stimulus** | Watch, loop, or cron | mode |

## Steps

```bash
lf debug -c    # paste an error, watch it fix
lf design      # interactive design session
```

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

### Planning steps (`plan/`)

| Step | What it does |
|------|--------------|
| `review` | Research an area — architecture, complexity, quality, potential |
| `reduce` | Find simplification opportunities |
| `polish` | Find polish priorities |
| `expand` | Find expansion opportunities |
| `iterate` | Read review, write design to address it |
| `ingest` | Pick wave item, move to scratch/ |
| `kickoff` | Elaborate design — alternatives, research, imagine success/failure |
| `wave-plan` | Synthesize analysis into a wave plan proposal |
| `5whys` | Root cause analysis on a bug fix |

### Code steps (`code/`)

| Step | What it does |
|------|--------------|
| `debug` | Fix an error |
| `implement` | Build from a design doc |
| `compress` | Simplify touched code |
| `gate` | Ship-ready code and reviewer-friendly docs |

### Interactive steps (`interactive/`)

| Step | What it does |
|------|--------------|
| `design` | Interactive design session |
| `explore` | Investigate the codebase |
| `refine` | Refine existing work |

### Scan steps (`scan/`)

| Step | What it does |
|------|--------------|
| `scan/cves` | Check dependencies for known vulnerabilities |
| `scan/deps` | Check for major version bumps, deprecations |
| `scan/upstream` | Check external APIs for breaking changes |

### Ops steps (`ops/`)

| Step | What it does |
|------|--------------|
| `consolidate` | Reorganize scratch/ for wave |
| `add-to-wave` | Promote from scratch/ to wave/ |
| `synthesize` | Combine multiple perspectives into one |
| `validate` | Validate flows, steps, and directions |

## Flows

```bash
lf design && lf implement && lf gate    # chain steps manually
lf flow ship                            # or use a named flow
```

Steps chain into flows. Flows feed into waves.

### Code flows (`code/`)

| Flow | Steps |
|------|-------|
| `ship` | implement → compress → gate → consolidate |
| `design-and-ship` | design → implement → reduce → polish |
| `pair` | design → ship |
| `grind` | review → iterate → ship → gate |
| `incident` | debug → 5whys → ship |
| `start` | ingest → kickoff |
| `ship-wave` | start → ship → update-wave |

### Plan flows (`plan/`)

| Flow | Steps |
|------|-------|
| `wave-reduce` | review → fork(reduce×3) → publish |
| `wave-polish` | review → fork(polish×3) → publish |
| `wave-expand` | review → fork(expand×3) → publish |
| `research` | explore → review → publish |
| `publish` | consolidate → add-to-wave |

### Scan flows (`scan/`)

| Flow | Steps |
|------|-------|
| `scan` | scan/cves → scan/deps → scan/upstream |

### Forks

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

```bash
lf flow wave-reduce    # runs reduce 3x with different perspectives
```

`wave-reduce` forks `reduce` across infra-engineer, designer, and product-engineer directions, then synthesizes and publishes to wave/.

## Playing in the Waves

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

```bash
lfq create engbot .                # create a wave
lfq run engbot                            # start a wave
```

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

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

loopflow.update_wave("engbot", flow="ship", direction=["designer"], area=["designs/"])
loopflow.run_wave("engbot")
PY
```

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

```bash
lf review -d designer,product-engineer
lf review -d ceo
```

## Install

```bash
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`.

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

```bash
cargo install --git https://github.com/loopflowstudio/loopflow --bin lf --bin lfd
```
Install the Rust binaries directly with cargo.

## Query lfd (lfq)

```bash
uv tool install loopflow
lfq                  # status overview
lfq list             # list waves
lfq logs engbot      # tail agent output
```

`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

```bash
uv pip install loopflow
```

```python
import loopflow.api as loopflow

loopflow.waves()
loopflow.create_wave("engbot", repo=".", flow="ship", direction=["product-engineer"])
loopflow.run_wave("engbot")
```

[Documentation →](docs/index.md)

## Integrations

**Coding Agents**
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — Anthropic's coding agent (default)
- [Codex CLI](https://github.com/openai/codex) — OpenAI's coding agent
- [Gemini CLI](https://github.com/google-gemini/gemini-cli) — Google's coding agent
- [OpenCode](https://github.com/anomalyco/opencode) — Open source coding agent

**Skill Libraries**
- [superpowers](https://github.com/obra/superpowers) — prompt library (`lf sp:<skill>`)
- [SkillRegistry](https://skillregistry.io/) — remote skill directory (`lf sr:<skill>`)
- [rams](https://rams.ai) — accessibility and visual design review

## Requirements

- macOS
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [OpenCode](https://github.com/anomalyco/opencode)

## License

MIT