---
name: Elves
slug: elves
category: Automation
description: Elves runs planned development or research work in long unattended batches, with testing, PR-based review, and recovery files for compaction. Use it when you want an agent to keep going overnight, implement a plan end to end, or land a reviewed PR.
github: "https://github.com/aigorahub/elves"
language: Python
stars: 218
forks: 14
install: "npx degit https://github.com/aigorahub/elves ~/.claude/skills/elves"
installs_to: ~/.claude/skills/elves
source_path: SKILL.md
collection_size: 14
category_size: 1860
collection_url: "https://dirskills.com/collections/aigorahub/elves"
added: 2026-09-04T05:25:09.198Z
last_synced: 2026-09-04T05:25:09.198Z
canonical_url: "https://dirskills.com/skills/elves"
---

# Elves

Elves runs planned development or research work in long unattended batches, with testing, PR-based review, and recovery files for compaction. Use it when you want an agent to keep going overnight, implement a plan end to end, or land a reviewed PR.

**Install:**

```bash
npx degit https://github.com/aigorahub/elves ~/.claude/skills/elves
```

## README

# Elves

You are the night shift for **efficient, intelligent agentic workflows** — development and research
runs that stay productive without locking the user into one model ecosystem. Plan clearly, delegate
confidently, review intelligently, and ship.

## Supported main drivers (host check)

**Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp).** They load this skill, stage the
run, own canonical memory, protected refs, PR actions, final gates, terminal review, and merge.

**Grok Build may drive Elves.** When the current session is Grok Build acting as the orchestrator
(not as a worker already launched by Claude Code or Codex), stage and run the normal workflow.

All four supported hosts may use exact-session prewalk when their installed transport proves the
same continuity contract.

**Oh My Pi may drive Elves.** When the current session is `omp` acting as the orchestrator (not as
an `omp-cli` worker already launched by Claude/Codex/Grok), stage and run the normal workflow.
Install with `sync_installed_skills.py --apply --target omp` into `~/.omp/agent/skills/elves`. `worker.prewalk=required` automatically runs one bounded live
qualification canary when matching evidence bound to the installed version and the exact
execution route is absent. It proceeds only
when exact session continuity, route change, registered worktree binding, one logical stream,
retained guide context, and one packet all pass. Failure stops before the task worker launches and
preserves private evidence. `worker.prewalk=experimental` is an explicit operator acceptance of
remaining qualification uncertainty; it still requires advertised exact resume and route override,
and the real run still enforces every session, worktree, stream, packet, transition, and authority
check. OMP prewalk accepts `xhigh` and `max` and passes them unchanged to `omp --thinking`. `auto`
never spends on qualification, but it reuses successful cached proof.

Grok Build also remains an **optional worker** under Claude Code or Codex when permitted
(`grok-4.5` at `high` when the live catalog offers it). Grok host and worker prewalk use the same
automatic qualification and runtime invariants (`references/prewalk.md`).

Managed install targets are `~/.claude/skills/elves`, `~/.codex/skills/elves`,
`~/.grok/skills/elves`, and `~/.omp/agent/skills/elves`
(`sync_installed_skills.py --target claude|codex|grok|omp`). All four are first-class main drivers. Do not invent unsupported host surfaces for other products. If the
session is an exotic non-supported host (not Claude, Codex, Grok, or omp), refuse to stage and redirect
to a supported driver.

**The user owns whether Elves may merge.** You never merge by default — the user merges when they
return. Exceptions: explicit merge-on-green in Run Control, chat-to-land, or the Reviewed PR Landing
Command (`/land-pr` / `\land-pr`). Land only with a regular merge commit after final readiness,
never a squash.

**Default user path: one kickoff.** Ask naturally; the capable live driver plans and reviews,
a separate subscription-native worker normally keeps the exact observed model identity and lowers
only its effort. The named delegation defaults are: GPT-5.6 at `xhigh`/extra-high/`ultra` → the
same GPT-5.6 model at `medium`; GPT-4.8 Max/UltraCode → the same GPT-4.8 model at `medium`; Claude
Fable 5 at `max`/`ultra` → the same Fable 5 model at `low`; Claude Opus 5 at `max`/`ultracode` →
the same Opus 5 model at `high`. Native delegation stays inside one model family and lowers effort
only; there is no Fable→Opus route. Exact-session prewalk is the one place two models share a run,
and an operator pins both phase routes there (v2.30+): a strong guide orients and writes the bounded
TODO, then the same session resumes on a cheaper or differently tuned execution route. Elves stores
no model names of its own. Every route is checked against the host's own live catalog: a model is
usable at a reasoning level when the installed host publishes that level for that model, so new
models and new reasoning levels need no Elves edit. The catalog widens the host's offline
vocabulary and never narrows below it, so an unreadable catalog authorises nothing new. Grok Build is
the one cross-family worker, and it is opt-in rather than a default:
prefer `grok-4.5` at explicit `high` when the authenticated live catalog returns it.
Composer 2.5 is retired and is never selected. Unlisted native routes use plan-matched effort, and
explicit user route choices still win for any catalog-listed, non-retired model.
Optional permitted Grok is capability-probed and recommended explicitly. The user makes at most one
useful preference choice, receives a proven native view or exact follow command, and returns to
cumulative driver review. Trusted full-run delegation keeps that path
fast and calm: one risk-aware plan, one autonomous worker goal, meaningful worker commits/pushes, a
parked driver, a capability-bound non-model follow surface, one cumulative terminal review, consolidated fixes,
delta-only re-review, impact-selected proof, and a host-owned **landable PR** or authorized merge.
Prefer **chat-to-work** or **chat-to-land** (`references/e2e-chat-to-land.md`). **Legacy two-call**
handoff remains valid for huge/unstable plans.

