Lantern, illuminating your herd

What it is

A Herdr plugin from the team that brought you Elves. It opens as a chat tab in its own Herdr workspace and starts the CLI you already use — Cursor agent, Devin, Claude Code, Codex, Grok, or Pi. That CLI drives Herdr. It is not a new chat product, and it does not cobble or land PRs.

The sidebar already marks working, blocked, done, or idle. Lantern adds goals and progress in words, then seats or focuses a pane when you ask.

New here? Paste this to your agent

Open Claude Code, Codex, Cursor, Grok Build, or another helper you already have, paste the block, and let it install Lantern and open it. First-run setup happens in the new lantern chat.

Install the Lantern Herdr plugin from aigorahub/herdr-lantern and open it. Do not start a coding agent until I ask.

1. Confirm `herdr` is on PATH and reports 0.7.5 or newer. If it is missing, stop and tell me to install Herdr from https://herdr.dev first.

2. If `herdr plugin list` already shows aigora.lantern from a local `herdr plugin link`, leave that checkout. Otherwise install from GitHub:
   herdr plugin unlink aigora.lantern
   herdr plugin install aigorahub/herdr-lantern
   Skip unlink when nothing is installed. Do not link and GitHub-install the same id at once.

3. Open it:
   herdr plugin action invoke aigora.lantern.open
   Or, from a checkout, `sh install.sh`.

4. Stop. Tell me to switch to the new Lantern tab and answer its first-run question there (harness, model, setting). Do not run onboard apply from this shell.

5. After I set the default in that chat, I can say things like: open battle-paddle.

Need Herdr 0.7.5+ and Python 3. Windows also needs Git for Windows. The shell one-liner below is enough if you prefer not to paste.

Install

1. Need Herdr 0.7.5+ and Python 3 on macOS, Linux, or Windows, already running. Windows also needs Git for Windows. Lantern accepts python3, python, or py -3.
2. One command installs the plugin and opens it:

   herdr plugin install aigorahub/herdr-lantern && herdr plugin action invoke aigora.lantern.open

3. If you had a local herdr plugin link for this id, unlink first:

   herdr plugin unlink aigora.lantern

The first lantern chat asks what to open when you just name a repo. Developers: herdr plugin link /path/to/herdr-lantern. Do not link and GitHub-install the same id at once.

Open it

1. Once it is installed, in Herdr: ctrl+b, then capital H. Lowercase h still moves focus left. If the binding is missing, map prefix+H to aigora.lantern.open and run herdr server reload-config.
2. Or put this repo’s hsh on your PATH and run:

   hsh

Close by quitting the helper CLI. Escape stays inside the CLI. Cursor agent: ctrl+c (twice if a turn is running), or ctrl+d on an empty prompt.

Quit the chat before you upgrade or reinstall the plugin. herdr plugin install drops Herdr’s record of a running lantern pane, so the next open seats a fresh chat beside the old tab. Close that one with herdr pane close <pane_id>.

The lantern checks for a newer published version at light-up and offers the update — it asks first, never upgrades silently. There is no herdr plugin update; a GitHub install refreshes by running the install command again. A linked checkout is only told it is behind; pull it yourself.

Where it sits

1. The first open creates a workspace labelled 🔥 lantern at your home directory and seats the chat there as a tab named home — suffixed with what the chat runs, e.g. home · claude · opus, and the chat's first line names the same. Nothing is dropped into the workspace you are working in, and the empty shell tab of the new workspace is closed, so the chat sits alone. The lantern in the sidebar is how you spot it.
2. Every later open reuses it. A chat that is still running is focused wherever it sits, so moving or renaming that tab is safe. If it has exited, a new chat is seated in the same workspace. Lantern does not open a second lantern workspace.
3. The new workspace lands last in the sidebar. There is no pin-to-top; drag it where you want it.

The chat runs in the plugin state workdir. Home is only where the workspace sits and the search root the helper is told about (HELPER_CWD). Your repositories keep their own workspaces. When the helper CLI exits, the tab closes, and the lantern workspace closes with it if that chat was the only tab. Herdr reuses workspace and pane ids after a restart, so Lantern checks the remembered ids before it trusts them: keep the 🔥 lantern label if you want that workspace reused after the chat closes.

