loopflow 0.5.2__tar.gz

loopflow-0.5.2/.gitignore

@@ -0,0 +1,11 @@
+# Python
+__pycache__/
+.pytest_cache/
+
+# Swift
+.build/
+xcuserdata/
+.swiftpm/xcode/
+
+# Claude Code (personal state)
+.claude/settings.local.json

loopflow-0.5.2/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: loopflow
+Version: 0.5.2
+Summary: Arrange LLMs to code in harmony
+Author: Jack
+License-Expression: MIT
+Keywords: ai,claude,cli,coding,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pathspec>=0.11.0
+Requires-Dist: pydantic-ai-slim[anthropic]>=1.0.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Loopflow
+
+## Usage
+
+```bash
+lf review
+lf implement: add auth
+lf ship
+```
+
+Run LLM coding tasks from reusable prompt files.
+
+macOS only. Supports Claude Code, OpenAI Codex, and Google Gemini CLI via configuration.
+
+## Install
+
+```bash
+pip install loopflow
+lf ops install    # installs Claude Code, Codex, Gemini CLI, worktrunk
+```
+
+## Why Worktrees?
+
+Loopflow is designed for running background agents while you work on something else. That means isolated branches - you can't have an agent committing to the branch you're actively editing.
+
+The workflow: create a worktree, run tasks there, merge when ready. You can have multiple features in flight at once.
+
+## Quick Start
+
+```bash
+wt switch --create my-feature --execute pwd
+cd ../loopflow.my-feature
+
+lf design                     # interactive: figure out what to build
+lf ship                       # batch: implement, review, test, commit, open PR
+```
+
+`lf design` runs `.lf/design.lf`. `lf ship` runs the `ship` pipeline from `.lf/config.yaml`.
+
+## Tasks
+
+Tasks are prompt files in `.lf/`. Here's an example:
+
+```markdown
+# .lf/review.lf
+
+Review the diff on the current branch against `main` and fix any issues found.
+
+The deliverable is the fixes themselves, not a written review.
+
+## What to look for
+
+- Style guide violations (read STYLE.md)
+- Bugs, logic errors, edge cases
+- Unnecessary complexity
+- Missing tests
+```
+
+Run tasks by name:
+
+```bash
+lf review                     # run .lf/review.lf
+lf review -x src/utils.py     # add context files
+lf : "fix the typo"           # inline prompt, no task file
+```
+
+All `.md` files at repo root (README, STYLE, etc.) are included as context automatically.
+
+## Pipelines
+
+Chain tasks in `.lf/config.yaml`:
+
+```yaml
+pipelines:
+  ship:
+    tasks: [implement, review, test, commit]
+    pr: true    # open PR when done
+```
+
+```bash
+lf ship    # runs each task, auto-commits between steps
+```
+
+## Worktrees
+
+Loopflow delegates worktree management to worktrunk. Use `wt` directly:
+
+```bash
+wt list                       # show all worktrees
+wt switch --create auth       # create or switch to a worktree
+wt remove auth                # remove worktree + branch
+```
+
+## Session Tracking
+
+Track running tasks across multiple terminals (maestro is optional):
+
+```bash
+lf ops maestro start              # optional web UI (tails logs)
+lf ops status                     # show running sessions (reads SQLite)
+
+# In another terminal
+lf implement                  # auto mode task registers automatically
+
+# Check from anywhere
+lf ops status                     # see all running sessions
+```
+
+Sessions write to SQLite in auto mode; the maestro UI reads the same database.
+
+## Configuration
+
+```yaml
+# .lf/config.yaml
+agent_model: claude:opus     # Model: claude, codex, gemini (or backend:variant)
+push: true        # auto-push after commits
+pr: false         # open PR after pipelines
+
+# Tasks that default to interactive mode (default is auto)
+interactive:
+  - design
+  - iterate
+
+ide:
+  warp: true
+  cursor: true
+```
+
+## Run Modes
+
+By default, tasks run in **auto mode**: non-interactive with streaming output. This is ideal for most coding tasks and background execution. All runs append logs under `~/.lf/logs/<worktree>/`.
+
+Use `-i` to run interactively (full chat, can interrupt) or configure per-task defaults:
+
+```bash
+lf implement           # auto mode (default)
+lf design              # interactive (from config)
+lf implement -i        # force interactive
+lf design -a           # force auto
+lf implement &         # background (shell handles it)
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-i, --interactive` | Run in interactive mode (override default) |
+| `-a, --auto` | Run in auto mode (override default) |
+| `-x, --context` | Add context files |
+| `-w, --worktree` | Create worktree and run task there |
+| `-c, --copy` | Copy prompt to clipboard, show token breakdown |
+| `-v, --paste` | Include clipboard content in prompt |
+| `-m, --model` | Choose model (backend or backend:variant) |
+| `--parallel` | Run with multiple models in parallel |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `lf <task>` | Run a task from `.lf/` |
+| `lf <pipeline>` | Run a pipeline |
+| `lf : "prompt"` | Inline prompt |
+| `lf ops compare a b` | Compare two worktree implementations |
+| `wt <subcommand>` | Worktree management (worktrunk) |
+| `lf ops pr create` | Open GitHub PR |
+| `lf ops pr land [-a]` | Squash-merge to main |
+| `lf ops land [--no-pr] [--force] [--base]` | Land locally via worktrunk |
+| `lf ops commit [-p]` | Generate commit message and commit |
+| `lf ops init` | Initialize repo with prompts and config |
+| `lf ops install` | Install Claude Code, Codex, Gemini CLI |
+| `lf ops doctor` | Check dependencies |
+| `lf ops maestro start` | Start session tracking daemon |
+| `lf ops maestro stop` | Stop session tracking daemon |
+| `lf ops status` | Show running sessions |