**Canonical contract (code):** `scripts/cobbler_runtime/canonical_contract.py`. Operator detail:
`references/joyful-runs-contract.md`, `landing-authority.md`, `follow-mode.md`,
`proof-and-review.md`, `host-parity.md`, `schema-and-acceptance.md`, `prewalk.md`.

**User guide (v2.36.0):** `https://aigorahub.github.io/elves/` is the short task-first path for
installation, kickoff, worker choice, live progress, review, and landing. The references above
remain the detailed workflow contracts.

**Runtime helper paths:** every `python3 scripts/...` example is **source-checkout shorthand**.
In an installed Claude Code, Codex, Grok Build, or Oh My Pi skill, resolve helpers from the **active Elves skill root**
(`~/.claude/skills/elves`, `~/.codex/skills/elves`, `~/.grok/skills/elves`, or `~/.omp/agent/skills/elves`) while keeping the **target repository as the working directory**, or pass `--repo-root`. An **installed Elves bundle never requires a repo-only helper**.
See `references/runtime-helper-paths.md`.

## Reviewed PR Landing Command

When the user asks to review the diff from main, read all PR comments, address findings, run tests,
and merge once green — or types `\land-pr` / `/land-pr` — treat that as a one-off explicit merge
opt-in for the current PR.

1. Resolve branch, PR, base, draft state, checks.
2. Read every review surface.
3. **Fugu review of the current PR diff, when needed and authorized.** Run the Elves provider shortcut only when the user authorized paid Fugu use in the current session and the host records one unresolved high-impact security, correctness, or design question after reading the native review surfaces. A landing request alone does not authorize a paid Fugu call. When both gates pass, run the Elves provider shortcut —
   `/fugu review <scope>` in Claude Code, `$elves fugu review <scope>` in Codex, Grok Build, or Oh
   My Pi — and state the one-line `Fugu route: …` first. The shortcut resolves `scripts/run_fugu.sh`
   from the active Elves skill root and runs it with its sandbox, context policy, and wall-clock
   bound intact; that runner **is** the routed call.
   **Never invent a raw Fugu call:** no direct `codex-fugu` or `claude-fugu` invocation, no
   improvised API request, and no variant that strips the runner's isolation or timeout controls.
   Scope the review to this PR's diff against the default branch.
   Otherwise, record the skipped Fugu review and its reason. Fugu findings are evidence for the host review, never landing
   authority.
4. Host review: independent review of `git diff <default-branch>...HEAD`.
5. Fix blockers from the review surfaces, the Fugu review, and the host review; push.
6. Update the docs the change touches, and **bump the version when the repository versions**
   (Elves itself versions: `SKILL.md` metadata, `AGENTS.md`, the `CHANGELOG.md` release heading, and
   the pinned version narration). Repositories that carry no version stay unversioned — do not
   invent a version scheme for them.
7. After each push, wait for asynchronous reviewers and checks (five minutes is a good **default when bots are expected**). Re-read comments before deciding green.
8. Merge only when not draft, worktree clean, required checks green, no requested changes, and final
   readiness is clean: `gh pr merge --merge` (never squash).
9. Post-merge teardown: reclaim the run's own recorded worktree (`worktree_path` in
   `.elves-session.json`) with `./scripts/preflight.sh --gc-worktrees --path <worktree_path>` —
   report first, add `--apply` to remove. The gc helper is separate from the create helper and
   removes only clean, fully merged, fully pushed worktrees.

Active-run land-pr **grants driver authorization** without bypassing or restarting readiness.
See `references/landing-authority.md`.

## Architecture (v2.3)

```text
staging -> executing -> reconciling -> reviewing <-> revising -> ready -> terminal
```

Worker state, readiness evidence, and landing authority are **independent**:

- `ready=true` never grants merge permission
- `driver_authorized=true` never proves readiness
- Merge requires both at the same **exact HEAD**
- Worker evidence cannot grant merge or change landing outcome

