lemming-cli 0.4.6__tar.gz → 0.5.0__tar.gz

{lemming_cli-0.4.6 → lemming_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lemming-cli
-Version: 0.4.6
+Version: 0.5.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
@@ -10,6 +10,7 @@ License-File: LICENSE
 Keywords: agents,ai,antigravity,automation,claude,opencode
 Requires-Python: >=3.12
 Requires-Dist: beautifulsoup4>=4.13.3
+Requires-Dist: click-agentcli>=0.3.0
 Requires-Dist: click>=8.0.0
 Requires-Dist: fastapi>=0.124.4
 Requires-Dist: markdownify>=0.14.1
@@ -112,10 +113,19 @@ runner, and the agent's closing message comes back on stdout.
 # Delegate one task to a different agent, e.g. to spare another's quota
 lemming exec "Fix the flaky test in runner_test.py" --runner codex
 
+# Allow up to three total attempts for transient runner failures
+lemming exec "Fix the flaky test in runner_test.py" --retries 3
+
 # Pipe a longer handoff instead of fighting shell quoting
-cat handoff.md | lemming exec -f - --runner agy
+cat handoff.md | lemming -v exec -f - --runner agy
 ```
 
+The runner receives no conversation history and cannot be steered mid-run.
+Make the handoff self-contained: state the goal, hard constraints, relevant
+findings and evidence, approaches ruled out and why, and the definition of done
+and verification. The installed skill includes a complete here-document
+example for orchestrating agents.
+
 With no description there is nothing for a task runner to do, so only the
 reviews run — against work that already exists.
 
@@ -124,7 +134,7 @@ reviews run — against work that already exists.
 lemming exec --review readability
 
 # Review someone else's branch, checked out in a worktree
-lemming exec -C ../review-worktree --review testing --scope main...HEAD
+lemming -C ../review-worktree exec --review testing --scope main...HEAD
 
 # Do the work, then gate it
 lemming exec "Add pagination to the tasks API" --review all
@@ -135,13 +145,14 @@ which is resolved to the files it changed. It defaults to uncommitted work, or
 to the whole tree outside a git repository.
 
 Each run is self-contained: nothing is read from the project's roadmap or its
-local hooks, one agent run is attempted, and the run's state directory is
-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. Stderr reports the ephemeral
-tasks file and task ID at startup; pass those to
+local hooks, it runs only the requested task and reviews, and its state
+directory is 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. 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.
@@ -149,25 +160,40 @@ activity.
 Note that the agent runs unattended (`--yolo` by default), so it does not
 inherit the permission prompts of whatever launched it.
 
+`--retries N` includes the first attempt and defaults to 1. Retries reuse the
+same task state and progress after incomplete runs, timeouts, launch errors, or
+non-zero exits. An explicit failure or cancellation, an interruption, or a
+failed review stops immediately. Review-only runs cannot be retried.
+
+Concurrent writing runs must not share a checkout. Lemming stays independent of
+Git, Mercurial, and other version control systems: the caller creates a separate
+working copy with the repository's existing VCS, passes it with
+`lemming -C <working-copy> -v exec ...`, and owns result recovery and cleanup.
+For Git, stop when the source checkout has modified or untracked files instead
+of silently excluding them. Retain every isolated working copy until its changes
+have been recovered. The packaged skill includes a minimal Git example.
+
 ### Teaching Your Agent to Use It
 
 Lemming ships an Agent Skill so that an agent already running — Codex, Claude
 Code, Gemini CLI, Cursor — can reach any other agent CLI without knowing how
-each one spells its flags. Install it once:
+each one spells its flags. Install or refresh it with:
 
 ```bash
-# Cross-tool location (~/.agents/skills), and report any tool-specific ones
+# Cross-tool location plus every detected tool-specific location
 lemming skill install
 
-# Cover detected tools that require their own skill directory too
-lemming skill install --all
-
 # This repository only
 lemming skill install --to .agents/skills
+
+# Inspect every supported location
+lemming skill status
 ```
 
-`lemming skill uninstall` reverses it. Both refuse to touch a directory that
-does not hold this skill, so a mistyped `--to` fails instead of deleting work.
+`lemming skill uninstall` reverses the default installation sweep. Both refuse
+to touch a directory that does not hold this skill, so a mistyped `--to` fails
+instead of deleting work. Use `--link` on a durable installation to track
+package upgrades without reinstalling.
 
 ---
 
@@ -209,9 +235,9 @@ loops through each pending task:
     `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.
+4.  **Retry or advance**: On failure, Lemming retries the task up to the
+    configured roadmap limit, 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
@@ -411,19 +437,21 @@ These come before the subcommand and apply to all of them.
     revision range is resolved to the files it changed. Defaults to uncommitted
     work, or the whole tree outside a repository.
   - `--runner`, `--model`: Which agent CLI and model to use.
+  - `--retries`: Maximum total task-runner attempts, including the first
+    (default 1). Does not retry review-only runs.
   - `--time-limit`: Minutes before the agent is killed (default 60, 0 for no
     limit).
   - `--yolo/--no-yolo`: Run the agent unattended (default: True).
   - `--keep`: Keep the run's state directory even when it succeeds.
 - **`skill install`**: Install the packaged Agent Skill so agents discover
-  Lemming. Writes to `~/.agents/skills` by default and names any tool-specific
-  directories it found.
+  Lemming. Writes to `~/.agents/skills` and every detected tool-specific
+  directory by default. Re-running it refreshes existing Lemming copies.
   - `--to <dir>`: Install into a specific skills directory.
-  - `--all`: Also cover every detected tool's own skills directory.
   - `--link`: Symlink instead of copying, so upgrades take effect immediately.
-  - `--force`: Replace an existing installation of this skill.
   - `--dry-run`: Print what would happen, refusals included.
-- **`skill uninstall`**: Remove it again. Same `--to`, `--all`, and `--dry-run`.
+- **`skill uninstall`**: Remove it again. Supports `--to` and `--dry-run`.
+- **`skill status`**: Show every supported location and installation state.
+  Supports `--json` for structured output.
 - **`stop`**: Stop the running loop and its runner.
   - `--after-current-task`: Drain instead — let the running task finish, then
     stop before claiming another. This is the safe way to change the runner or

{lemming_cli-0.4.6 → lemming_cli-0.5.0}/README.md

@@ -90,10 +90,19 @@ runner, and the agent's closing message comes back on stdout.
 # Delegate one task to a different agent, e.g. to spare another's quota
 lemming exec "Fix the flaky test in runner_test.py" --runner codex
 
+# Allow up to three total attempts for transient runner failures
+lemming exec "Fix the flaky test in runner_test.py" --retries 3
+
 # Pipe a longer handoff instead of fighting shell quoting
-cat handoff.md | lemming exec -f - --runner agy
+cat handoff.md | lemming -v exec -f - --runner agy
 ```
 
+The runner receives no conversation history and cannot be steered mid-run.
+Make the handoff self-contained: state the goal, hard constraints, relevant
+findings and evidence, approaches ruled out and why, and the definition of done
+and verification. The installed skill includes a complete here-document
+example for orchestrating agents.
+
 With no description there is nothing for a task runner to do, so only the
 reviews run — against work that already exists.
 
@@ -102,7 +111,7 @@ reviews run — against work that already exists.
 lemming exec --review readability
 
 # Review someone else's branch, checked out in a worktree
-lemming exec -C ../review-worktree --review testing --scope main...HEAD
+lemming -C ../review-worktree exec --review testing --scope main...HEAD
 
 # Do the work, then gate it
 lemming exec "Add pagination to the tasks API" --review all
@@ -113,13 +122,14 @@ which is resolved to the files it changed. It defaults to uncommitted work, or
 to the whole tree outside a git repository.
 
 Each run is self-contained: nothing is read from the project's roadmap or its
-local hooks, one agent run is attempted, and the run's state directory is
-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. Stderr reports the ephemeral
-tasks file and task ID at startup; pass those to
+local hooks, it runs only the requested task and reviews, and its state
+directory is 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. 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.
@@ -127,25 +137,40 @@ activity.
 Note that the agent runs unattended (`--yolo` by default), so it does not
 inherit the permission prompts of whatever launched it.
 
+`--retries N` includes the first attempt and defaults to 1. Retries reuse the
+same task state and progress after incomplete runs, timeouts, launch errors, or
+non-zero exits. An explicit failure or cancellation, an interruption, or a
+failed review stops immediately. Review-only runs cannot be retried.
+
+Concurrent writing runs must not share a checkout. Lemming stays independent of
+Git, Mercurial, and other version control systems: the caller creates a separate
+working copy with the repository's existing VCS, passes it with
+`lemming -C <working-copy> -v exec ...`, and owns result recovery and cleanup.
+For Git, stop when the source checkout has modified or untracked files instead
+of silently excluding them. Retain every isolated working copy until its changes
+have been recovered. The packaged skill includes a minimal Git example.
+
 ### Teaching Your Agent to Use It
 
 Lemming ships an Agent Skill so that an agent already running — Codex, Claude
 Code, Gemini CLI, Cursor — can reach any other agent CLI without knowing how
-each one spells its flags. Install it once:
+each one spells its flags. Install or refresh it with:
 
 ```bash
-# Cross-tool location (~/.agents/skills), and report any tool-specific ones
+# Cross-tool location plus every detected tool-specific location
 lemming skill install
 
-# Cover detected tools that require their own skill directory too
-lemming skill install --all
-
 # This repository only
 lemming skill install --to .agents/skills
+
+# Inspect every supported location
+lemming skill status
 ```
 
-`lemming skill uninstall` reverses it. Both refuse to touch a directory that
-does not hold this skill, so a mistyped `--to` fails instead of deleting work.
+`lemming skill uninstall` reverses the default installation sweep. Both refuse
+to touch a directory that does not hold this skill, so a mistyped `--to` fails
+instead of deleting work. Use `--link` on a durable installation to track
+package upgrades without reinstalling.
 
 ---
 
@@ -187,9 +212,9 @@ loops through each pending task:
     `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.
+4.  **Retry or advance**: On failure, Lemming retries the task up to the
+    configured roadmap limit, 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
@@ -389,19 +414,21 @@ These come before the subcommand and apply to all of them.
     revision range is resolved to the files it changed. Defaults to uncommitted
     work, or the whole tree outside a repository.
   - `--runner`, `--model`: Which agent CLI and model to use.
+  - `--retries`: Maximum total task-runner attempts, including the first
+    (default 1). Does not retry review-only runs.
   - `--time-limit`: Minutes before the agent is killed (default 60, 0 for no
     limit).
   - `--yolo/--no-yolo`: Run the agent unattended (default: True).
   - `--keep`: Keep the run's state directory even when it succeeds.
 - **`skill install`**: Install the packaged Agent Skill so agents discover
-  Lemming. Writes to `~/.agents/skills` by default and names any tool-specific
-  directories it found.
+  Lemming. Writes to `~/.agents/skills` and every detected tool-specific
+  directory by default. Re-running it refreshes existing Lemming copies.
   - `--to <dir>`: Install into a specific skills directory.
-  - `--all`: Also cover every detected tool's own skills directory.
   - `--link`: Symlink instead of copying, so upgrades take effect immediately.
-  - `--force`: Replace an existing installation of this skill.
   - `--dry-run`: Print what would happen, refusals included.
-- **`skill uninstall`**: Remove it again. Same `--to`, `--all`, and `--dry-run`.
+- **`skill uninstall`**: Remove it again. Supports `--to` and `--dry-run`.
+- **`skill status`**: Show every supported location and installation state.
+  Supports `--json` for structured output.
 - **`stop`**: Stop the running loop and its runner.
   - `--after-current-task`: Drain instead — let the running task finish, then
     stop before claiming another. This is the safe way to change the runner or

{lemming_cli-0.4.6 → lemming_cli-0.5.0}/SKILL.md

@@ -24,6 +24,9 @@ agent run can hold.
 ```sh
 lemming -v exec "Fix the flaky heartbeat test in src/runner_test.py" --runner codex
 
+# Opt into at most three total attempts for transient runner failures
+lemming -v exec "Fix the flaky heartbeat test" --retries 3
+
 # Pipe a longer handoff rather than fighting shell quoting; no length limit
 cat handoff.md | lemming -v exec -f - --runner agy
 ```
@@ -48,8 +51,70 @@ 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.
+The runner receives no conversation history and cannot be steered mid-run. Give
+it a self-contained handoff with:
+
+- **Goal:** the concrete outcome to produce.
+- **Hard constraints:** scope, compatibility, process, and safety requirements.
+- **Relevant findings and evidence:** paths, commands, output, and prior
+  observations it should rely on.
+- **Approaches ruled out and why:** decisions it should not revisit without new
+  evidence.
+- **Definition of done and verification:** the required result and checks that
+  prove it works.
+
+For example:
+
+```sh
+lemming -v exec -f - --runner codex <<'EOF'
+# Goal
+Fix the race that lets two workers claim the same queued job.
+
+# Hard constraints
+- Keep the SQLite schema and public CLI unchanged.
+- Make the smallest scoped change; do not reformat unrelated files.
+
+# Relevant findings and evidence
+- `uv run pytest tests/test_queue.py -k concurrent_claim` fails intermittently.
+- `src/queue.py:claim_next` reads and updates in separate transactions.
+
+# Approaches ruled out and why
+- Do not add an in-process mutex; separate worker processes would bypass it.
+
+# Definition of done and verification
+- The concurrency test passes repeatedly and no existing behavior regresses.
+- Run the focused test, then the full test suite and configured linter.
+EOF
+```
+
+## Isolate concurrent writing runs
+
+Concurrent writing runs must use separate working copies. Detect and use the
+repository's existing version control system, then pass each copy with the
+global `-C` option. The caller owns creation, result recovery, and cleanup;
+Lemming remains independent of Git, Mercurial, and other VCSs.
+
+For Git, refuse modified or untracked input rather than silently excluding it,
+then create a worktree from committed `HEAD`:
+
+```sh
+repo=$(git rev-parse --show-toplevel) || exit 1
+test -z "$(git -C "$repo" status --porcelain)" || exit 1
+worktree=$(mktemp -d "${TMPDIR:-/tmp}/lemming-exec.XXXXXX") || exit 1
+branch="lemming/$(basename "$worktree")"
+git -C "$repo" worktree add -b "$branch" "$worktree" HEAD || exit 1
+printf 'Worktree: %s\nBranch: %s\n' "$worktree" "$branch"
+lemming -C "$worktree" -v exec "<self-contained task>" --runner codex
+```
+
+Retain the reported worktree after success, failure, timeout, or interruption.
+After its changes have been committed, copied, or deliberately discarded, use
+Git's non-forcing cleanup so dirty or unmerged work is not destroyed:
+
+```sh
+git -C "$repo" worktree remove "$worktree"
+git -C "$repo" branch -d "$branch"
+```
 
 ## Run a review
 
@@ -111,12 +176,14 @@ one off for the project.
 - **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.
+- **`exec` makes one attempt by default.** `--retries N` opts into at most `N`
+  total task attempts with progress carried forward. Explicit failure,
+  cancellation, interruption, and failed reviews stop immediately.
 - **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`.
+  run its own VCS-managed working copy and address it with `-C`; retain the copy
+  until its result is recovered.
 - **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

{lemming_cli-0.4.6 → lemming_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lemming-cli"
-version = "0.4.6"
+version = "0.5.0"
 description = "An autonomous, iterative task runner for AI coding agents."
 readme = "README.md"
 authors = [
@@ -16,6 +16,7 @@ keywords = ["ai", "agents", "automation", "antigravity", "claude", "opencode"]
 dependencies = [
     "beautifulsoup4>=4.13.3",
     "click>=8.0.0",
+    "click-agentcli>=0.3.0",
     "fastapi>=0.124.4",
     "markdownify>=0.14.1",
     "pydantic>=2.12.5",

{lemming_cli-0.4.6 → lemming_cli-0.5.0}/src/lemming/cli/exec_cli.py

@@ -30,6 +30,9 @@ ALL_REVIEWS = "all"
 # large enough that reading it whole is wasteful.
 MAX_LOG_TAIL_BYTES = 256 * 1024
 
+# Log header used to isolate the final runner or review output.
+ATTEMPT_HEADER = "--- Attempt started at "
+
 
 def _read_log_tail(
     log_file: pathlib.Path, max_bytes: int = MAX_LOG_TAIL_BYTES
@@ -41,17 +44,20 @@ def _read_log_tail(
         max_bytes: Most bytes to read from the end of the file.
 
     Returns:
-        The tail of the log, decoded leniently. A leading partial line is
+        The final attempt within the decoded tail. A leading partial line is
         harmless: the extractor skips anything that is not a whole event.
     """
     try:
         with open(log_file, "rb") as f:
             f.seek(0, 2)
             f.seek(max(0, f.tell() - max_bytes))
-            return f.read().decode("utf-8", errors="replace")
+            text = f.read().decode("utf-8", errors="replace")
     except OSError:
         return ""
 
+    header = text.rfind(ATTEMPT_HEADER)
+    return text[header:] if header >= 0 else text
+
 
 def _resolve_prompt(description: str | None, file: typing.TextIO | None) -> str:
     """Returns the prompt text from an argument or a file.
@@ -237,6 +243,13 @@ def _task_status(
     default=60,
     help="Minutes before the agent is killed (0 disables the limit).",
 )
+@click.option(
+    "--retries",
+    default=1,
+    type=click.IntRange(min=1),
+    show_default=True,
+    help="Maximum total task-runner attempts, including the first.",
+)
 @click.option(
     "--yolo/--no-yolo",
     default=True,
@@ -258,6 +271,7 @@ def exec_command(
     runner_name: str | None,
     model_name: str | None,
     time_limit: int,
+    retries: int,
     yolo: bool,
     keep: bool,
     runner_args: tuple,
@@ -285,6 +299,10 @@ def exec_command(
         if description or file or not reviews
         else None
     )
+    if prompt is None and retries > 1:
+        raise click.UsageError(
+            "--retries only applies when exec has a task description."
+        )
 
     # The runner must edit the caller's workspace, never the throwaway
     # directory that only holds this run's bookkeeping.
@@ -304,9 +322,8 @@ def exec_command(
             return
         scope_text = scope.describe(entries)
 
-    # A one-shot spends one agent run: a silent retry would multiply the
-    # caller's cost without their say.
-    config = tasks.RoadmapConfig(retries=1, time_limit=time_limit)
+    # Extra attempts require opt-in because each can incur runner cost.
+    config = tasks.RoadmapConfig(retries=retries, time_limit=time_limit)
     if runner_name:
         config.runner = runner_name
     if model_name: