loopflow 0.2.2__tar.gz

loopflow-0.2.2/.gitignore

@@ -0,0 +1,8 @@
+# Python
+__pycache__/
+
+# Claude Code (personal state)
+.claude/settings.local.json
+
+# Worktrees (created by lf start)
+.lf/worktrees/

loopflow-0.2.2/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: loopflow
+Version: 0.2.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: 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
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Loopflow
+
+Run LLM coding tasks from reusable prompt files.
+
+macOS only. Currently uses Claude Code; other backends planned.
+
+## Install
+
+```bash
+pip install loopflow
+lf meta install    # installs Claude Code via npm
+```
+
+## 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
+lf wt create my-feature       # branch + worktree, opens IDEs
+cd .lf/worktrees/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
+
+```bash
+lf wt create auth             # .lf/worktrees/auth/, opens Warp + Cursor
+lf wt list                    # show all worktrees
+lf wt clean                   # remove merged branches
+```
+
+## Configuration
+
+```yaml
+# .lf/config.yaml
+push: true        # auto-push after commits
+pr: false         # open PR after pipelines
+
+ide:
+  warp: true
+  cursor: true
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --print` | Batch mode (non-interactive) |
+| `-x, --context` | Add context files |
+| `-w, --worktree` | Create worktree and run task there |
+| `-c, --copy` | Copy prompt to clipboard, show token breakdown |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `lf <task>` | Run a task from `.lf/` |
+| `lf <pipeline>` | Run a pipeline |
+| `lf : "prompt"` | Inline prompt |
+| `lf wt create/list/clean` | Worktree management |
+| `lf pr create` | Open GitHub PR |
+| `lf pr land [-a]` | Squash-merge to main |
+| `lf meta install` | Install Claude Code |
+| `lf meta doctor` | Check dependencies |

loopflow-0.2.2/README.md

@@ -0,0 +1,116 @@
+# Loopflow
+
+Run LLM coding tasks from reusable prompt files.
+
+macOS only. Currently uses Claude Code; other backends planned.
+
+## Install
+
+```bash
+pip install loopflow
+lf meta install    # installs Claude Code via npm
+```
+
+## 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
+lf wt create my-feature       # branch + worktree, opens IDEs
+cd .lf/worktrees/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
+
+```bash
+lf wt create auth             # .lf/worktrees/auth/, opens Warp + Cursor
+lf wt list                    # show all worktrees
+lf wt clean                   # remove merged branches
+```
+
+## Configuration
+
+```yaml
+# .lf/config.yaml
+push: true        # auto-push after commits
+pr: false         # open PR after pipelines
+
+ide:
+  warp: true
+  cursor: true
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --print` | Batch mode (non-interactive) |
+| `-x, --context` | Add context files |
+| `-w, --worktree` | Create worktree and run task there |
+| `-c, --copy` | Copy prompt to clipboard, show token breakdown |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `lf <task>` | Run a task from `.lf/` |
+| `lf <pipeline>` | Run a pipeline |
+| `lf : "prompt"` | Inline prompt |
+| `lf wt create/list/clean` | Worktree management |
+| `lf pr create` | Open GitHub PR |
+| `lf pr land [-a]` | Squash-merge to main |
+| `lf meta install` | Install Claude Code |
+| `lf meta doctor` | Check dependencies |

loopflow-0.2.2/pyproject.toml

@@ -0,0 +1,49 @@
+[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",
+]
+
+[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"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/loopflow"]
+
+[tool.hatch.version]
+path = "src/loopflow/__init__.py"

loopflow-0.2.2/src/loopflow/__init__.py

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

loopflow-0.2.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 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.2.2/src/loopflow/builtins/commit_message.txt

@@ -0,0 +1,24 @@
+Generate a commit message for the staged changes.
+
+Review the diff and write a concise commit message.
+
+## 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.2.2/src/loopflow/builtins/pr_message.txt

@@ -0,0 +1,46 @@
+Generate a PR title and body for the changes on this branch.
+
+Review the diff against main and summarize what changed and why.
+
+## 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 pr create -a
+lf 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.2.2/src/loopflow/cli/__init__.py