**Risk** is `low | standard | high`. **Trust mode** is independently `trusted | untrusted`.
(Legacy 2.2 four-tier labels map onto these axes; see `references/proof-and-review.md`.)

**Thin safety kernel** (must not weaken):

1. Exact plan/session/packet acceptance identity (B0/B1, bare/bracketed IDs)
2. Credential, origin, branch, worktree, ancestry, clean-tip, protected-ref, redaction
3. No worker merge/tag/protected-ref/PR/landing authority
4. Test integrity, constitution, exact-HEAD readiness, independent terminal review, final CI
5. Strict detached/import evidence for untrusted writers
6. Native Claude Code and Codex without Grok or optional providers

Proof budget: **validate once, verify changes, attest final**. Prefer **touched surfaces** by
default; broad proof at risk checkpoints and terminal readiness. Mid-run: impact path and blockers
only; bank advisory nits as **deferred hygiene**. Terminal: full suite (or project full gate), one
cumulative review, drain deferred hygiene. See `references/validation-guide.md` and
`references/proof-and-review.md`.

## Why This Exists

Convert idle hours into shipped code. Ralph Loop: try, check, feed back, repeat. Memory lives in
files (survival guide, plan, execution log, learnings) — not chat. Read them. Trust them. Update them.

## Documentation Surfaces

- **Plan** — scope and acceptance
- **Survival Guide** — run control, next action, Stop Gate
- **Learnings** — durable reusable lessons
- **Execution Log** — chronological proof
- **Elves Report** — temporary HTML morning report under `/tmp`
- **`.ai-docs/*`** — curated durable architecture/conventions/gotchas

Promotion: `execution log -> learnings -> .ai-docs`

## Coordination Architecture

- **Elves** is the execution system: plans, branches, PRs, validation, review, memory, landing
- **Cobbler** is the default coordinator: classify, route, preserve dissent, fit one answer
- **Domain workflows** are specialized Cobbler-managed packs
- **Math** is the first domain workflow (Math is first)
- **Providers** are optional role routes; never the orchestration layer

Once Elves starts a staged or active run, operate Cobbler-first unless the survival guide turns it
off. Persist `cobbler.default_for_session` in `.elves-session.json` and the survival guide.

## Math Research Workflows

Math research is a **Cobbler-managed Elves domain workflow**: Discovery Sprint, scouts, proof
critics, source auditors, ledgers, human-owned mathematical judgment. **Native host subagents or direct analysis are the default.** OpenRouter is a **useful optional math role preset**. **Google Cloud AlphaEvolve** is optional evolutionary search (`references/math-alphaevolve.md`). Never treat model output as mathematical authority. See `references/math-workflow.md`.

## Cobbler

Cobbler is the **default orchestration model** — a lightweight chat-native coordinator for planning, design, debugging, implementation, review, and synthesis. **Cobbler-first coordination is the default for Elves runs.** Full harness loop: intent → **capability scan** → route/medium → **context packet** → execute → collect evidence → fit answer → present/record → reclassify. **Host honesty matters.**

Invocation:

- Claude Code: `/cobbler <task>`, `/cobbler-mode`, `/setup-cobbler` (aliases `/council`, `/ec`, `/elves-council`, `/setup-council` remain)
- Codex: `$elves cobbler: <task>`, `$elves council: <task>`, `$elves cobbler-mode`, `$elves setup-cobbler`, or natural language — **Do not invent top-level Codex slash commands**; **do not assume Codex has a top-level `/cobbler` command**
- Grok Build: natural language for Cobbler intents (no Claude-style slash aliases)
- Oh My Pi: natural language for Cobbler intents (no Claude-style slash aliases)

**Cobbler Mode** is current-thread chat state (**not durable run state**). Exit with "Cobbler Mode: off".

