Using Elves

New here? Paste this to your agent

Open Claude Code, Codex, Grok Build, or Oh My Pi (omp) in any directory, paste the block below, and let the agent install Elves and explain how it works. Shell install steps are optional if you prefer them: see Install Elves.

Install Elves for whichever coding agents I have on this machine (Claude Code, Codex, Grok Build, and/or Oh My Pi / omp), then explain how Elves works. Do not start an implementation run unless I ask.

1. Detect availability:
   - Claude Code: `claude` on PATH and/or `~/.claude`
   - Codex: `codex` on PATH and/or `~/.codex`
   - Grok Build: `grok` on PATH and/or `~/.grok`
   - Oh My Pi: `omp` on PATH and/or `~/.omp`
   Install only for hosts that are actually present. If several exist, install each with an explicit target (do not rely on `all` for first-time install).

2. Install from a temporary clone of https://github.com/aigorahub/elves.git:
   ELVES_TMP="$(mktemp -d)"
   git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves"
   python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target <claude|codex|grok|omp>
   rm -rf "$ELVES_TMP"
   Use target `claude`, `codex`, `grok`, or `omp` to match what you detected. Requires Python 3.10 or newer.

3. Validate each install you performed:
   python3 ~/.claude/skills/elves/scripts/install_doctor.py --startup
   python3 ~/.codex/skills/elves/scripts/install_doctor.py --startup
   python3 ~/.grok/skills/elves/scripts/install_doctor.py --startup
   python3 ~/.omp/agent/skills/elves/scripts/install_doctor.py --startup

4. In plain language, explain:
   - Elves is a skill for Claude Code, Codex, Grok Build, and Oh My Pi / omp (those are the supported main drivers).
   - I own the plan and whether to merge. The driver plans/reviews/lands; a separate worker implements.
   - Default: same subscription, lower-effort native worker. Outcome is usually a landable PR; merge only if I authorize it.
   - Optional workers (Grok under Claude/Codex, Devin, omp-cli /omp shortcut, OpenCode, …) are not required. Native works with no extra keys.
   - Required prewalk qualifies Claude Code, Codex, Grok Build, or omp automatically before task launch when matching proof is absent.

5. Stop after install + orientation. Offer one short first-run starter prompt I can paste later (chat-to-work: landable PR, do not merge).

How a run works

Elves keeps the agent that understands your intent available for planning and review. A separate worker handles implementation. The planning agent can stay quiet while the worker commits progress.

1. Plan. Agree on the outcome, constraints, acceptance criteria, and risky areas with Claude Code, Codex, Grok Build, or Oh My Pi.
2. Work. Elves recommends a worker, gives it one complete packet, and shows its live output or provides an exact follow command before the driver parks.
3. Review. The main driver checks the whole change, pays closer attention to the risks named in the plan, fixes real gaps, and prepares the PR.

Install Elves

Install from a temporary clone. The sync helper updates the main skill and preserves user-owned Claude Code aliases.

Windows through WSL2

Elves runs on Windows through WSL2. Native Win32 is not supported. Run these commands in PowerShell. Install Ubuntu if no distribution exists. Convert it if the VERSION column shows 1.

wsl --status
wsl --list --verbose
wsl --install -d Ubuntu
wsl --set-version Ubuntu 2
wsl -d Ubuntu

Docker Desktop's internal WSL distributions do not count as an Elves host. The install doctor ignores them when it selects a distribution. A failed WSL query reports wsl_probe_failed. It does not claim that no distribution exists. Run wsl --status and wsl --list --verbose to correct that failure before you retry.

Run the next commands inside Ubuntu. Install one supported host in the same WSL2 distribution. Confirm that its command is on the Linux PATH. Set ELVES_TARGET to claude, codex, grok, or omp.