@@ -0,0 +1,74 @@
+"""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
+
+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 wt, pr, meta
+
+app.add_typer(wt.app, name="wt")
+app.add_typer(pr.app, name="pr")
+app.add_typer(meta.app, name="meta")
+
+# Register top-level commands
+app.command()(run_module.run)
+app.command()(run_module.inline)
+app.command(name="pipeline")(run_module.pipeline)
+
+
+def main():
+    """Entry point that supports 'lf <task>' and 'lf <pipeline>' shorthand."""
+    known_commands = {"run", "pipeline", "inline", "wt", "pr", "meta", "--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:
+                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. "
+                        "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:
+                    typer.echo(f"Error: No task or pipeline named '{name}'", err=True)
+                    typer.echo(f"Create .lf/{name}.lf or add '{name}' to pipelines in .lf/config.yaml", err=True)
+                    raise SystemExit(1)
+
+        app()
+    except ConfigError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

loopflow-0.2.2/src/loopflow/cli/meta.py

@@ -0,0 +1,158 @@
+"""Setup and diagnostics commands."""
+
+import platform
+import shutil
+import subprocess
+
+import typer
+
+from loopflow.config import load_config
+from loopflow.context import find_worktree_root
+from loopflow.launcher import check_claude_available
+
+app = typer.Typer(help="Setup and diagnostics.")
+
+
+def _install_node() -> bool:
+    """Attempt to install Node.js via Homebrew on macOS."""
+    if platform.system() != "Darwin":
+        return False
+
+    if not shutil.which("brew"):
+        typer.echo("Homebrew not found. Install from https://brew.sh", err=True)
+        return False
+
+    typer.echo("Installing Node.js via Homebrew...")
+    result = subprocess.run(["brew", "install", "node"], capture_output=True)
+    return result.returncode == 0
+
+
+def _install_cask(name: str) -> bool:
+    """Install a Homebrew cask. Returns success."""
+    result = subprocess.run(
+        ["brew", "install", "--cask", name],
+        capture_output=True,
+    )
+    return result.returncode == 0
+
+
+@app.command()
+def version():
+    """Show loopflow version."""
+    from loopflow import __version__
+
+    typer.echo(f"loopflow {__version__}")
+
+
+@app.command()
+def install():
+    """Install loopflow dependencies based on config. macOS only."""
+    if platform.system() != "Darwin":
+        typer.echo("Error: lf install only supports macOS", err=True)
+        typer.echo("Install dependencies manually.", err=True)
+        raise typer.Exit(1)
+
+    if not shutil.which("brew"):
+        typer.echo("Error: Homebrew not found. Install from https://brew.sh", err=True)
+        raise typer.Exit(1)
+
+    # Load config to check what's needed
+    repo_root = find_worktree_root()
+    config = load_config(repo_root) if repo_root else None
+    ide = config.ide if config else None
+
+    # Node.js (required for Claude Code)
+    if not shutil.which("npm"):
+        typer.echo("Installing Node.js...")
+        if _install_node() and shutil.which("npm"):
+            typer.echo("✓ Node.js installed")
+        else:
+            typer.echo("✗ Could not install Node.js", err=True)
+            raise typer.Exit(1)
+    else:
+        typer.echo("✓ Node.js")
+
+    # Claude Code (always required)
+    if check_claude_available():
+        typer.echo("✓ Claude Code")
+    else:
+        typer.echo("Installing Claude Code...")
+        result = subprocess.run(
+            ["npm", "install", "-g", "@anthropic-ai/claude-code"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            typer.echo("✓ Claude Code installed")
+        else:
+            typer.echo(f"✗ Could not install Claude Code: {result.stderr}", err=True)
+            raise typer.Exit(1)
+
+    # Warp (if enabled in config, default true)
+    if not ide or ide.warp:
+        if shutil.which("warp"):
+            typer.echo("✓ Warp")
+        else:
+            typer.echo("Installing Warp...")
+            if _install_cask("warp"):
+                typer.echo("✓ Warp installed")
+            else:
+                typer.echo("✗ Could not install Warp", err=True)
+
+    # Cursor (if enabled in config, default true)
+    if not ide or ide.cursor:
+        if shutil.which("cursor"):
+            typer.echo("✓ Cursor")
+        else:
+            typer.echo("Installing Cursor...")
+            if _install_cask("cursor"):
+                typer.echo("✓ Cursor installed")
+            else:
+                typer.echo("✗ Could not install Cursor", err=True)
+
+
+@app.command()
+def doctor():
+    """Check loopflow dependencies based on config."""
+    all_ok = True
+
+    # Load config to check what's needed
+    repo_root = find_worktree_root()
+    config = load_config(repo_root) if repo_root else None
+    ide = config.ide if config else None
+
+    # Required
+    if shutil.which("npm"):
+        typer.echo("✓ npm")
+    else:
+        typer.echo("✗ npm - Install Node.js: https://nodejs.org")
+        all_ok = False
+
+    if check_claude_available():
+        typer.echo("✓ claude")
+    else:
+        typer.echo("✗ claude - Run: lf meta install")
+        all_ok = False
+
+    # IDE tools (based on config)
+    if not ide or ide.warp:
+        if shutil.which("warp"):
+            typer.echo("✓ warp")
+        else:
+            typer.echo("✗ warp - Run: lf meta install")
+            all_ok = False
+
+    if not ide or ide.cursor:
+        if shutil.which("cursor"):
+            typer.echo("✓ cursor")
+        else:
+            typer.echo("✗ cursor - Run: lf meta install")
+            all_ok = False
+
+    # Optional: gh for PR creation
+    if shutil.which("gh"):
+        typer.echo("✓ gh (optional)")
+    else:
+        typer.echo("- gh (optional): brew install gh")
+
+    raise typer.Exit(0 if all_ok else 1)