Temporary Codex jobs and cleanup

Full interactive Herdr agents remain the default for work that needs repeated steering, resume, team coordination, or a durable live session. When you explicitly call a bounded Codex task temporary, disposable, low-importance, one-shot, or Daily-Tasks-style, Lantern can run it with codex exec --ephemeral. Disposable research is read-only; bounded updates use workspace-write automatic review. These jobs create no normal Codex desktop history entry and no Herdr agent workspace or tab.

The launcher resolves and preflights the live Codex model, passes the task on stdin, and saves only the final response in private Lantern state outside the product checkout. It inherits the existing Codex login without copying, printing, or serializing authentication/config material. Ephemeral jobs cannot resume; work that needs steering moves to a fresh interactive agent. Update results still require diff inspection and the repository's required tests.

Daily-Tasks has a pinned Windows profile: bin\codex-headless.cmd research --profile daily-tasks --job state-2026-09-15 "Read the durable context and report today's state. Do not edit or send external messages.". Git Bash uses bin/codex-headless. It reads C:\Claude\Daily-Tasks with model phrase 5.6 luna xhigh fast. Every instruction uses a unique job name and starts a fresh ephemeral run; it cannot resume and creates no normal Codex desktop/web session.

Ask clean completed sessions in <repo or workspace> to clean a named scope. Lantern closes only settled tabs with committed clean edits or durably saved findings, passed task/dependency/integration checks, and no active dependents. It rechecks identity and repo state before close. Ineligible tabs stay open with the failed gate reported. Workspace cleanup requires every child tab to pass. Worktree removal is separate. The Lantern home tab, pane, and workspace are never cleanup targets.

Run hsh evening (or hsh nightly) from an outside terminal. Lantern dependency-audits the field, preserves active/unresolved work, closes only completed explicitly temporary workspaces that pass every gate, and atomically writes a compact private handoff. For a Codex Lantern, light-up privately records only CODEX_SESSION_ID and exact pane/workspace identity. Evening verifies the handoff, identity, and foreground PID; closes the exact home pane; proves the pane and Codex process exited; then runs supported codex delete <UUID> --force to remove the old chat and child-agent records from normal desktop history. It never deletes a running session or edits history files directly. Missing identity, uncertain exit, unsupported deletion, or command failure leaves the saved session in place and returns an explicit warning/nonzero result. Handoff failure leaves home open, and the Herdr server is never stopped. Close the Herdr window normally afterward. Run hsh morning to open a fresh Lantern, load and reconcile the handoff, and attach Herdr. Windows can use the included hsh.cmd.

Ship work across repos

Name the repos and the result you want. Lantern states the targets and starts. Ship means the full job through clean merge.

• Ship high ROI issue fixes in storefront, billing-api, and admin-console.Agents read relevant issues and choose a bounded batch of valuable fixes per repo.
• Ship performance improvements in storefront and billing-api.Agents check relevant issues, measure a baseline, and verify the improvement.
• Ship saved carts in storefront and invoice exports in billing-api.Name the changes and their repos. Agents check related issues and PRs, then keep the work within your scope.

Agents read issue bodies, comments, acceptance details, and relevant docs before planning. They check for related PRs and work already fixed. Lantern runs repos in parallel within available capacity. Drivers open PRs early, implement, get independent reviews, fix findings, update docs and versions, merge when clean, and check deployment. Lantern handles routine scoped permissions and reports each repo's result.

Lantern keeps the work moving. It tracks each task and its next step, checks progress on a recurring schedule, handles routine permissions, and resumes stopped sessions. It directs idle drivers to the next gate and verifies results before marking work done. Checks stop when all selected work is done. Ask status to see progress.

If no useful work fits the goal, Lantern reports the checked evidence and records that no change is needed. It does not create a PR for that result.

Keep Lantern open during the run. It uses a native recurring job when available, or an active check loop. Reopen Lantern after a restart to recover unfinished work. If all remaining work needs your input, Lantern reports the blocks and pauses until you answer.

