lemming-cli 0.1.0__tar.gz

lemming_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.14'
+
+      - name: Install Python dependencies
+        run: uv sync
+
+      - name: Run Python linting
+        run: uv run ruff check .
+
+      - name: Run Python formatting check
+        run: uv run ruff format --check .
+
+      - name: Run Python tests
+        run: uv run pytest
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+
+      - name: Install Node.js dependencies
+        run: npm install
+
+      - name: Run Web linting
+        run: npm run lint
+
+      - name: Run Web check
+        run: npm run check
+
+      - name: Run Web tests
+        run: |
+          npx playwright install --with-deps
+          npm test
+
+      - name: Build container image
+        run: docker build -t lemming:ci .

lemming_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.14'
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

lemming_cli-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+.pytest_cache/
+.coverage
+dist/
+build/
+*.egg-info/
+tasks.yml
+*.swp
+node_modules/
+.biome/
+.lemming_loop.lock
+test-results/
+*tasks*.lock
+.ruff_cache/

lemming_cli-0.1.0/.prettierignore

@@ -0,0 +1,5 @@
+.venv
+node_modules
+dist
+src/lemming/web/mancha.js
+test-results

lemming_cli-0.1.0/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "printWidth": 80,
+  "proseWrap": "always",
+  "singleQuote": true,
+  "trailingComma": "all"
+}

lemming_cli-0.1.0/Dockerfile

@@ -0,0 +1,32 @@
+FROM python:3.14-slim
+
+# Install common dev tools
+RUN apt-get update && apt-get install -y \
+    git curl wget jq make gcc g++ openssh-client procps \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js (LTS) and npm
+RUN curl -fsSL https://deb.nodesource.com/setup_24.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install AI coding CLIs (antigravity ships a native binary, not an npm package)
+RUN npm install -g @openai/codex @anthropic-ai/claude-code \
+    && curl -fsSL https://antigravity.google/cli/install.sh | bash -s -- --dir /usr/local/bin
+
+# Copy cloudflared and uv binaries directly from their official images
+COPY --from=cloudflare/cloudflared:latest /usr/local/bin/cloudflared /usr/local/bin/cloudflared
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+WORKDIR /opt/lemming
+COPY . .
+RUN uv sync --no-dev --frozen
+
+# Install frontend dependencies and Playwright browsers
+RUN npm install && npx playwright install --with-deps
+
+# Pre-create the lemming home directory so users can bind-mount a .env file into it
+RUN mkdir -p /root/.local/lemming
+
+WORKDIR /workspace
+ENTRYPOINT ["uv", "run", "--project", "/opt/lemming", "lemming", "serve", "--host", "0.0.0.0"]

