lemming-cli 0.4.0__tar.gz → 0.4.2__tar.gz

lemming_cli-0.4.2/.dockerignore

@@ -0,0 +1,30 @@
+# The image builds its own environments, so host-built ones are not just
+# wasted bytes in the context — they are the wrong platform's binaries
+# landing on top of what `uv sync` and `npm install` are about to create.
+.venv
+node_modules
+
+# History and build products the image never reads.
+.git
+.github
+dist
+test-results
+docs/screenshots
+
+# Agent worktrees are whole checkouts of this repo, each with its own
+# dependencies installed, and they dwarf the source they sit beside.
+.claude
+
+# Local state and caches.
+.pytest_cache
+.ruff_cache
+__pycache__
+*.pyc
+.DS_Store
+
+# Roadmaps and their locks belong to whoever is running lemming, not to
+# the image; a stale one baked in would be read as that project's state.
+tasks.yml
+*.lock
+!uv.lock
+!package-lock.json

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
           python-version: '3.14'
 
       - name: Install Python dependencies
-        run: uv sync
+        run: uv sync --locked
 
       - name: Run Python linting
         run: uv run ruff check .

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/Dockerfile

@@ -22,8 +22,14 @@ WORKDIR /opt/lemming
 COPY . .
 RUN uv sync --no-dev --frozen
 
-# Install frontend dependencies and Playwright browsers
-RUN npm install && npx playwright install --with-deps
+# Frontend dependencies are always needed: postinstall vendors mancha into
+# the web assets. The browsers are not, and they are more than half the
+# image, so anything that will never drive one builds without them.
+ARG INSTALL_BROWSERS=true
+RUN npm install \
+    && if [ "$INSTALL_BROWSERS" = "true" ]; then \
+         npx playwright install --with-deps; \
+       fi
 
 # Pre-create the lemming home directory so users can bind-mount a .env file into it
 RUN mkdir -p /root/.local/lemming

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lemming-cli
-Version: 0.4.0
+Version: 0.4.2
 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
@@ -140,7 +140,10 @@ removed unless it failed — in which case it is kept, and its path printed, so
 the log can be read. Kept directories live in `~/.local/lemming/exec-*` and
 are retired automatically a week later, so a recent failure is always still
 there to inspect. Stdout carries the agent's message alone and everything
-else goes to stderr, so the output can be consumed directly.
+else goes to stderr, so the output can be consumed directly. Stderr reports
+the ephemeral tasks file and task ID at startup; pass those to `lemming
+--tasks-file <path> status <id>` or `logs <id>` to inspect an active run. Use
+the global verbose flag (`lemming -v exec ...`) to stream runner activity.
 
 Note that the agent runs unattended (`--yolo` by default), so it does not
 inherit the permission prompts of whatever launched it.
@@ -395,8 +398,9 @@ These come before the subcommand and apply to all of them.
     per-task `--runner`/`--model` overrides anything passed here.
 - **`exec [<description>]`**: Run one task, or one set of reviews, outside any
   roadmap. Prints the agent's closing message to stdout and everything else to