Add stop before merge or PRs only to keep the work unmerged. That stop point overrides earlier broader authority. Use your saved model choices or name a model. No internal workflow name is required. Other workflow phrases and full rules.

New implementation work gets a draft PR at the first useful push, before bulk execution. The driver checks the configured bot review trigger and reads findings at safe batch boundaries. Lantern tracks the PR and bot state. If bots skip drafts, record the block and continue authorized work. Keep incomplete work in draft. Early bot reviews do not replace final independent review.

For the older landable loop and parallel pack phrases, omit merge when clean to stop at a landable PR unless you already gave merge authority for that run. A sweep, harvest, or stage does not grant merge authority. Lantern never merges, edits product repos, or prompts a working chat.

Lantern can grant routine permissions within the named run scope. It reads the blocked prompt, selects a visible allow once option, and checks progress. It does not grant access outside the run scope or turn on broad bypass settings. Yolo stays off unless you name it.

Herd runs need the installed Elves skill. The driver controls parallel batches within its repo. The herd rules load on every Lantern launch, including with a saved custom prompt. Reopen Lantern after an upgrade.

Agy reviews always use /boost in plan mode, including reviews of fixes. Prefer the listed gemini-3.8-flash-high model. Keep a separate session from the code writers. If Boost fails or cannot be confirmed active, use an approved independent fallback or report a block. A plain Agy response does not satisfy review. Use a supervised terminal when headless transport is unqualified. Pass the absolute review workspace to every Boost worker. Approve only scoped review actions. Keep the terminal open until the children finish and the final report names the exact commit. A parent success or delegation notice does not prove completion. A clean review also needs verified coverage of changed files, relevant callers, tests, instructions, and task documentation. Missing required context blocks a clean result. Keep /grill-me for optional planning interviews.

Put a team on one task

Open the interactive team guide for copyable requests, a request builder, and instructions for model discussions, helpers, and parallel repo work.

Give one lead a set of helpers, or compare proposals from several models. Use Elves 2.37.0 or later for team assignments and the callback adapter. On Windows, Elves team execution requires WSL2 and callback paths valid inside WSL2.

• Brainstorm ways to simplify onboarding. Have three models compare approaches.Agents write separate first proposals, critique the alternatives, and give the lead evidence for a recommendation.
• Investigate slow checkout. Give the driver database and frontend helpers.Each helper gets a bounded question. The driver combines findings and tracks decisions.
• Ship saved carts in storefront. Use helpers where useful.The driver assigns work, checks dependencies, and integrates separate writer worktrees.
• Ship high ROI issue fixes in storefront, billing-api, and admin-console. Run two repos at once, with up to two helpers per driver.Set the number of active repos and helpers in the request. Extra work waits for capacity.

Brainstorming and investigation stop with findings. They do not authorize edits or merge. Ship keeps its existing meaning and stop options. Lantern reuses the model routes saved in Elves. Named models and team limits take priority. A comparison without a count starts with a lead and two proposers. Helpers cannot expand their own scope or team.

Agents send persistent reports through Lantern's local mailbox. The Elves adapter receives them at safe checkpoints. Reports survive a busy chat or process exit, but they do not wake chats automatically. Herdr event observation provides hints. Lantern keeps its recurring monitor active and checks the evidence before marking work done.

Each actor has a private credential limited to its run, tasks, session, model, and permitted peers. A message cannot grant permission, change a model, or authorize merge. Keep credentials outside repos and logs. Unsupported socket transports use the existing CLI monitor.

The final reviewer must be separate from the authors and substantive design contributors. Prefer another model family. A separate qualified agent from the same family is valid when no other family is available under saved choices. The reviewer checks the code and documentation before discussing findings with authors.

Read the team rules and callback protocol for setup and recovery.

Choose a live model

• astra, gpt-6 astra, and astra high select Codex gpt-6-astra. The default effort is medium. Supported efforts are low, medium, high, xhigh, max, and ultra. Bare gpt-6 needs a model choice.
• fable, fable 5.1 high, and claude-fable-5-1 high select Claude Code Fable 5.1. Routing reads the live initialization response and pins claude-fable-5-1. Supported efforts are low, medium, high, xhigh, and max. Old CLI help examples do not limit the model list.
• An explicit Cursor request uses its own live model list. Fable 5.1 IDs are listed. No Cursor Astra ID was listed in the 2026-09-05 check.