sudo apt update
sudo apt install -y git python3 bubblewrap
ELVES_TARGET=codex
ELVES_TMP="$(mktemp -d)"
git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves"
python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target "$ELVES_TARGET"
case "$ELVES_TARGET" in
  claude) ELVES_ROOT="$HOME/.claude/skills/elves" ;;
  codex) ELVES_ROOT="$HOME/.codex/skills/elves" ;;
  grok) ELVES_ROOT="$HOME/.grok/skills/elves" ;;
  omp) ELVES_ROOT="$HOME/.omp/agent/skills/elves" ;;
esac
python3 "$ELVES_ROOT/scripts/install_doctor.py" --doctor
rm -rf "$ELVES_TMP"

Fugu, Grok, and OMP local shortcuts need a qualified /usr/bin/bwrap probe. Manus and Devin perform remote work, but their Bash runners also start inside WSL2. The doctor reports the local shortcut sandbox and external council process boundary as separate capabilities.

ELVES_TMP="$(mktemp -d)"
git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves"
python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target claude
rm -rf "$ELVES_TMP"

ELVES_TMP="$(mktemp -d)"
git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves"
python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target codex
rm -rf "$ELVES_TMP"

ELVES_TMP="$(mktemp -d)"
git clone --depth 1 https://github.com/aigorahub/elves.git "$ELVES_TMP/elves"
python3 "$ELVES_TMP/elves/scripts/sync_installed_skills.py" --apply --target grok
rm -rf "$ELVES_TMP"

Check the install

# Claude Code
python3 ~/.claude/skills/elves/scripts/install_doctor.py --startup

# Codex
python3 ~/.codex/skills/elves/scripts/install_doctor.py --startup

# Grok Build
python3 ~/.grok/skills/elves/scripts/install_doctor.py --startup

# Oh My Pi
python3 ~/.omp/agent/skills/elves/scripts/install_doctor.py --startup

Grok Bot (non-git jobs)

Grok Bot is not Grok Build. Grok Build is a coding host. Grok Bot is for long unattended non-git work such as HubSpot, Gmail, LinkedIn, or CRM.

Give Grok Bot the skill at skills/elves-grok-bot/SKILL.md. Then say use elves. Do not use /goal.

The kernel is four files (PLAN, SURVIVAL, session.json, LEDGER), a closed Stop Gate until every acceptance row has proof, and a one-minute reminder. One fire at a time. A user stop writes a terminal status and deletes that reminder so the next minute does not resume. Write the item intent before each send or CRM write so an interrupted fire does not double-send. Coding runs still use the root skill on Claude Code, Codex, Grok Build, or Oh My Pi.

Use a focused provider shortcut

A full run is unnecessary when you only want one specialist task. Claude Code installs /fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>, /fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>, /manus <topic>, /grok <instructions>, /devin <instructions>, and /omp <instructions>. In Codex, use the matching $elves fugu|manus|grok|devin|omp … form or ask in natural language; those top-level slash aliases are Claude-specific.

