Elves

Elves is an open-source Agent Skill for handing planned development or research work to a separate worker without locking the run to one model provider. The capable Claude Code, Codex, Grok Build, or Oh My Pi (omp) driver plans and reviews; a subscription-native (or optional external) worker implements; durable run files let the work survive context compaction. You write the plan and own the merge decision. The agent does the middle.

Current release: v2.37.2. See CHANGELOG.md for version history. Coined terms are defined once in references/glossary.md.

Implementation runs get a draft PR at the first useful pushed commit, preferably during staging, before bulk execution. The driver opens or reuses it and checks whether configured bots review drafts. It uses a permitted documented bot request when needed. If draft review is unavailable, it records that limit and keeps unfinished work in draft. Bot feedback enters driver review at safe boundaries. Final independent review still applies. Workers do not gain PR authority. Read-only audits and harvests do not open PRs. If staging has no useful diff, a planned worker checkpoint gives the driver control at the first useful push when the installed route and staging gates permit it. Otherwise useful staging changes must supply the draft before launch. The driver opens the draft before bulk work continues. It checks for the bot's own review, check, or queued job.

New to Elves? Use the practical user guide — especially Paste this to your agent at the top. That copy-ready block installs Elves for Claude Code, Codex, Grok Build, and/or Oh My Pi (omp) (whichever is available) and orients you. The guide also covers the first run, worker choice, live progress, review, and landing. This README is the repository reference: shell install, safety model, operations, and an index into the detailed contracts under references/.

Supported main drivers: Claude Code, Codex, Grok Build, and Oh My Pi (omp). All four are first-class hosts: native skill install, doctor validation, automatic required-mode prewalk qualification, and explicit experimental prewalk. Grok Build is also an optional worker under Claude/Codex when permitted. Oh My Pi is also a main driver (omp → ~/.omp/agent/skills/elves) and an optional worker under other hosts. Managed install targets: claude, codex, grok, omp. See the guide FAQ I opened Grok Build and tried /elves.

---

Quick start

Prefer the agent paste in the guide if you already have a supported host open. Otherwise use the shell one-liners below (Python 3.10+). First-time install needs an explicit host target; --target all only updates hosts that already have an Elves skill root.

Windows through WSL2

Elves supports Windows through WSL2. Native Win32 execution is not supported. Open PowerShell and check the installed distributions:

wsl --status
wsl --list --verbose

If no distribution is installed, install Ubuntu. If Ubuntu shows version 1, convert it to WSL2:

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. It reports wsl_probe_failed instead of claiming that no distribution exists when either WSL query fails. Run wsl --status and wsl --list --verbose to correct that failure before you retry.

Run the remaining commands inside Ubuntu. Install the Linux prerequisites. Then install Claude Code, Codex, Grok Build, or Oh My Pi inside the same WSL2 distribution and confirm that its command is on the Linux PATH.

sudo apt update
sudo apt install -y git python3 bubblewrap

# Set this to claude, codex, grok, or omp for the host installed inside WSL2.
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 require a qualified /usr/bin/bwrap probe. Manus and Devin perform remote work, but their Bash runners must still start inside WSL2. The doctor reports local shortcut sandbox readiness separately from external council process-boundary readiness.

Install (Claude Code)

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"

This installs ~/.claude/skills/elves/ plus eleven managed alias skills (/cobbler, /cobbler-mode, /council, /ec, /elves-council, /setup-cobbler, /setup-council, /fugu, /manus, /grok, /devin, /omp). The sync helper creates missing aliases and updates only aliases carrying the Elves-managed marker. If it finds a user-owned alias, it reports the conflict before changing the install and never overwrites that alias.