-  stderr. Exits non-zero if the task did not complete. See
-  [One-off tasks](#one-off-tasks-without-a-roadmap).
+  stderr, including its tasks file and task ID at startup. Use `lemming -v
+  exec ...` to stream runner activity. Exits non-zero if the task did not
+  complete. See [One-off tasks](#one-off-tasks-without-a-roadmap).
   - `-f/--file`: Read the description from a file, or `-` for stdin. Unlike
     `add`, there is no length cap.
   - `--review <names>`: Reviews to run after the task, comma-separated or
@@ -533,10 +537,16 @@ 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
+# 1. Bump pyproject.toml and uv.lock together, commit, and push
+uv version --bump patch --no-sync
+version="$(uv version --short)"
+git add pyproject.toml uv.lock
+git commit -m "Bump version to $version"
+git push origin main
+
+# 2. After CI passes, tag the release and push the tag
+git tag "v$version"
+git push origin "v$version"
 ```
 
 ---

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/README.md

@@ -118,7 +118,10 @@ removed unless it failed — in which case it is kept, and its path printed, so
 the log can be read. Kept directories live in `~/.local/lemming/exec-*` and
 are retired automatically a week later, so a recent failure is always still
 there to inspect. Stdout carries the agent's message alone and everything
-else goes to stderr, so the output can be consumed directly.
+else goes to stderr, so the output can be consumed directly. Stderr reports
+the ephemeral tasks file and task ID at startup; pass those to `lemming
+--tasks-file <path> status <id>` or `logs <id>` to inspect an active run. Use
+the global verbose flag (`lemming -v exec ...`) to stream runner activity.
 
 Note that the agent runs unattended (`--yolo` by default), so it does not
 inherit the permission prompts of whatever launched it.
@@ -373,8 +376,9 @@ These come before the subcommand and apply to all of them.
     per-task `--runner`/`--model` overrides anything passed here.
 - **`exec [<description>]`**: Run one task, or one set of reviews, outside any
   roadmap. Prints the agent's closing message to stdout and everything else to
-  stderr. Exits non-zero if the task did not complete. See
-  [One-off tasks](#one-off-tasks-without-a-roadmap).
+  stderr, including its tasks file and task ID at startup. Use `lemming -v
+  exec ...` to stream runner activity. Exits non-zero if the task did not
+  complete. See [One-off tasks](#one-off-tasks-without-a-roadmap).
   - `-f/--file`: Read the description from a file, or `-` for stdin. Unlike
     `add`, there is no length cap.
   - `--review <names>`: Reviews to run after the task, comma-separated or
@@ -511,10 +515,16 @@ 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
+# 1. Bump pyproject.toml and uv.lock together, commit, and push
+uv version --bump patch --no-sync
+version="$(uv version --short)"
+git add pyproject.toml uv.lock
+git commit -m "Bump version to $version"
+git push origin main
+
+# 2. After CI passes, tag the release and push the tag
+git tag "v$version"
+git push origin "v$version"
 ```
 
 ---

lemming_cli-0.4.2/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: lemming
+description: One interface over the AI coding agent CLIs (agy, claude, codex). Delegate a single task to another agent to spare a quota or play to its strengths; run a readability, testing, or UX review over changed files, a branch, or a path; or drive a multi-task project through a roadmap that survives context limits. Use whenever work should run under a different agent than the current one, when reviewing a diff before opening a pull request, or when a job is too large for one agent run.
+license: MIT
+---
+
+# lemming
+
+One interface over several agent CLIs. You do not need to know how `agy`,
+`claude`, or `codex` spell their flags — only `lemming`.
+
+Use `exec` for one unit of work, and a roadmap for anything larger than a
+single agent run can hold.
+
+## Delegate one task
+
+```sh
+lemming -v exec "Fix the flaky heartbeat test in src/runner_test.py" --runner codex
+
+# Pipe a longer handoff rather than fighting shell quoting; no length limit
+cat handoff.md | lemming -v exec -f - --runner agy
+```
+
+The agent's closing message comes back on **stdout**, everything else on
+stderr, and the exit code is 0 only if the task completed. Read that message
+instead of hunting through logs.
+
+When you launch `exec` as a subprocess, use the global `-v` flag (before
+`exec`) and continue monitoring its output until it exits. Verbose mode streams
+the runner's activity on stderr. At startup, stderr also reports the exact
+`Tasks file` and `Task ID`; use them from another process to inspect the
+agent's durable findings or full log without guessing which `exec-*` directory
+belongs to the run:
+
+```sh
+lemming --tasks-file <reported-path> status <reported-task-id>
+lemming --tasks-file <reported-path> logs <reported-task-id>
+```
+
+The task runner is required to record its approach first and concise findings
+as it works. These entries are checkpoints rather than a continuous trace, so
+use verbose output or the log to tell whether it is actively making progress.
+
+The task starts with an empty context and sees nothing of your conversation,
+so give it everything it needs.
+
+## Run a review
+
+With no description there is nothing for a task runner to do, so only the
+reviews run — against work that already exists.
+
+```sh
+lemming exec --review readability            # uncommitted work
+lemming exec --review testing --scope main...HEAD
+lemming exec --review all --scope src/api/
+lemming exec "Add pagination" --review all   # do the work, then gate it
+
+# Someone else's branch, in a worktree so your own tree is untouched
+git worktree add /tmp/pr-123 && (cd /tmp/pr-123 && gh pr checkout 123)
+lemming -C /tmp/pr-123 exec --review testing --scope main...HEAD
+```
+
+`--scope` takes paths, which pass through untouched, or a git revision range,
+which is resolved to the files it changed. It defaults to uncommitted work,
+and a clean tree stops the run rather than reviewing everything.
+
+Reviews **edit the workspace** — readability applies fixes and reruns checks.
+That is the point, but it means a review is not read-only.
+
+## Drive a roadmap
+
+For work that outlasts one agent run — a migration, a multi-step feature —
+break it into tasks. Each runs with a fresh context seeded only by the goal
+and recorded progress, so the project survives context limits.
+
+```sh
+lemming goal "Add offline support with a service worker and a sync queue"
+lemming add "Register the service worker and cache the app shell"
+lemming add "Queue writes in IndexedDB while offline"
+lemming run                                  # runs until the queue drains
+```
+
+Check on it, and read what an agent actually did:
+
+```sh
+lemming status              # queue, attempts, and recorded progress
+lemming status <id>         # one task in detail, including its runner command
+lemming logs                # the active task's log, or logs <id> for one task
+```
+
+Adjust it while it runs — new tasks are picked up automatically:
+
+```sh
+lemming add "Add a retry backoff to the sync queue" --index 0  # jump the queue
+lemming stop --after-current-task                             # drain, then stop
+```
+
+After each task, review hooks run automatically and a roadmap hook may revise
+the queue. `lemming hooks list` shows them; `lemming hooks disable <name>`
+turns one off for the project.
+
+## What to know before running any of it
+
+- **The agent runs unattended.** `--yolo` is the default, so it does not
+  inherit the permission prompts of whatever launched it. Treat this as
+  granting an agent unsupervised write access to the working directory.
+- **`exec` makes one attempt, no retry.** A failure is final. A roadmap task
+  retries (3 by default) with its progress carried forward.
+- **Interrupting leaves partial edits.** Nothing is restored, so there is no
+  atomicity to rely on.
+- **Concurrent runs in one checkout interleave their edits.** Give each
+  writing run its own worktree and address it with `-C`.
+- **Every run reports its state.** The tasks file and task ID are printed on
+  stderr at startup. Successful state is removed on exit unless `--keep` is
+  used; failures keep their directory and print it again for recovery. Kept
+  failure state is retired automatically after a week.
+- **`--tasks-file` and `-C` are group options.** They go before the
+  subcommand — `lemming -C ../other exec ...`, never `exec -C ../other`.
+
+`lemming --help`, or `--help` on any subcommand, has the full flag list.

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lemming-cli"
-version = "0.4.0"
+version = "0.4.2"
 description = "An autonomous, iterative task runner for AI coding agents."
 readme = "README.md"
 authors = [

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/src/lemming/cli/exec_cli.py

@@ -324,6 +324,12 @@ def exec_command(
         else _create_review_task(exec_dir, reviews, config)
     )
 
+    # A supervising process needs an exact, race-free handle to the ephemeral
+    # roadmap while the run is active. Keep it on stderr so stdout remains the
+    # agent's closing-message interface.
+    click.echo(f"Tasks file: {tasks_file}", err=True)
+    click.echo(f"Task ID: {task_id}", err=True)
+
     shutdown.clear_drain()
     shutdown.install_handlers()
 

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/src/lemming/cli/exec_cli_test.py

@@ -80,6 +80,24 @@ def test_exec_keeps_progress_chatter_off_stdout(workspace):
     assert "Attempt" in result.stderr
 
 
+def test_exec_announces_monitoring_coordinates_on_stderr(workspace):
+    """A supervisor can inspect an active exec without guessing its state."""
+    seen = {}
+
+    def finish(cmd, tasks_file, task_id, *args, **kwargs):
+        seen["tasks_file"] = tasks_file
+        seen["task_id"] = task_id
+        return _finish("Done.")(cmd, tasks_file, task_id, *args, **kwargs)
+
+    with mock.patch("lemming.runner.run_with_heartbeat", finish):
+        result = CliRunner().invoke(cli, ["exec", "Fix the flaky test"])
+
+    assert result.exit_code == 0, result.stderr
+    assert result.stdout.strip() == "Done."
+    assert f"Tasks file: {seen['tasks_file']}" in result.stderr
+    assert f"Task ID: {seen['task_id']}" in result.stderr
+
+
 def test_exec_removes_its_state_directory_on_success(workspace):
     """A one-shot leaves nothing behind when it worked."""
     with mock.patch("lemming.runner.run_with_heartbeat", _finish("Done.")):

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/src/lemming/evals/cli.py

@@ -178,6 +178,10 @@ def run(
             )
         click.echo(f"Building eval image '{image}'...")
         container.build_image(context, image=image, docker=docker)
+        # The image is what the trials need; the cache that produced it is
+        # dead weight, and it outgrows the image several times over across
+        # repeated runs.
+        container.prune_build_cache(docker=docker)
 
     if run_dir is None:
         run_dir = pathlib.Path(tempfile.mkdtemp(prefix="lemming-evals-"))

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/src/lemming/evals/container.py

@@ -41,7 +41,41 @@ def build_image(
         image: Tag for the built image.
         docker: Docker-compatible CLI binary to invoke.
     """
-    subprocess.run([docker, "build", "--tag", image, str(context)], check=True)
+    # No scenario drives a browser, and they are more than half the image.
+    subprocess.run(
+        [
+            docker,
+            "build",
+            "--build-arg",
+            "INSTALL_BROWSERS=false",
+            "--tag",
+            image,
+            str(context),
+        ],
+        check=True,
+    )
+
+
+def prune_build_cache(docker: str = "docker") -> None:
+    """Discards the build cache left behind by an eval image build.
+
+    Cache accumulates faster than images do — a run rebuilding this image a
+    few times leaves tens of gigabytes behind — and nothing reuses it once
+    the trials have finished.
+
+    Args:
+        docker: Docker-compatible CLI binary to invoke.
+    """
+    try:
+        subprocess.run(
+            [docker, "builder", "prune", "--force", "--all"],
+            check=False,
+            capture_output=True,
+        )
+    except OSError:
+        # This runs after the results are in; failing to tidy up must never
+        # be the reason a completed eval run reports an error.
+        pass
 
 
 def trial_command(

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/src/lemming/evals/container_test.py

@@ -84,3 +84,34 @@ class TestRunTrial(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class BuildImageTest(unittest.TestCase):
+    """The build must not carry what the eval trials never use."""
+
+    @unittest.mock.patch("subprocess.run")
+    def test_builds_without_browsers(
+        self, run: unittest.mock.MagicMock
+    ) -> None:
+        """Browsers are over half the image and no trial drives one."""
+        container.build_image(pathlib.Path("/repo"))
+
+        argv = run.call_args[0][0]
+        self.assertIn("--build-arg", argv)
+        self.assertIn("INSTALL_BROWSERS=false", argv)
+
+    @unittest.mock.patch("subprocess.run")
+    def test_prunes_the_build_cache(self, run: unittest.mock.MagicMock) -> None:
+        """Repeated eval runs accumulate cache faster than images."""
+        container.prune_build_cache()
+
+        argv = run.call_args[0][0]
+        self.assertEqual(argv[:3], ["docker", "builder", "prune"])
+        self.assertIn("--force", argv)
+
+    @unittest.mock.patch("subprocess.run", side_effect=OSError("no docker"))
+    def test_pruning_never_fails_a_run(
+        self, run: unittest.mock.MagicMock
+    ) -> None:
+        """Cleanup runs after the results are in; it must not lose them."""
+        container.prune_build_cache()

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/src/lemming/runner.py

@@ -29,6 +29,10 @@ KILL_GRACE_SECONDS = 5
 # inherit the pipe and hold it open indefinitely.
 OUTPUT_DRAIN_SECONDS = 5
 
+# Headroom between the task time limit and a runner's own print-mode timeout,
+# so the two never race to end the same run.
+PRINT_TIMEOUT_GRACE_MINUTES = 5
+
 
 def _pretty_quote(s: str) -> str:
     """Quotes a string for shell execution, preferring readable quoting.
@@ -234,9 +238,16 @@ def build_runner_command(
             # payload, with none of claude's top-level "type".
             cmd.extend(["--output-format", "stream-json"])
 
-            # agy caps print mode at 5 minutes by default; extend it to the
-            # task time limit (or effectively unlimited when there is none).
-            print_timeout = f"{time_limit}m" if time_limit > 0 else "24h"
+            # agy caps print mode at 5 minutes by default; extend it past the
+            # task time limit (or make it effectively unlimited when there is
+            # none). The headroom leaves Lemming's own kill to end an
+            # overrunning task, which records why it stopped; agy's expiry
+            # reports an empty response instead, losing the run's outcome.
+            print_timeout = (
+                f"{time_limit + PRINT_TIMEOUT_GRACE_MINUTES}m"
+                if time_limit > 0
+                else "24h"
+            )
             cmd.extend(["--print-timeout", print_timeout])
 
             prompt_arg = "--prompt"

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/src/lemming/runner_test.py

@@ -48,11 +48,13 @@ def test_build_runner_command_agy_streams_json_events():
     assert "--log-file" not in cmd
 
 
-def test_build_runner_command_agy_print_timeout_matches_time_limit():
+def test_build_runner_command_agy_print_timeout_clears_time_limit():
+    # The runner's own timeout must not race Lemming's kill: Lemming records
+    # why it stopped the task, whereas agy's expiry yields an empty response.
     cmd = runner.build_runner_command(
         "agy", "my prompt", yolo=True, time_limit=45
     )
-    assert cmd[cmd.index("--print-timeout") + 1] == "45m"
+    assert cmd[cmd.index("--print-timeout") + 1] == "50m"
 
 
 def test_build_runner_command_agy_print_timeout_without_time_limit():

{lemming_cli-0.4.0 → lemming_cli-0.4.2}/uv.lock

@@ -222,7 +222,7 @@ wheels = [
 
 [[package]]
 name = "lemming-cli"
-version = "0.3.4"
+version = "0.4.2"
 source = { editable = "." }
 dependencies = [
     { name = "beautifulsoup4" },

lemming_cli-0.4.0/SKILL.md

@@ -1,86 +0,0 @@
----
-name: lemming
-description: Delegate a single coding task to another AI agent CLI (agy, claude, codex) through one interface, or run a code review — readability, testing, UX — over changed files, a PR branch, or a path. Use when handing work to a different agent to spare a quota or play to its strengths, or when reviewing a diff before opening a pull request. Not for driving a multi-task project; that is a roadmap.
-license: MIT
----
-
-# lemming
-
-One interface over several agent CLIs. You do not need to know how `agy`,
-`claude`, or `codex` spell their flags — only `lemming exec`.
-
-## Delegate one task
-
-```sh
-lemming exec "Fix the flaky heartbeat test in src/runner_test.py" --runner codex
-```
-
-The agent's closing message comes back on **stdout**; progress and the event
-trace go to stderr. Exit code is 0 only if the task completed. That message is
-the return value — read it instead of hunting through logs.
-
-Pipe a longer handoff rather than fighting shell quoting. There is no length
-limit, unlike a roadmap task description:
-
-```sh
-cat handoff.md | lemming exec -f - --runner agy
-```
-
-Delegate when another agent's quota, price, or strengths suit the work better
-than yours. Give the task everything it needs: it starts with an empty context
-and sees nothing of your conversation.
-
-## Run a review
-
-With no description there is nothing for a task runner to do, so only the
-reviews run — against work that already exists.
-
-```sh
-lemming exec --review readability          # uncommitted work
-lemming exec --review testing --scope main...HEAD
-lemming exec --review all --scope src/api/
-lemming exec "Add pagination" --review all # do the work, then gate it
-```
-
-`--scope` takes paths, which pass through untouched, or a git revision range,
-which is resolved to the files it changed. It defaults to uncommitted work.
-A clean tree stops the run rather than reviewing everything.
-
-Reviews **edit the workspace**: readability applies fixes and reruns checks.
-That is the point — but it means a review is not read-only.
-
-## Reviewing someone else's branch
-
-Check it out in a worktree so your own tree is untouched, and point `-C` at it:
-
-```sh
-git worktree add /tmp/pr-123 && (cd /tmp/pr-123 && gh pr checkout 123)
-lemming -C /tmp/pr-123 exec --review testing --scope main...HEAD
-```
-
-## What to know before running it
-
-- **The agent runs unattended.** `--yolo` is the default, so it does not
-  inherit the permission prompts of whatever launched it. Treat `lemming exec`
-  as granting an agent unsupervised write access to the working directory.
-- **One agent run, no retry.** A failure is final; it does not silently try
-  again. `--time-limit` caps the wall clock (default 60 minutes).
-- **Interrupting leaves partial edits.** The workspace is not restored, so
-  there is no atomicity to rely on.
-- **Failures keep their log.** The state directory path is printed on stderr;
-  read it with `lemming logs` pointed at that tasks file.
-
-## Running several at once
-
-Concurrent runs in one checkout will interleave their edits. Give each write
-task its own worktree and address it with `-C`. Read-only work parallelizes
-safely as-is.
-
-## When not to use it
-
-`exec` is for one unit of work. Anything needing more context than a single
-agent run can hold — a migration across a large codebase, a multi-step feature
-— belongs on a roadmap: `lemming add`, then `lemming run`. In particular,
-`--scope .` over a large repository *samples*; it does not cover.
-
-Run `lemming exec --help` for the full flag list.