loopflow-0.5.2/README.md

@@ -0,0 +1,174 @@
+# Loopflow
+
+## Usage
+
+```bash
+lf review
+lf implement: add auth
+lf ship
+```
+
+Run LLM coding tasks from reusable prompt files.
+
+macOS only. Supports Claude Code, OpenAI Codex, and Google Gemini CLI via configuration.
+
+## Install
+
+```bash
+pip install loopflow
+lf ops install    # installs Claude Code, Codex, Gemini CLI, worktrunk
+```
+
+## Why Worktrees?
+
+Loopflow is designed for running background agents while you work on something else. That means isolated branches - you can't have an agent committing to the branch you're actively editing.
+
+The workflow: create a worktree, run tasks there, merge when ready. You can have multiple features in flight at once.
+
+## Quick Start
+
+```bash
+wt switch --create my-feature --execute pwd
+cd ../loopflow.my-feature
+
+lf design                     # interactive: figure out what to build
+lf ship                       # batch: implement, review, test, commit, open PR
+```
+
+`lf design` runs `.lf/design.lf`. `lf ship` runs the `ship` pipeline from `.lf/config.yaml`.
+
+## Tasks
+
+Tasks are prompt files in `.lf/`. Here's an example:
+
+```markdown
+# .lf/review.lf
+
+Review the diff on the current branch against `main` and fix any issues found.
+
+The deliverable is the fixes themselves, not a written review.
+
+## What to look for
+
+- Style guide violations (read STYLE.md)
+- Bugs, logic errors, edge cases
+- Unnecessary complexity
+- Missing tests
+```
+
+Run tasks by name:
+
+```bash
+lf review                     # run .lf/review.lf
+lf review -x src/utils.py     # add context files
+lf : "fix the typo"           # inline prompt, no task file
+```
+
+All `.md` files at repo root (README, STYLE, etc.) are included as context automatically.
+
+## Pipelines
+
+Chain tasks in `.lf/config.yaml`:
+
+```yaml
+pipelines:
+  ship:
+    tasks: [implement, review, test, commit]
+    pr: true    # open PR when done
+```
+
+```bash
+lf ship    # runs each task, auto-commits between steps
+```
+
+## Worktrees
+
+Loopflow delegates worktree management to worktrunk. Use `wt` directly:
+
+```bash
+wt list                       # show all worktrees
+wt switch --create auth       # create or switch to a worktree
+wt remove auth                # remove worktree + branch
+```
+
+## Session Tracking
+
+Track running tasks across multiple terminals (maestro is optional):
+
+```bash
+lf ops maestro start              # optional web UI (tails logs)
+lf ops status                     # show running sessions (reads SQLite)
+
+# In another terminal
+lf implement                  # auto mode task registers automatically
+
+# Check from anywhere
+lf ops status                     # see all running sessions
+```
+
+Sessions write to SQLite in auto mode; the maestro UI reads the same database.
+
+## Configuration
+
+```yaml
+# .lf/config.yaml
+agent_model: claude:opus     # Model: claude, codex, gemini (or backend:variant)
+push: true        # auto-push after commits
+pr: false         # open PR after pipelines
+
+# Tasks that default to interactive mode (default is auto)
+interactive:
+  - design
+  - iterate
+
+ide:
+  warp: true
+  cursor: true
+```
+
+## Run Modes
+
+By default, tasks run in **auto mode**: non-interactive with streaming output. This is ideal for most coding tasks and background execution. All runs append logs under `~/.lf/logs/<worktree>/`.
+
+Use `-i` to run interactively (full chat, can interrupt) or configure per-task defaults:
+
+```bash
+lf implement           # auto mode (default)
+lf design              # interactive (from config)
+lf implement -i        # force interactive
+lf design -a           # force auto
+lf implement &         # background (shell handles it)
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-i, --interactive` | Run in interactive mode (override default) |
+| `-a, --auto` | Run in auto mode (override default) |
+| `-x, --context` | Add context files |
+| `-w, --worktree` | Create worktree and run task there |
+| `-c, --copy` | Copy prompt to clipboard, show token breakdown |
+| `-v, --paste` | Include clipboard content in prompt |
+| `-m, --model` | Choose model (backend or backend:variant) |
+| `--parallel` | Run with multiple models in parallel |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `lf <task>` | Run a task from `.lf/` |
+| `lf <pipeline>` | Run a pipeline |
+| `lf : "prompt"` | Inline prompt |
+| `lf ops compare a b` | Compare two worktree implementations |
+| `wt <subcommand>` | Worktree management (worktrunk) |
+| `lf ops pr create` | Open GitHub PR |
+| `lf ops pr land [-a]` | Squash-merge to main |
+| `lf ops land [--no-pr] [--force] [--base]` | Land locally via worktrunk |
+| `lf ops commit [-p]` | Generate commit message and commit |
+| `lf ops init` | Initialize repo with prompts and config |
+| `lf ops install` | Install Claude Code, Codex, Gemini CLI |
+| `lf ops doctor` | Check dependencies |
+| `lf ops maestro start` | Start session tracking daemon |
+| `lf ops maestro stop` | Stop session tracking daemon |
+| `lf ops status` | Show running sessions |