Install (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 codex && rm -rf "$ELVES_TMP"

Codex installs the main skill bundle only — no slash aliases. Use $elves cobbler: <task> or natural language such as "Ask the Cobbler…". Codex users should not need or expect a top-level /cobbler command. Do not invent top-level /cobbler.

Install (Grok Build)

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"

This installs ~/.grok/skills/elves/ for native Grok Build discovery (first-class host, same workflow contract as Claude and Codex). No Claude-style slash aliases. Invoke Elves via Grok Build skill discovery or natural language.

Install (Oh My Pi)

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 omp && rm -rf "$ELVES_TMP"

This installs ~/.omp/agent/skills/elves/ for native Oh My Pi discovery (first-class host, same workflow contract as Claude, Codex, and Grok Build). No Claude-style slash aliases. Invoke Elves via omp skill load or natural language. Elves prewalk is not omp product --prewalk. OMP prewalk accepts xhigh and max and passes those levels unchanged to omp --thinking.

Optional provider shortcuts

Focused provider tasks do not require a full Elves run. The contracts below are unchanged; this section is the readable index. Full requirements, auth environment names, timeouts, and follow behavior live in references/provider-shortcuts.md.

Commands

Claude Code:

• /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>
• /omp <instructions>

Codex uses the equivalent $elves fugu|manus|grok|devin|omp … forms or natural language.

Fugu

Plain Fugu supports planning and analysis. fugu review keeps the read-only P0-P3 review contract. Both receive a bounded snapshot of policy-admitted tracked and non-ignored untracked files. Fugu is limited to planning and read-only review. The runner rejects --write.

Profiles:

• regular fugu/high (default)
• --deep → fugu/xhigh
• --cyber → fugu-cyber/xhigh
• --ultra → fugu-ultra-v1.1/high
• --max → fugu-ultra-v1.1/max for one narrow high-stakes gate on a 60-minute default wall 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.

--include records an exact host-selected path but cannot override exclusions for ignored trees, credentials, operational state, executable agent configuration, unsafe links/file types, or repository escapes; the exact path must actually be admitted and copied, and gitignored includes fail closed before the provider launches (use --preflight to check). Both .env.* and *.env dotenv-name families plus host-owned internal namespaces are always excluded. macOS read-only cleanup is best-effort, not proof of recursive descendant absence.

Use --max-wait before automatic --deep; if any --include, run --preflight first; prefer redirect to a log (never | tail).

Host Fugu routing: when the user says “use Fugu” without an explicit profile flag, the host agent uses plain by default. It may select deep for regular Fugu xhigh work, or Cyber for explicit security intent. It must not select Ultra or Max without an explicit user flag. It chooses planning vs review and optional --include paths before launch, and states a short Fugu route: … line; explicit flags always win. The isolation snapshot is always on; the host only adds exact admitted context via --include. See references/provider-shortcuts.md (Host routing when the user says "use Fugu") and references/fugu-calling-guide.md.

Regular/deep calls are ephemeral; Ultra and max reserve synthesis time and resume only the exact isolated session with further tools forbidden. Session state and raw events never leave the lane; events cross a bounded host-owned pipe, final output remains pinned to a no-follow descriptor, and every settled phase receives a final descriptor-safe writable-state audit. Codex's documented externally-sandboxed mode avoids an invalid nested macOS sandbox while Elves' required outer boundary remains authoritative.

Fugu's Linux boundary likewise omits procfs around its credential-bearing launcher and exposes only a synthetic /proc/self/exe symlink to the qualified real Codex executable.

Manus, Devin, and Oh My Pi

Manus supports a normal private task plus Cobbler-managed --wide and deterministic --fanout rosters, explicit --file attachments, and duplicate-safe --resume that retries only known-failed steps; roster manifests are validated and exclusively reserved before any upload. A durable pre-create marker prevents resume from duplicating a paid Manus task when task-ID persistence was interrupted. Manus requests nest empty connector, enabled-skill, and forced-skill lists under message, so the wrapper grants no connector or forced-skill IDs explicitly; the documented API still loads account-default enabled skills when enable_skills is empty, and this route therefore does not claim skill isolation.

Devin creates a bounded remote task, including its creation request, without granting stored secrets or knowledge by default.

Oh My Pi (/omp / $elves omp) runs headless omp over the shared isolation snapshot with a single provider-matched API key and never modifies the live checkout from the shortcut (use parked omp-cli full-run for implementation labor).

Grok

Grok uses headless mode at high reasoning by default, without approval bypass over a disposable tracked-source snapshot in Elves' required outer kernel sandbox, plus Grok's built-in inner strict profile, provider-documented isolated dontAsk settings, and bypass mode locked off. The shortcut requires an explicit XAI_API_KEY; a dedicated Grok tool shell removes both supported key names before any model-directed command runs, and the Linux boundary omits procfs to prevent parent-environment inspection. It does not expose a shared OAuth file because Grok applies the same sandbox to provider and tool reads.

The runner builds argv from the flags the installed Grok Build CLI advertises: an absent 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. Reasoning effort defaults to high; 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 Seatbelt refuses a second profile inside Elves' required outer sandbox-exec boundary), the runner fails closed with grok_inner_sandbox_unavailable 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.

Review snapshot media policy (all harnesses and hosts). 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 of the snapshot; 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 (review route fallback). When a review route is unavailable because of quota, authentication, catalog, runner, timeout, or provider failure, probe the supported review routes and select another available independent reviewer instead of stopping. Preserve an explicit user route when it works; otherwise prefer a supported native reviewer when no optional provider works. Record requested route, actual route, and fallback reason. Do not claim a review ran when it did not, and do not let optional-provider failure block the run while a qualified review route exists. Host-neutral helper: python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" review-route --host <host> --requested <route> --unavailable <route>=<reason>.

Per-project install

Clone into .claude/skills/elves, .codex/skills/elves, .grok/skills/elves, or .omp/agent/skills/elves inside your repo (remove the nested .git), or prefer scripts/sync_installed_skills.py over hand-maintaining a second tree.

Validate 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

Update or uninstall

# Update every host that already has Elves installed:
python3 /path/to/elves/scripts/sync_installed_skills.py --apply --target all
# Or update one host:
python3 /path/to/elves/scripts/sync_installed_skills.py --apply --target grok
# Uninstall: remove the skill root you installed (and Claude aliases only if you want them gone):
rm -rf ~/.claude/skills/elves ~/.codex/skills/elves ~/.grok/skills/elves ~/.omp/agent/skills/elves

No plan yet? Start with Discovery

When you do not know what to work on, ask for a survey 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 the nine categories in references/audit-playbook.md, returns findings ranked by impact over effort, and writes nothing outside advisor-plans/. Every finding cites file:line and a concrete effect, so "probably slow somewhere" never reaches you. "Not worth doing" is a recorded verdict, not a silent omission.

Findings you pick become self-contained executor plans in advisor-plans/, one per finding, using references/finding-plan-template.md. Those plans feed the normal run below. Findings you do not pick are filed with gh issue create rather than carried in anyone's memory.

First run

Write a plan (start from references/plan-template.md), then say, from your project:

Implement docs/plans/my-feature.md as an elves run while I'm offline.

The driver stages the run (run docs, branch, dedicated worktree when other agents may touch the repo, worker packet for delegable runs, preflight), launches the worker, reviews cumulatively, and stops at a landable PR (chat-to-work). Merging happens only when you say so — an explicit in-session authorization (chat-to-land) or the reviewed-landing command \land-pr / /land-pr. See references/e2e-chat-to-land.md and references/kickoff-prompt-template.md.

For a machine-checked cold handoff, the session may opt into explicit handoff v1: exact state, acceptance ownership, branch/HEAD, and a matching bounded Markdown or JSON packet capsule. The ordinary v2.8 path remains advisory when this schema is absent. The capsule is not prewalk continuity proof. See references/schema-and-acceptance.md.

Projects with deterministic repository-specific landing rituals may track .elves/landing-profile.json. Its declarative path co-change checks are evaluated at the exact HEAD/base/merge-base and bound to a host-owned digest; schema v1 rejects executable checks and never launches profile-directed processes. Missing profiles are neutral; profiles can block readiness but never grant merge, tag, release, protected-ref, secret, connector, or posting authority. Hosts may observe landings, propose candidates, explicitly promote into the tracked profile, and apply exact-HEAD waive entries — with no auto-promotion. See references/project-landing-profiles.md.

---

Who implements

Default: a subscription-native worker on the live host (Claude Code, Codex, Grok Build, or Oh My Pi) in a separate exact session — no external provider required. Optional work drivers when configured and permitted: trusted Grok Build full-run under Claude/Codex, Devin CLI, or other adapters. Missing optional provider access never blocks a native run. Repository allow_grok=false is an absolute veto. The host owns packets, protected refs, final gates, PR, and merge — always. Details: references/adaptive-worker-routing.md, references/prewalk.md, references/grok-open-source-worker.md, references/grok-implementer-launch-prompt.md, references/omp-worker.md (Oh My Pi main driver + optional omp-cli / /omp worker). Parallel implementation lanes are optional and never the default: serial stays the default, and worker.parallel=auto only recommends lanes when the deterministic width test passes; see references/parallelves.md.

Trusted Grok implementation launches use --always-approve alone: Grok Build treats an explicit --permission-mode auto as an override, so the two flags must not be combined.

Native delegation names both model and effort, and stays inside one model family. GPT-5.6 xhigh/extra-high/ultra hands off to the same GPT-5.6 model at medium; GPT-4.8 Max/UltraCode to the same GPT-4.8 model at medium; Fable 5 max/ultra to the same Fable 5 model at low; Opus 5 max/ultracode to the same Opus 5 model at high. There is no Fable→Opus route — a Fable driver hands off to claude-fable-5 at low rather than crossing families. The one cross-family worker is the opt-in Grok handoff, which prefers grok-4.5 at explicit high when the live catalog returns it. Composer 2.5 (grok-composer-2.5-fast) is retired and is never selected.

Optional exact-session prewalk

Prewalk lets one worker orient on a guide model/effort, create a bounded TODO, make the first real edit, and then resume the same session in the same worktree on the execution route. The packet is sent once; the resume input is only Continue.. A new worker that receives a summary is a normal cold handoff, not prewalk, and cold fallback is forbidden after an edit.

The safe preference is worker.prewalk: "auto", while the launch CLI defaults to off for backward compatibility. auto makes no qualification model calls 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 session, worktree, stream, route-change, retained-context, and packet-count checks pass; failure stops with a private evidence path. experimental explicitly accepts qualification uncertainty after static grammar inspection, reports that status, 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. See the normative prewalk contract and host parity matrix.

Safety model

The user owns whether Elves may merge. The worker never merges; the driver merges only with an explicit opt-in recorded in Run Control, and only with a regular merge commit after final readiness — never a squash. Readiness (plan Acceptance with proof at the exact HEAD) and merge authority are independent; Landable is plan Acceptance with proof, not green CI plus status: complete.

Thin safety kernel (never weakened): exact plan/session/packet acceptance identity; credential, origin, branch, worktree, ancestry, clean-tip, protected-ref, and redaction checks; no worker merge/tag/protected-ref/PR/landing authority; test integrity; independent terminal review; final CI.

The optional continuity watchdog stays outside the kernel's authority surfaces: an operator-owned OS timer that Elves never activates itself, detect-and-report by default, and every safety decision delegated to full-run-prepare --resume — it never resumes a terminal run and holds no landing, merge, or credential authority (references/operations-guide.md).

Forbidden commands. Never: git reset --hard, git checkout ., git clean -fd, force push, rebase on shared branches, rm -rf outside scope, operating on another agent's checkout.

One run owns one branch and one checkout. Prefer a dedicated worktree when other agents may touch the repo (./scripts/preflight.sh --create-worktree <branch> --base origin/main; --dry-run first). The helper prints the branch, worktree path, base ref, and collision tripwire, and does not reuse, delete, or repair exis