Codex Fast is off by default. An explicit Fast request needs a listed Fast tier. Codex seats keep --dangerously-bypass-approvals-and-sandbox, including on resume. A model check does not prove that a review ran. Review launch checks also cover local files, sockets, login, and sandbox access. A named review kind cannot change without your choice.

What to say

• “Who is working, blocked, or done?”Inspect-only. It reads herdr agent list.
• “What are they working toward?”Titles, Claude /goal / recap lines, who is waiting on a merge. Status alone is not progress.
• “Jump me to the love-spark agent.”Reuse the workspace. Unnamed agents use a pane id, e.g. w1X:p1.
• “Open battle paddle.”No harness named: uses your spawn default. Set that on first run, or say “make Cursor Grok 4.6 high fast my default spawn”. The new agent gets one opening prompt: load the herdr skill, prompt peers in that workspace, and use a new tab instead of a split.
• “Open the image maker repo with claude.”Reuse if they are already there. An explicit kind or model always wins. Slugs: image-maker, not “Image Maker”.
• “There is a PR on battle-paddle. Get a Codex review.”Resolve the repository and PR first. Check the model before any workspace or tab change. Lantern does not edit the repository.
• “Open battle paddle with Grok.”Bare Grok means Grok Build. The default is grok-4.7-build-fast at medium effort. Say “in Cursor with Grok” to use the Cursor CLI.
• “Open battle paddle with Fugu.”Fugu uses the Codex profile. The default is regular fugu at high effort. Name Ultra, Fugu Max, or effort max when you want those.
• “Create a GitHub repo for X.”Always gh repo create --private. Public only when you ask for public.
• “Make a worktree on herdr for branch helper-tests.”herdr worktree create, not a second workspace on the main checkout.
• “How’s the night shift?”If Elves session files are around, it reads that floor. It does not cobble or land.

Pick your helper CLI

The lantern chat is one CLI. That is yours. It is not a shared team model. The spawn default is separate: HELPER_SPAWN_KIND, HELPER_SPAWN_MODEL, and HELPER_SPAWN_EFFORT are what Lantern opens when you just name a repo.

Claude, Grok, and Cursor seats start in the smart-auto permission tier. Codex seats pass --dangerously-bypass-approvals-and-sandbox so they do not stop for command or sandbox confirms. The herdr wrapper puts that flag immediately after --, including when the seat omitted it or placed it after resume or review. bypassPermissions, --yolo, --force, and --always-approve stay off unless a user asks for yolo and confirms the exact flag and lost protections. Pi has no permission modes: HELPER_PERMISSION is accepted and ignored for Pi, and Lantern never passes any approval-bypass flag to it. Before seating, Lantern checks the live model catalog and availability. After a seat, it renames the tab to <slug> · <kind> and reports the kind, model, effort, Fast state, and task. Every fresh seat also gets one opening prompt: load the herdr skill, prompt the other agents in that workspace, and add work in a new tab instead of splitting the tab.

$EDITOR "$(herdr plugin config-dir aigora.lantern)/helper.conf"

HELPER_AGENT="agent"
HELPER_MODEL="grok-4.7-high-fast"
HELPER_PROVIDER=""
HELPER_EFFORT=""
HELPER_CWD="~"
HELPER_SPAWN_KIND="claude"
HELPER_SPAWN_MODEL=""
HELPER_SPAWN_EFFORT=""
HELPER_PERMISSION="smart"
HELPER_EXTRA_ARGS=""

Empty HELPER_AGENT picks the first of those CLIs on PATH. Conf is KEY=value only; it is never sourced. After an upgrade, copy repo prompt.md over the seeded file if you want the latest rules.

Trust

Runs as you, with your environment. Read launch.sh, lib.sh, and bin/herdr first. Create / start / focus / close run through the helper with HERDR_HELPER_OK=1. The lantern acts on what you ask and stops to ask only when the ask itself is unclear: no target named, or a name that matches more than one.