loopflow-0.5.2/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "loopflow"
+dynamic = ["version"]
+description = "Arrange LLMs to code in harmony"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Jack" }]
+keywords = ["llm", "claude", "ai", "coding", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "pathspec>=0.11.0",
+    "pyyaml>=6.0",
+    "pydantic>=2.12.5",
+    "pydantic-ai-slim[anthropic]>=1.0.0",
+    "tiktoken>=0.7.0",
+    "fastapi>=0.115.0",
+    "uvicorn>=0.30.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+]
+
+[project.scripts]
+lf = "loopflow.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loopflow"]
+include = [
+    "src/loopflow/prompts/*.md",
+    "src/loopflow/templates/**/*.md",
+    "src/loopflow/templates/**/*.yaml",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/loopflow",
+    "src/loopflow/prompts/*.md",
+    "src/loopflow/templates/**/*.md",
+    "src/loopflow/templates/**/*.yaml",
+]
+
+[tool.hatch.version]
+path = "src/loopflow/__init__.py"

loopflow-0.5.2/src/loopflow/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.5.2"

loopflow-0.5.2/src/loopflow/builtins/__init__.py

@@ -0,0 +1,15 @@
+"""Builtin prompts for loopflow commands.
+
+These are prompts used by loopflow's own commands (lf ops pr create, etc.),
+not user-defined tasks in .lf/.
+"""
+
+from pathlib import Path
+
+_BUILTINS_DIR = Path(__file__).parent
+
+
+def get_builtin_prompt(name: str) -> str:
+    """Get a builtin prompt by name. Raises FileNotFoundError if not found."""
+    prompt_file = _BUILTINS_DIR / f"{name}.txt"
+    return prompt_file.read_text()

loopflow-0.5.2/src/loopflow/builtins/commit_message.txt

@@ -0,0 +1,26 @@
+Generate a commit message for the staged changes.
+
+Review the diff and write a concise commit message.
+
+Do not ask questions. If anything is unclear, make the best assumption and proceed.
+
+## Output format
+
+Return a structured response with:
+- **title**: lowercase, with optional area prefix (e.g. `llm_http: add structured output`)
+- **body**: brief explanation if needed, otherwise empty string
+
+## Title style
+
+Titles are lowercase and concise. Use an area prefix when changes are focused on a specific module or feature area.
+
+Examples:
+- `llm_http: add structured output for pr messages`
+- `pr workflow: add -a flag to commit and push`
+- `fix typo in readme`
+
+## Body style
+
+Keep it brief—one sentence or a few bullets if the change needs explanation. Empty string is fine for self-explanatory changes.
+
+Most commits don't need a body. Only add one if the "why" isn't obvious from the title.

loopflow-0.5.2/src/loopflow/builtins/pr_message.txt

