elves

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.38.0. 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-v2.0/high when listed, then fugu-ultra, then fugu-ultra-v1.1
• --max → fugu-ultra-v1.1/max for one narrow high-stakes gate on a 60-minute default wall budget. This is effort max, not the Fugu Max model fugu-max.

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