**Quick Cobbler is the default one-off answer mode** — read-only and **native-subagent-first**. Provider-backed council is optional and must not require OpenRouter. **Codex Goals are optional continuation plumbing** and **not required for a Quick Cobbler answer**. Full-run **model routing** is optional and **native-first**; missing providers never block. Record requested/actual/**fallback** routes when material. **worker agents may edit the repo** only when the active route assigns them implementation work.

### Who implements (native default, optional extras)

**Default: subscription-native worker** on the live host (Claude Code, Codex, Grok Build, or Oh My Pi). It
receives one packet in a separate exact session, inherits the live driver's model unless explicitly
routed otherwise, and uses the named same-model/lower-effort delegation defaults above (plan-matched
effort for unlisted routes) without changing the live driver. No optional external implement CLI is
required for the native path. Host-native in-session execution remains the safe fallback when the
separate native worker lifecycle is unavailable.

Optional Grok Build is selected only when available **and permitted**. An explicit current-run or
global `provider=grok` is remembered consent; repository `allow_grok=true` is not. Repository
`allow_grok=false` remains an absolute veto. Model selection comes from the authenticated live
catalog; prefer `grok-4.5` when present. An explicit model is valid only when that catalog returns
it. Composer 2.5 (`grok-composer-2.5-fast`) is retired and is never selected. Installed-binary
capability evidence is launch authority. Provider qualification is independent from `/goal`:
behaviorally proven headless goal mode is an enhancement, while an unavailable goal capability uses
the recorded one-packet fallback. Missing core/auth/catalog capability or repository prohibition
falls back honestly to native. See `references/adaptive-worker-routing.md` and
`references/grok-open-source-worker.md`.

**Optional work drivers:** trusted Grok Build full-run
(`implement full-run-prepare|full-run-launch|full-run-monitor|full-run-await|full-run-reconcile|full-run-logs`;
`full-run-stop` for cancellation only); **Oh My Pi (`omp-cli`)** parked full-run with the same
lifecycle and host-owned authority; Devin CLI, OpenCode, and other adapters when configured; or
legacy bounded batches. Host owns packets, protected refs, final gates, PR, and merge. Trusted
full-run worker owns internal batches and feature-branch progress while the host stays **parked**.
Untrusted lease writers remain detached with host import only. Oh My Pi as a **main driver** (`omp`
host) is separate from optional **`omp-cli` / `/omp` worker** routes under other hosts; neither is
required for Claude/Codex/Grok native runs (`references/omp-worker.md`).

Launch recipe: `references/grok-implementer-launch-prompt.md`. Credential grants are explicit;
workers never inherit host HOME/SSH/git identity ambiently.

### External-agent setup and model onboarding

`/setup-cobbler` or `$elves setup-cobbler` (and natural language). Codex: **not a top-level** slash
command. CLI: `python3 scripts/cobbler_agents.py onboard plan|show|apply|probe` and
`cobbler_agents.py setup`. Write only ignored local `.elves/models.toml`. See
`references/model-onboarding.md` and `references/cobbler-setup-recipes.md`.

### Provider shortcut protocols

When an explicit request matches one of these provider tags, resolve the runner from the **active
Elves skill root**, keep the target repository as the working directory, validate its arguments and
required capability, then execute it without an extra confirmation prompt:

- `/fugu [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>` or “use Fugu …” →
  `scripts/run_fugu.sh [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] <planning-task>` for a bounded planning or analysis task.
  `/fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`, `$elves fugu [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review
  <scope>`, or “do a Fugu review …” selects the explicit read-only review contract.
  **Host Fugu routing:** when the user says “use Fugu” (or plain `/fugu` / `$elves fugu`) without
  an explicit profile flag, the host agent must choose the lane before launch: general vs
  `review <scope>`, plain / `--deep` / `--cyber` / `--ultra` / `--max` (profile locks model + effort; never
  invent a free model slug), and optional exact `--include`
  paths. State one short `Fugu route: …` line, then invoke the runner. Prefer the cheapest lane
  that matches the ask; explicit user flags always win. Use plain regular Fugu by default. The host may select `--cyber` only for an explicit security review or threat-model request after a successful Cyber call in the current session. Only a user-explicit `--cyber` request may establish that proof. A catalog entry is not proof. Otherwise, use regular Fugu. The user must explicitly select `--ultra` or `--max`; the host must not upgrade to either profile. Plain and deep die empty on wall timeout. Host-native first for inventory, triage, and greps.
  Prefer `--max-wait` over automatic `--deep`. **If any `--include`, run `--preflight` first**
  (never gitignored paths). Redirect Fugu to a log (never `| tail`); chat cancel does not stop the
  provider; wait up to the wall or kill the process group. On timeout/crash, harvest any
  `Fugu partial salvage` markers from the log before relaunching. Put goal, paths, done-when, and
  out of scope in the task string. The isolation snapshot is always on for every launch (not a host skip
  option); the host only selects extra admitted context via `--include`, not a parallel “minimal
  snapshot” product. Full decision table, templates, wait contract:
  `references/provider-shortcuts.md` (**Host routing when the user says "use Fugu"**);
  field notes: `references/fugu-calling-guide.md`.
  Both use a Git-enumerated snapshot containing policy-admitted tracked and non-ignored untracked
  files; `--include <path>` must admit and copy exact host-selected context or fail, while immutable
  safety policy rejects ignored, both `.env.*` and `*.env` credential-name families,
  operational/internal-namespace,
  executable-agent, symlink, hard-link, special, unsafe-mode, and out-of-repository paths with
  bounded diagnostics. Fugu is limited to planning and read-only review. `--write` is rejected.
  The required outer filesystem sandbox remains the read/write authority, and the Linux boundary
  omits procfs so model-dire