@@ -0,0 +1,48 @@
+Generate a PR title and body for the changes on this branch.
+
+Review the diff against main and summarize what changed and why.
+
+Do not ask questions. If anything is unclear, make the best assumption and proceed.
+
+## Output format
+
+Return a structured response with:
+- **title**: lowercase, with optional area prefix (e.g. `llm_http: add structured output`)
+- **body**: markdown with headers, code blocks for commands, and bullet lists
+
+## Title style
+
+Titles are lowercase and concise. Use an area prefix when changes are focused on a specific module or feature area. The area can be new or existing.
+
+Examples:
+- `llm_http: add structured output for pr messages`
+- `pr workflow: add -a flag to commit and push`
+- `fix worktree cleanup on branch delete`
+
+## Body style
+
+Use markdown headers to organize the body. Open with a "Usage" or "Try it" section showing commands in code blocks. Then explain what changed.
+
+Structure:
+1. **Usage section** (header + code block) - how to try it, run it, or see it in action
+2. **Summary** - one paragraph explaining what this PR does and why
+3. **Changes** (optional) - bullet list of notable changes if helpful
+
+Keep it medium length. Stay high-level; don't enumerate every file.
+
+Example body:
+```
+## Usage
+
+\`\`\`bash
+lf ops pr create -a
+lf ops pr update -a
+\`\`\`
+
+PR create and update now generate title/body via Claude API instead of reading from .lf/COMMIT. The -a flag adds, commits, and pushes before creating/updating.
+
+## Changes
+
+- New llm_http module for structured LLM responses
+- Builtin prompts stored in package, separate from user .lf/ tasks
+```

loopflow-0.5.2/src/loopflow/cli/__init__.py

@@ -0,0 +1,97 @@
+"""Loopflow CLI: Arrange LLMs to code in harmony."""
+
+import sys
+
+import typer
+
+from loopflow.config import ConfigError, load_config
+from loopflow.context import find_worktree_root, gather_task
+from loopflow.init_check import check_init_status
+
+app = typer.Typer(
+    name="lf",
+    help="Arrange LLMs to code in harmony.",
+    no_args_is_help=True,
+)
+
+# Import and register subcommands
+from loopflow.cli import run as run_module
+from loopflow.cli import ops
+from loopflow.cli import agent
+
+app.add_typer(ops.app, name="ops")
+app.add_typer(agent.app, name="agent")
+
+# Register top-level commands
+app.command(context_settings={"allow_extra_args": True, "allow_interspersed_args": True})(run_module.run)
+app.command()(run_module.inline)
+app.command(name="pipeline")(run_module.pipeline)
+app.command()(run_module.cp)
+
+
+def main():
+    """Entry point that supports 'lf <task>' and 'lf <pipeline>' shorthand."""
+    known_commands = {
+        "run",
+        "pipeline",
+        "inline",
+        "cp",
+        "ops",
+        "agent",
+        "--help",
+        "-h",
+    }
+
+    try:
+        if len(sys.argv) > 1:
+            first_arg = sys.argv[1]
+
+            # Inline prompt: lf : "prompt"
+            if first_arg == ":":
+                sys.argv.pop(1)
+                sys.argv.insert(1, "inline")
+            elif first_arg not in known_commands:
+                # Handle colon suffix: "lf implement: add logout" -> "lf implement add logout"
+                if first_arg.endswith(":"):
+                    sys.argv[1] = first_arg[:-1]
+                name = sys.argv[1]
+                repo_root = find_worktree_root()
+                config = load_config(repo_root) if repo_root else None
+
+                has_pipeline = config and name in config.pipelines
+                has_task = repo_root and gather_task(repo_root, name) is not None
+
+                if has_pipeline and has_task:
+                    typer.echo(f"Error: '{name}' exists as both a pipeline and a task", err=True)
+                    typer.echo(f"  Pipeline: defined in .lf/config.yaml", err=True)
+                    typer.echo(f"  Task: .claude/commands/{name}.md or .lf/{name}.*", err=True)
+                    typer.echo(f"Remove one to resolve the conflict.", err=True)
+                    raise SystemExit(1)
+
+                if has_pipeline:
+                    sys.argv.insert(1, "pipeline")
+                elif has_task:
+                    sys.argv.insert(1, "run")
+                else:
+                    # Check if repo is initialized
+                    status = check_init_status(repo_root) if repo_root else None
+                    if status and not status.has_commands and not status.has_lf_dir:
+                        # Uninitialized repo - suggest init
+                        typer.echo(f"No task named '{name}' found.", err=True)
+                        typer.echo("", err=True)
+                        typer.echo("This repo hasn't been set up for loopflow yet.", err=True)
+                        typer.echo("Run: lf ops init", err=True)
+                    else:
+                        # Initialized but task missing - suggest creating it
+                        typer.echo(f"No task or pipeline named '{name}'", err=True)
+                        typer.echo(f"Create: .claude/commands/{name}.md", err=True)
+                    raise SystemExit(1)
+
+        app()
+    except ConfigError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()