• Fugu is a provider, not always a review mode. Plain fugu <task> follows the requested analysis, design, investigation, or other deliverable. fugu review <scope> keeps the opinionated read-only P0-P3 review with exact file/line findings and a deterministic clean verdict. Both run codex-fugu over a bounded snapshot of policy-admitted tracked and non-ignored untracked files. --include records an exact host-selected context file, but cannot override exclusions for ignored trees, credentials, Git/Elves state, executable agent configuration, unsafe file types/links, or repository escapes; that exact path must actually be admitted and copied, and gitignored includes fail closed before the provider launches (--preflight checks without launch). Both .env.* and *.env dotenv-name families plus host-owned internal namespaces are always excluded. Fugu is limited to planning and read-only review. The runner rejects --write. macOS read-only cleanup is best-effort and never proof of recursive containment. The Linux boundary omits procfs; it provides only a synthetic /proc/self/exe link to the qualified, narrowly mounted Codex executable, so Codex can discover itself without exposing parent process environments. Codex's externally-sandboxed mode runs only inside Elves' mandatory outer boundary. Fugu uses regular fugu/high when the host chooses plain, fugu/xhigh with --deep, fugu-cyber/xhigh with --cyber, fugu-ultra-v1.1/high with --ultra, or fugu-ultra-v1.1/max with --max for one narrow high-stakes gate on a 60-minute budget. Plain regular Fugu is the default. The host may select Cyber only for explicit security review or threat-model intent after a successful Cyber call in the current session. Only a user-explicit Cyber request may establish that proof. Otherwise, it uses regular Fugu. The user must explicitly select Ultra or Max. Use --max-wait before automatic --deep; if any --include, run --preflight first; redirect to a log (never | tail). When you say “use Fugu” without a profile flag, the host uses plain Fugu by default. It may select Cyber for explicit security intent. It states a short Fugu route: … line. Explicit flags always win. The isolation snapshot is always on. See references/provider-shortcuts.md (Host routing when the user says "use Fugu") and references/fugu-calling-guide.md. Regular and deep calls are ephemeral one-shot sessions. Ultra reserves part of its total wall limit for synthesis; if exploration uses its phase, Elves resumes the exact captured session with further tools forbidden. It never guesses the “last” session, and its state and raw events remain only in the disposable lane. Events cross a bounded host-owned pipe, final output stays pinned to a no-follow descriptor, and a final descriptor-safe writable-state audit runs after each phase settles.
• Review snapshot media policy applies to every harness and host. Read-only review snapshots omit oversized binary media instead of failing the whole review. Video, audio, presentation, archive, image, font, and 3D binaries above the per-file limit are left out; the 16 MiB per-file limit is not raised. The context manifest records each omitted path, byte size, and reason, and every runner prints the same omission block. Source, prose instructions, executable agent configuration, and explicit --include paths still fail closed, with a remediation that asks for a derived text, image, or transcript artifact. Writable lanes keep fail-closed behavior.
• Fugu is optional. When a review route is unavailable because of quota, authentication, catalog, runner, timeout, or provider failure, Elves probes the supported review routes and selects another available independent reviewer instead of stopping. An explicit user route is preserved when it works; otherwise a supported native reviewer is preferred when no optional provider works. Elves records requested route, actual route, and fallback reason. It does not claim a review ran when it did not, and optional-provider failure does not block the run while a qualified review route exists. Probe with cobbler_agents.py review-route --host <host> --requested <route> --unavailable <route>=<reason>.
• Manus creates private, bounded deep-web research and needs MANUS_API_KEY. To request one worker per paper or reference, use /manus --wide --items-file references.json <goal>. Cobbler requests native Wide Research, checks exact roster coverage, repairs missing or duplicated items with independently tracked tasks, then synthesizes. Use --fanout to skip the native attempt, --file for explicit sources, and --resume with the printed ignored manifest. Resume preserves successful and live task IDs while archiving and retrying only known-failed steps. New manifests stay under .elves/runtime/manus/, are exclusively reserved before upload, never replace existing files, and durably mark each roster-task creation before its request so an interrupted task-ID write cannot trigger an automatic duplicate. Requests place empty connector, enabled-skill, and forced-skill lists under message, granting no connector or forced-skill IDs explicitly. Manus documents that empty enable_skills loads account-default enabled skills, so this route does not promise skill isolation.
• Grok runs the installed Grok Build CLI headlessly at high reasoning by default, without bypassing permissions over a disposable tracked-source snapshot in a required outer kernel sandbox. Grok also uses its built-in inner strict profile, provider-documented isolated dontAsk settings, and a bypass lock. It requires an explicit XAI_API_KEY; a dedicated tool shell removes both key names before model-directed commands run, and the Linux boundary omits procfs to block parent-environment inspection. Shared-file OAuth is rejected because Grok applies its sandbox to both provider and tool reads. Argv is built from the flags the installed CLI advertises: a missing safety flag (isolated --cwd, inner --sandbox strict, headless --single, --output-format, explicit reasoning effort) fails closed, while a quality flag the installed version dropped is simply not passed. Auto-update is disabled through the isolated [cli] auto_update config key rather than a removed flag. ELVES_GROK_EFFORT selects low, medium, high, or xhigh, and ELVES_GROK_MODEL pins a model only when the authenticated live catalog lists it. The runner reports the CLI version, effort, model, the authentication route the CLI itself names, and any omitted flags. On a host that cannot nest sandboxes (macOS refuses a second profile inside Elves' required outer sandbox-exec boundary), the runner fails closed before it builds a snapshot rather than launching with the inner profile silently missing. Elves does not drop the inner profile to make a launch succeed, and the outer boundary is not optional; use a Linux host with the bwrap backend or select another review route.
• Devin creates and boundedly follows a remote developer session and needs DEVIN_API_KEY. Stored Devin secrets and knowledge are not granted by default, and bounded session creation and polling responses share a hard wall-clock wait budget.
• Oh My Pi (/omp / $elves omp) is the optional worker/shortcut under Claude/Codex/Grok: headless omp over Elves' isolation snapshot with one provider-matched API key (set ELVES_OMP_MODEL). Parked full-run labor uses adapter omp-cli. Opening omp as the host with the managed skill root is a supported main driver; that is a different role. Never spell the CLI opm. The Linux shortcut omits procfs and has no /proc view; it does not receive Fugu's synthetic Codex /proc/self/exe link. Shortcut writes are not supported; use full-run for implementation labor. See references/omp-worker.md.

Manus chooses whether its internal Wide mode activates; the public API has no documented force-Wide or create-child endpoint. Cobbler's coverage check and deterministic fallback make the result auditable without pretending otherwise.

These optional routes can consume paid provider capacity. They do not grant merge or protected-branch authority. A local timeout leaves the remote Manus or Devin task alive and prints its follow link.

Start a run

Start with the outcome and the landing choice. You do not need to name internal Elves phases or write a launch script.

1. Open a terminal and change to the repository you want Elves to modify.
2. Start Claude Code with claude, or open the repository in Codex. Codex CLI users can start it with codex.
3. Paste one of the prompts below into that agent conversation.

Finish the work but do not merge

Implement this plan while I am offline. Review the completed work and leave the PR ready for me, but do not merge it.

Finish the work and merge when it is ready

Implement this plan, review and revise the completed work, then land the PR with a regular merge commit when all serious issues are resolved.

Both requests use the same planning, implementation, proof, and review path. The second request also grants the driver merge authority after final readiness. Worker completion alone is never enough.

If the plan is still in your head

Describe the change in ordinary language. Elves will help turn it into a durable plan before launching the worker. Name the parts that need caution and the evidence that would convince you the result is complete.

What happens to things it notices along the way

A run always finds work the plan did not cover. Elves keeps three destinations apart, so nothing turns into scope creep and nothing gets lost:

The third one is the rule that keeps runs honest. The worker searches existing issues so it does not file a duplicate, opens one naming the file and line and why it was out of scope, records the link, and moves on. It never quietly fixes it and never widens the batch you approved. Your terminal report lists every issue the run opened.

If you do not know what to work on

Ask for a discovery pass instead of a run:

Do a discovery pass on this repo and tell me what is worth doing.

Discovery is read-only on source. It sweeps the repository against nine audit categories, ranks what it finds by impact over effort, and writes nothing outside advisor-plans/. Every finding names a file and line and the concrete effect, so vague reports never reach you. Not worth doing is a recorded verdict rather than a silent omission, so you can see what was considered and dismissed.

Findings you pick become one self-contained plan each, written for an executor with no memory of the survey. Those plans feed the normal run above. Findings you do not pick are filed as GitHub issues rather than carried in anyone's memory.

Choose a worker

Elves checks the current host and available tools without making a model call. It shows one recommendation and asks at most one useful preference question.

“Inherit” means the exact same model, with only effort lowered: GPT-5.6 xhigh/extra-high/ultra → GPT-5.6 medium; GPT-4.8 Max/UltraCode → GPT-4.8 medium; Fable 5 max/ultra → Fable 5 low; Opus 5 max/ultracode → Opus 5 high. Native delegation stays inside one model family, so a Fable driver hands off to claude-fable-5 at low instead of routing to Opus. Unlisted native routes remain plan-matched. The live driver is not downgraded. Devin CLI, Oh My Pi (omp-cli), and other configured adapters remain optional routes, not required setup. Grok provider availability is independent from goal support: proven headless /goal is an enhancement, and a compatible one-packet prompt is the recorded fallback. Permitted Grok workers use grok-4.5 at explicit high when the live catalog offers it. Composer 2.5 is retired and is never selected.

Machine-check a cold handoff when needed

Elves v2.9 adds optional explicit handoff v1 for coordinators that need deterministic state transfer to a separate worker. Declaring it binds fresh-start or resume state, acceptance ownership, the current branch and commit, and a matching bounded Markdown or JSON packet capsule. The ordinary path stays advisory when the schema is absent. This is cold-handoff evidence, not prewalk continuity; see the schema and acceptance contract.

Use exact-session prewalk

Prewalk lets one worker orient on a guide model or effort, create a bounded TODO, make the first real task edit, and then resume the same session in the same worktree on the execution route. The packet is sent once; the later input is only Continue.. Starting a new worker with a summary is a normal cold handoff, not prewalk, and Elves never cold-falls back after an edit.

# Read-only: inspects installed help/version and makes no model call.
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" \
  native-worker prewalk-capabilities --host codex --json
# Use --host claude, --host grok, or --host omp.

# A real launch with --prewalk required runs qualification automatically.
# Use --prewalk experimental only when you explicitly accept qualification uncertainty.

The preference defaults to safe auto, while direct launch defaults to off for compatibility. auto never spends on qualification and reuses only matching cached proof. required automatically runs a 180-second, 1 MiB-bounded live canary when proof is absent. The task worker starts only after exact session, route change, worktree, stream, retained-context, and packet-count checks pass. Failure stops with a private evidence path.

experimental is an explicit operator choice that accepts qualification uncertainty after static grammar inspection. It reports exact_session_experimental and keeps every real-run continuity and authority check. Claude Code, Codex, Grok Build, and Oh My Pi share these semantics. Grok single-phase native-worker launch remains registry-gated. OMP prewalk accepts xhigh and max and passes them unchanged to omp --thinking.

Pin a strong guide and a cheap execution route

The two prewalk phases take separate routes, so a strong model can orient and write the bounded TODO before a cheaper model does the work in the same session. Elves keeps no model list of its own: each route is checked against the host's own live catalog, so any model and reasoning level the installed host publishes is available the day it ships. The catalog widens what the host already accepts and never narrows below it: when it cannot be read, the conservative low/medium/high floor applies.

# Read the levels the installed host publishes for each model.
codex debug models | python3 -c 'import json,sys
for m in json.load(sys.stdin)["models"]:
    print(m["slug"], [l["effort"] for l in m.get("supported_reasoning_levels", [])])'

# Pin both phase routes: strong guide, cheaper execution.
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" native-worker launch --json \
  --host codex --worktree <registered-worktree> --run-id <run-id> --packet <packet> \
  --prewalk required \
  --guide-model <strong-model> --guide-effort xhigh \
  --execution-model <cheaper-model> --execution-effort max

Qualification binds the execution route, which is what the canary proves: this transport resumes one exact session, and the model that resumes keeps the guide phase's instructions. One canary therefore serves every guide route, so trying different guides or guide levels spends nothing extra. Changing the execution model or its level runs a new canary under required. The guide phase is never taken on trust: its TODO, checkpoint, first real edit, session identity, and worktree binding are checked on every run before the handoff.

Use the optional open-source Grok worker

Install from the official Grok Build source, then authenticate once. The first grok launch opens the browser login flow.

curl -fsSL https://x.ai/cli/install.sh | bash
grok

ELVES_HOST=claude  # Use codex when Codex is the live driver.
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" route-worker --json \
  --host "$ELVES_HOST" --execution-reasoning medium --review-risk high \
  --provider grok --allow-grok --probe-grok

The capability check uses the narrow OAuth projection. Its /goal status probe is independent of catalog lookup and model inference, but proves command resolution only. Goal mode additionally requires an authenticated objective canary to reach terminal state and return the requested session identity. Without that evidence, Elves keeps the qualified provider and records the compatible one-packet fallback.

The optional evidence input is a bounded, mode-safe JSON canary artifact tied to the exact installed build, canonical session, /goal prompt digest, successful exit, and matching end event. Invalid or incomplete evidence keeps goal mode off. See the open-source Grok worker reference for the artifact schema.

Parallel lanes (Parallelves)

Parallelves runs several worker lanes at once, each in its own worktree on its own branch, within one run. Serial stays the default. The worker.parallel preference is off unless you set it to auto, and even auto only recommends lanes when a deterministic width test passes. Nothing launches lanes automatically; the driver composes each lane as its own supervised session and records a concrete reason whenever lanes are declined. See the Parallelves contract for the full rules.

Watch the work

The driver opens or reuses a draft implementation PR at the first useful pushed commit, preferably during staging, before bulk execution. Configured bots can then review while work continues. The driver checks each bot's draft support and trigger. It uses a documented review request only when permitted. If draft review is unavailable, it records that limit and keeps unfinished work in draft.

If staging has no useful diff, the driver plans a safe checkpoint at the worker's first useful push only when the installed route and staging gates permit it. Otherwise it opens the draft from useful staging changes before launch. It opens a pending draft before bulk work continues. A bot review, its own check, or a queued bot job proves that review started. Unrelated CI does not.

Workers do not own PR actions. Bot feedback enters driver review at safe checkpoints or when the driver returns from a parked run. Early bot review does not replace final independent review. Read-only audits and issue harvests do not open PRs.

Before the driver parks, it should display the worker's live output or give you an exact command to follow the log. You can watch the worker without asking the driver to narrate routine progress.

Set the active installed skill root first. Keep the target repository as your working directory.

# Claude Code
export ELVES_SKILL_ROOT="$HOME/.claude/skills/elves"

# Codex
export ELVES_SKILL_ROOT="$HOME/.codex/skills/elves"

Then run the exact command Elves printed. Native workers use:

python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" \
  native-worker follow --run-id <run-id>

Grok full runs use the registered session ID instead:

python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" \
  implement full-run-await --session-id <session-id>

After an interrupted run, resume the exact Grok identity. Preparation revalidates the registered session, packet, branch, and worktree before launch:

python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" \
  implement full-run-prepare --session-id <session-id> \
  --branch <feature-branch> --start-head <start-head> --worktree <path> \
  --packet <packet.json> --session .elves-session.json \
  --adapter grok-build --model auto --resume
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" \
  implement full-run-launch --session-id <session-id> --resume \
  --grant-grok-auth --grant-github-push
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" \
  implement full-run-await --session-id <session-id>

If the worker exits cleanly after committing and pushing but omits a valid final report, run the affected host tests and reconstruct only the independently provable fields:

python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" \
  implement full-run-reconcile --json --session-id <session-id> \
  --host-tests-pass

The worker should also commit meaningful slices. Those commits are a durable progress readout and give the final reviewer clean points to inspect. The driver wakes on completion, blocked, or safety events. If the worker exits unexpectedly, the supervisor records the exit and the driver reconciles the actual branch state.

Review and finish

Agy reviews and reviews of fixes require /boost in plan mode. Use a separate reviewer session. If Boost fails, use an authorized 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.

At the end, the driver reviews the complete branch rather than repeatedly reviewing each batch. It checks the plan's acceptance criteria, the risky surfaces, relevant tests, and unresolved GitHub feedback.

Worker confidence actively guides that review on both Claude Code and Codex. A trusted full-run returns a bounded review block at terminal; a native worker records the same signal in Confidence: commit trailers. The reviewer deep-checks every reservation, low-confidence or conflicting area and reports the evidence. Missing signals keep the full baseline review, while high confidence never removes a gate or review step.

Revisions get narrower checks. The driver should not rerun an unrelated full test suite after every small fix. It reruns the tests that the revision could reasonably affect, then performs one final readiness check at the exact branch tip.

Project-specific landing checks

A repository can track .elves/landing-profile.json for bounded deterministic documentation, release, or parity co-change checks. Schema v1 is declarative: executable checks are rejected and no profile-directed process is launched. Elves recomputes a present profile at the exact HEAD and resolved base, records a host-owned digest, and shows advisory and post-merge checklist items. Worker reports cannot override that live result. A missing profile changes nothing. A profile can block readiness, but it cannot authorize merge, tags, releases, protected refs, connectors, secrets, or posting. Hosts may also record observations, synthesize candidates, and explicitly promote checks, or waive one blocking check at the exact HEAD; learning state stays under .elves/runtime/landing-profile/ and never auto-promotes.

If you asked Elves not to merge

The run stops with a reviewed, landable PR. You can inspect it and merge it yourself.

If you authorized landing

The driver clears serious review findings and required checks, confirms the exact PR head, then uses a regular merge commit. Elves never squashes or rebases this path.

Land a reviewed PR later

In the active Elves conversation, say “land this PR.” If the host maps Elves command strings, /land-pr or \land-pr starts the same reviewed landing path. The driver repeats only the checks needed for changes since readiness.

Worktree cleanup after merge

Runs that used a dedicated git worktree reclaim it after the merge. The driver runs ./scripts/preflight.sh --gc-worktrees (installed bundles ship worktree_gc.py with that helper), which first reports and then, with --apply, removes only worktrees that are clean, fully merged, and fully pushed. Anything unmerged, dirty, or not registered as a worktree is listed and left alone, so parallel work and your own directories are never touched.

Save preferences

Safe convenience choices can be stored once for both hosts in ${XDG_CONFIG_HOME:-~/.config}/elves/config.json. Repository safety rules and explicit instructions for the current run still take precedence.

python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" preferences show
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" preferences set worker.provider native
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" preferences set worker.provider grok
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" preferences set worker.prewalk auto
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" preferences reset

Credentials, destructive authority, protected-ref authority, approval bypasses, and merge permission cannot be stored as preferences.

v2.24 run tools

Five driver-facing helpers landed in v2.24, joined by review-route in v2.36 (design adapted, with attribution, from PrimeIntellect's prime-agent, MIT). All are advisory instruments for the run — none of them grants landing, merge, credential, or routing authority.

# Futile re-drive guard: never burn budget re-running an unchanged workspace
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" redrive record-failure --batch B3
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" redrive evaluate --batch B3 --budget 3

# Learnings ledger: auditable, reversible durable memory (freehand files stay valid)
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" learnings validate --file learnings.md
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" learnings apply --file learnings.md --edits-file edits.json
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" learnings rollback --file learnings.md

# Observed usage: morning cost visibility; unknown stays "unobserved", never zero
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" usage aggregate --records-file usage.jsonl --session .elves-session.json

# Salvage: bounded redacted tail of a dead worker's follow log (never a completion report)
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" salvage tail --log .elves/runtime/follow.log

# Continuity watchdog (opt-in): OS-owned timer re-checks a full-run after the session dies
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" continuity install --session-id RUN --branch BR --start-head SHA --packet PACKET
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" continuity status

# Review route: pick an available reviewer when an optional provider fails
python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" review-route --host claude-code \
  --requested fugu --unavailable fugu=quota --available grok --json

Honesty boundaries: the re-drive guard fails toward changed (a fingerprint error can never manufacture futility); usage ceilings are advisory checkpoints, never stops and never routing inputs; salvage text is untrusted observed output; the continuity watchdog only writes templates — Elves never activates the timer, defaults to detect-and-report, and never resumes a terminal run; review-route selects a route and records requested route, actual route, and fallback reason, and never claims a review ran. Details: references/e2e-chat-to-land.md, references/learnings-template.md, references/schema-and-acceptance.md, and references/operations-guide.md.

Troubleshooting

Deeper references

• Adaptive worker routing
• Exact-session native-worker prewalk
• Open-source Grok Build worker
• Joyful runs contract
• Landing authority
• Project landing profiles
• Claude Code and Codex parity