lemming_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lemming_cli-0.1.0/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: lemming-cli
+Version: 0.1.0
+Summary: An autonomous, iterative task runner for AI coding agents.
+Project-URL: Homepage, https://github.com/owahltinez/lemming
+Project-URL: Repository, https://github.com/owahltinez/lemming
+Author: Lemming Contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,aider,antigravity,automation,claude
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.13.3
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastapi>=0.124.4
+Requires-Dist: markdownify>=0.14.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: readability-cli>=0.4.0
+Requires-Dist: requests>=2.32.3
+Requires-Dist: uvicorn>=0.33.0
+Description-Content-Type: text/markdown
+
+# Lemming 🐹
+
+**The transparent, tool-agnostic orchestrator for autonomous AI coding agents.**
+
+Lemming bridges the gap between high-level project strategy and low-level agent
+execution. Instead of letting an agent wander through your codebase in a single,
+massive context window, Lemming forces a structured, iterative workflow via a
+human-readable `tasks.yml` file.
+
+## Why Lemming?
+
+- **Zero Context Drift**: By breaking projects into discrete tasks, Lemming
+  ensures agents stay focused. They only see the project context, relevant
+  history, and the specific task at hand.
+- **Transparency & Control**: Every decision, technical finding, and progress
+  update is recorded in a human-readable `tasks.yml` file. You can step in,
+  adjust the roadmap, or swap agents at any time.
+- **Tool Agnostic**: Lemming doesn't care which agent you use. It works
+  out-of-the-box with `agy`, `aider`, `claude`, `codex`, or even your own custom
+  scripts.
+- **Resilient Execution**: With built-in heartbeat monitoring, automatic
+  retries, and progress tracking, Lemming handles process crashes and rate
+  limits gracefully.
+- **Human-Agent Collaboration**: Use the CLI or the Web UI to collaborate with
+  your agents in real-time. Mark tasks, edit descriptions, and review progress
+  as they happen.
+
+---
+
+## Installation
+
+Install globally using `uv`:
+
+```bash
+uv tool install git+https://github.com/owahltinez/lemming.git
+```
+
+## Quick Start in 3 Steps
+
+### 1. Scaffold the Roadmap
+
+Initialize your project context and define your goals.
+
+```bash
+# Set project-wide rules (e.g. tech stack, style guides)
+lemming context "Use React, TypeScript, and Tailwind. Follow TDD."
+
+# Add tasks to the queue
+lemming add "Initialize the project with Vite"
+lemming add "Create the Button component"
+lemming add "Implement the authentication flow"
+```
+
+### 2. Review and Refine
+
+See exactly what's pending and what the agent will see.
+
+```bash
+# Show the current roadmap
+lemming status
+```
+
+### 3. Release the Lemming
+
+Start the autonomous loop.
+
+```bash
+# Run using the project's configured agent (defaults to the first
+# supported runner found on PATH: agy, aider, claude, or codex)
+lemming run
+
+# Flags passed after -- are sent directly to the underlying runner
+lemming run -- --model claude-3-5-sonnet
+```
+
+---
+
+## The Web Dashboard
+
+Lemming includes a modern, fast Web UI to monitor your projects.
+
+```bash
+lemming serve
+
+# Or share it remotely via a secure tunnel with token auth
+lemming serve --tunnel cloudflare
+```
+
+- **Real-time Monitoring**: Watch tasks move from pending to in-progress to
+  completed.
+- **Switch Project**: Easily switch between different projects or create new
+  folders directly from the UI.
+- **Browse Files**: Quickly open your workspace in a separate window to inspect
+  files and directory structure alongside the roadmap.
+- **Interactive Controls**: Add tasks, edit context, and manage the execution
+  loop from your browser.
+
+---
+
+## How it Works
+
+Lemming maintains a human-readable `tasks.yml` file containing your project
+context, a queue of tasks, and recorded progress. When you run `lemming run`, it
+loops through each pending task:
+
+1.  **Build a scoped prompt**: Lemming assembles a prompt containing only the
+    project context, a summary of completed tasks and their progress, and the
+    current task description.
+2.  **Invoke the agent**: It launches your chosen agent CLI with that prompt,
+    monitors it with heartbeats, and streams output to a log file.
+3.  **Collect results**: The agent reports back via the Lemming CLI — recording
+    findings with `lemming progress`, then marking the task with
+    `lemming complete` or `lemming fail`. Agents can also schedule new tasks
+    with `lemming add`, breaking down complex work into smaller steps that
+    Lemming will pick up automatically.
+4.  **Retry or advance**: On failure, Lemming retries the task (up to
+    `--retries`) with accumulated progress as context, so the agent learns from
+    previous attempts. On success, it moves to the next task.
+5.  **Orchestration**: After each task, Lemming can run one or more
+    **Orchestrator Hooks** (like the built-in `roadmap` hook) to evaluate the
+    results and adapt the roadmap if needed. Hooks are enabled by default but
+    can be disabled via configuration.
+
+---
+
+## Orchestrator Hooks ⚓️
+
+For longer, multi-stage projects, the initial task list often can't anticipate
+everything. Tasks may fail in ways that retrying won't fix, or completing all
+tasks may not fully achieve the stated goal. **Orchestrator Hooks** address this
+by running custom agents or scripts after each task execution to evaluate
+results and adapt the roadmap.
+
+By default, Lemming runs all available hooks (including the built-in `roadmap`
+hook). You can customize this behavior via the `hooks` subcommand:
+
+```bash
+# Enable or disable hooks for the project
+lemming hooks enable lint
+lemming hooks disable roadmap
+
+# Set the exact list of active hooks
+lemming hooks set roadmap lint
+
+# Reset to default (run all available hooks)
+lemming hooks reset
+```
+
+### Built-in Hooks ⚓️
+
+Lemming comes with several built-in hooks to help manage your project:
+
+- **`roadmap`**: The primary mechanism for autonomous project management. It
+  analyzes the results of the finished task and decides if the remaining roadmap
+  needs to be adjusted (e.g., adding a missing prerequisite, skipping obsolete
+  tasks, or breaking down a broad task).
+- **`readability`**: A code quality hook that reviews changes for adherence to
+  the Google Style Guide and general readability using the
+  [readability](https://github.com/owahltinez/readability) tool (exposed as
+  `lemming readability`). It can record findings as task progress or suggest
+  follow-up refactoring tasks.
+
+### Custom and Global Hooks
+
+You can create your own hooks by adding Markdown files to:
+
+1.  **Project-specific**: `.lemming/hooks/*.md`
+2.  **Global**: `~/.local/lemming/hooks/*.md`
+
+Lemming's built-in hooks can be symlinked to the global directory using
+`lemming hooks install`. This allows you to easily **override** a built-in hook
+by replacing its symlink with a file, or **disable** a global override by
+deleting the symlink.
+
+Hooks follow a specific discovery precedence: **Project > Global > Built-in**.
+See [DOCS/HOOKS.md](docs/HOOKS.md) for more details.
+
+### Managing Hooks and Configuration
+
+Use the `config` and `hooks` commands to manage your project's execution loop:
+
+```bash
+# List all available hooks (built-in and local)
+lemming hooks list
+
+# Install (symlink) built-in hooks to the global directory
+lemming hooks install
+
+# View current project configuration
+lemming config list
+
+# Persist configuration to tasks.yml
+lemming config set runner aider
+lemming hooks set roadmap lint
+```
+
+---
+
+## Command Reference
+
+### Roadmap Management
+
+- **`status [<id>]`**: Roadmap overview or deep-dive into a specific task.
+- **`context [<text>]`**: Set or view project-wide instructions. Supports
+  `-f/--file`.
+- **`add <desc>`**: Append a new task. Supports `--index` and `--runner`.
+- **`edit <id>`**: Modify a task's description, runner, or position.
+- **`delete <id>`**: Remove a task. Supports `--all` and `--completed` for bulk
+  operations.
+- **`progress`**: Manage progress entries and findings for specific tasks.
+  - `list <id>`: List all progress for a task.
+  - `add <id> <finding>`: Record a new technical detail.
+  - `edit <id> <index> <text>`: Modify an existing progress entry.
+  - `delete <id> <index>`: Remove a progress entry.
+- **`config`**: Manage project configuration (runner, retries).
+  - `list`: View current configuration.
+  - `set <key> <value>`: Update a setting.
+- **`hooks`**: Manage orchestrator hooks.
+  - `list`: View available and active hooks.
+  - `install`: Install built-in hooks to the global directory.
+  - `enable <name>...`: Activate one or more hooks.
+  - `disable <name>...`: Deactivate one or more hooks.
+  - `set <name>...`: Set the exact list of active hooks.
+  - `reset`: Restore default hooks (run all available).
+- **`readability`**: Code quality tool for style guide adherence, wrapping the
+  [readability](https://github.com/owahltinez/readability) package. Ruff and
+  Pyrefly run with bundled Google-style defaults unless the target project
+  defines its own configuration.
+  - `check <paths>...`: Run formatters and linters.
+  - `guide <language>`: Fetch and view style guides.
+  - `languages`: List all supported languages.
+  - `sync`: Synchronize style guides from the web.
+
+### Task Status
+
+- **`complete <id>`**: Mark a task as successful.
+- **`fail <id>`**: Mark a task as a terminal failure (will not be retried).
+- **`cancel <id>`**: Stop an in-progress task (kills the runner process).
+- **`reset <id>`**: Clear attempts and progress to start a task fresh.
+- **`logs [<id>]`**: Print a task's execution log to stdout. If no ID is
+  provided, it defaults to the active or most recent task. Orchestrator hook
+  output is automatically appended.
+
+### Execution
+
+- **`run`**: Start the autonomous orchestrator loop.
+  - `--retry-delay`: Seconds to wait before retries (default 10).
+  - `--yolo`: Run the runner in auto-approve mode (default: True).
+  - `--env`: Set environment variables for the runner (e.g., `--env KEY=VALUE`).
+  - `--no-defaults`: Skip default flag injection for known runners.
+  - `--`: Use `--` to pass any flag directly to the underlying runner.
+- **`serve`**: Launch the interactive Web UI.
+  - `--port`: The port to bind the server to (default: 8999).
+  - `--host`: The host address to bind the server to (default: 127.0.0.1).
+  - `--tunnel cloudflare|tailscale`: Expose the UI to the public internet via a
+    secure tunnel.
+  - `--timeout`: Auto-shutdown after a duration (e.g., `8h`, `30m`). Defaults to
+    `8h` with `--tunnel`, disabled otherwise.
+
+---
+
+## Advanced: Runner Customization
+
+Lemming uses **fuzzy matching** to automatically inject the correct "YOLO"
+(auto-approve) and "Quiet" flags for popular tools:
+
+- **Antigravity (`agy`)**: Adds `--dangerously-skip-permissions`
+- **Aider**: Adds `--yes --quiet`
+- **Claude**: Adds `--dangerously-skip-permissions`
+- **Codex**: Adds `--yolo`
+
+You can disable this behavior with `--no-defaults`, or use a **template** to
+fully control the command layout:
+
+```bash
+lemming run --runner "my-tool --input={{prompt}} --json"
+```
+
+When `{{prompt}}` is present in the runner string, Lemming replaces it with the
+prompt text and skips all default flag injection.
+
+---
+
+## Screenshots
+
+### Dashboard
+
+![Dashboard](docs/screenshots/dashboard-desktop.png)
+
+### Task Log
+
+![Task Log](docs/screenshots/task-log-desktop.png)