Metadata-Version: 2.4
Name: lemming-cli
Version: 0.3.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.5.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 long-term goal, 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 lemming-cli
```

## Quick Start in 3 Steps

### 1. Scaffold the Roadmap

Set the long-term goal and define the first tasks.

```bash
# Set the long-term goal that every task works toward
lemming goal "Build a habit-tracking web app with auth, offline support, and tests"

# Add tasks to the queue
lemming add "Initialize the project with Vite"
lemming add "Create the Button component"
lemming add "Implement the authentication flow"
```

The goal is the one piece of state every task sees, no matter how far into the
roadmap it runs — describe what "done" looks like for the project. Durable
coding rules (tech stack, style guides) belong in your repo's agent files (e.g.
`AGENTS.md`, `CLAUDE.md`), which your agent already reads on its own.

### 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 the goal, and manage the execution
  loop from your browser.

---

## How it Works

Lemming maintains a human-readable `tasks.yml` file containing your long-term
goal, 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
    long-term goal, 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.

Lemming runs every hook it discovers on the filesystem (including the
built-in `roadmap` hook). Hooks are plain Markdown files, and udev-style
filename conventions control their behavior:

- **Ordering**: A numeric prefix sets the execution order (e.g.
  `10-lint.md` runs before `90-roadmap.md`); files without a prefix
  default to priority 50.
- **Failure hooks**: Hooks at priority 90 and above also run when a task
  fails; all others only run on success.
- **Disabling**: An empty file masks (disables) the hook of the same name
  from a lower-precedence layer.

```bash
# Disable a hook for this project (writes an empty .lemming/hooks/50-lint.md)
lemming hooks disable lint

# Re-enable it (removes the mask file)
lemming hooks enable lint
```

### 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 and simplification hook that challenges
  unnecessary complexity and duplicate implementations, then 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.
- **`testing`**: Verifies that changed behavior has focused test coverage and
  that the relevant tests pass.
- **`ux`**: Reviews at most one critical user journey affected by a
  user-visible change. It reports only concrete, reproducible continuity gaps
  and exits immediately for non-user-facing 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`

To **override** a built-in hook, create a file with the same logical name
(the numeric prefix is not part of the name, so `20-roadmap.md` overrides
the built-in `90-roadmap.md` and also moves it to priority 20); delete the
file to restore the built-in version.

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 hooks in execution order, with source and status
lemming hooks list

# View current project configuration (includes the active hooks)
lemming config list

# Persist configuration to tasks.yml
lemming config set runner aider
```

### Evaluating Prompt Changes

Editing a hook prompt can regress behavior without any test failing. The
containerized eval harness replays realistic scenarios against the real hook
execution path and grades the outcome mechanically:

```bash
uv run python -m lemming.evals run --suite roadmap
```

See [docs/EVALS.md](docs/EVALS.md) for details.

---

## Command Reference

### Roadmap Management

- **`status [<id>]`**: Queue/history overview or deep-dive into a specific
  task, including supersession lineage and runner/orchestrator-hook execution
  times. Superseded and failed history stays visible in the default overview;
  `--verbose` also shows routine completed/cancelled history.
- **`goal [<text>]`**: Set or view the long-term goal shared by all tasks.
  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 an unstarted task while retaining its runner log.
  Tasks with execution history require `--force`; autonomous restructuring
  should use `supersede`. Supports `--all` and `--completed` for bulk cleanup,
  including logs.
- **`supersede <id> --reason <text>`**: Retire a replaced or split task without
  losing its progress, timings, log, or links to replacement tasks.
- **`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.
- Superseded tasks remain visible as non-failing history; replacement tasks
  link back through their parent task ID.
- **`logs [<id>]`**: Print a task's execution log to stdout, including retained
  logs for removed tasks. 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**: Runs non-interactively via `codex exec`, adds `--json`, and, in
  YOLO mode, adds `--dangerously-bypass-approvals-and-sandbox`

You can disable default flag injection with `--no-defaults` (`codex exec`
remains the Codex execution interface), 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.

---

## Releasing

Releases are published to PyPI as
[`lemming-cli`](https://pypi.org/project/lemming-cli/) via trusted publishing:
pushing a `v*` tag triggers the `publish.yml` GitHub Actions workflow, which
builds the package with `uv build` and uploads it.

```bash
# 1. Bump the version in pyproject.toml, commit, and push
# 2. Tag the release and push the tag
git tag v0.1.1
git push origin v0.1.1
```

---

## Screenshots

These are regenerated automatically by CI whenever the web UI changes (see
`.github/workflows/screenshots.yml`); run `npm run screenshots` to preview them
locally.

### Dashboard

![Dashboard](docs/screenshots/dashboard-desktop.png)

### Task Log

![Task Log](docs/screenshots/task-log-desktop.png)
