Immutable. This exact content is served forever at /api/v1/blob/249abdaf5763e7ab.
---
version: "2.36.0"
---
# Elves: Codex repository adapter
This file is a **thin Codex adapter**, not a second workflow fork. The compact
**canonical workflow is `SKILL.md`** — every contract below is a pointer into it or into one authoritative
`references/` file, never a restatement. Differences here are **invocation surface only**;
workflow semantics, the safety kernel, landing policy, and acceptance identity are identical for
Claude Code and Codex (see `references/host-parity.md`).
The task-first user guide is published at `https://aigorahub.github.io/elves/`. This adapter and
`SKILL.md` remain authoritative when the guide is too short to cover an edge case.
## Cobbler
Use Cobbler via `$elves cobbler: <task>`, `$elves council: <task>`, or natural language
("Ask the Cobbler…"). Do **not** invent top-level Codex slash commands; Claude Code managed aliases
(`/cobbler`, `/setup-cobbler`, …) are Claude-specific surfaces. Full Cobbler protocol: SKILL.md
`## Cobbler`.
**Codex Goals** are optional host continuation plumbing (`references/codex-goals.md`) — distinct
from **Grok Build goal mode**, the optional worker capability that is a
capability-proven enhancement with a recorded one-packet fallback; Grok models come only from the
authenticated live catalog (`references/adaptive-worker-routing.md`).
## v2.24 run tools (host-neutral)
The v2.24 helpers — futile re-drive guard (`redrive`), learnings ledger (`learnings`),
observed-usage ledger (`usage`), salvage previews (`salvage`), and the continuity watchdog
manager (`continuity`) — are **host-neutral CLI helpers** with identical semantics on Claude
Code, Codex, Grok Build, and Oh My Pi: invoke them as
`python3 "$ELVES_SKILL_ROOT/scripts/cobbler_agents.py" <verb> …` from any host. They are
advisory instruments (never landing, merge, credential, or routing authority), there are **no
per-host slash surfaces for them** — do not invent top-level Codex or Grok commands — and the
workflow contracts that mandate them (SKILL.md worker-failure recovery, labor completeness,
Skill Memory) apply to all four hosts unchanged. See the guide's "v2.24 run tools" section.
`review-route` joins them as a host-neutral helper on the same CLI surface and the same honesty
boundary: it selects an available review route and records requested route, actual route, and
fallback reason. It never claims a review ran and never carries landing, merge, or credential
authority.
## Codex invocation (host-honest)
| Intent | Codex |
|--------|--------|
| Run Elves | natural language or skill load; not an invented top-level `/elves` |
| Cobbler | `$elves cobbler: <task>` or "Ask the Cobbler…" |
| Cobbler Mode | `$elves cobbler-mode` or natural "Cobbler Mode: on/off" |
| Setup | `$elves setup-cobbler` / `$elves setup-council` |
| Provider shortcut | `$elves fugu [--deep\|--ultra\|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>` / `$elves fugu [--deep\|--cyber\|--ultra\|--max] [--max-wait SECONDS] [--preflight] review <scope>`, `$elves manus [--wide\|--fanout] …`, `$elves grok <instructions>`, `$elves devin <instructions>`, or `$elves omp <instructions>` |
| Land PR | natural language; `\land-pr` / `/land-pr` when the host maps them |
### Provider subprocess capabilities map
For explicit provider-shortcut intent, follow SKILL.md **Provider shortcut protocols** and
`references/provider-shortcuts.md`. Resolve helpers from the active installed skill root; do not
assume `./scripts` belongs to the target repository and do not execute mappings blindly:
- Fugu planning task → `run_fugu.sh [--deep|--ultra|--max] [--max-wait SECONDS] [--preflight] [--include PATH] <planning-task>`; explicit
review → `run_fugu.sh [--deep|--cyber|--ultra|--max] [--max-wait SECONDS] [--preflight] review <scope>`. Planning output follows the task instead
of a forced review rubric; review retains read-only base/change evidence and ordered findings.
**Host Fugu routing:** natural “use Fugu” without an explicit profile flag is host-routed. Before
launch, choose planning vs `review <scope>`, plain / `--deep` / `--cyber` / `--ultra` / `--max`
(profile locks model + effort; no free model slug), and
optional `--include` paths; state one short `Fugu route: …` line; prefer the cheapest matching
lane; explicit user flags always win. Plain regular Fugu is the default. The host may select
`--cyber` only for explicit security review intent after a successful Cyber call in the current
session. Only a user-explicit `--cyber` request may establish that proof. Otherwise, use regular
Fugu. The user must explicitly select `--ultra`
or `--max`. Host-native first for
inventory/triage/greps; prefer `--max-wait` over automatic `--deep`; if any `--include`, run
`--preflight` first (never gitignored paths); redirect to a log (never `| tail`); chat cancel does
not stop the provider; harvest `Fugu partial salvage` from the log on timeout/crash before
relaunch. The isolation snapshot is always on; the host only adds exact admitted
context via `--include`, not a separate “minimal snapshot” mode. Full table:
`references/provider-shortcuts.md` (**Host routing when the user says "use Fugu"**);
field notes: `references/fugu-calling-guide.md`.
All profiles receive a bounded policy-admitted tracked plus non-ignored-untracked snapshot. The host may
select exact context, but the safety kernel rejects ignored/credential/operational/configuration
paths (including both `.env.*` and `*.env` variants and reserved internal namespaces), unsafe
file types, links, modes, races, and repository escapes. Exact includes must be admitted or fail.
Fugu is limited to planning and read-only review. `--write` is rejected. Read-only macOS cleanup is
best-effort and non-authoritative. No Linux procfs is mounted; only a synthetic `/proc/self/exe`
link to the qualified real Codex binary is exposed. Codex external-sandbox mode runs
inside the mandatory outer boundary. Profiles remain `fugu/high`, `fugu/xhigh` for `--deep`,
`fugu-cyber/xhigh` for `--cyber`, `fugu-ultra-v1.1/high` for `--ultra`, and
`fugu-ultra-v1.1/max` for `--max` (60-minute default
wall budget, one narrow high-stakes gate); Ultra uses exact-session staged synthesis and bounded incremental
event parsing through a host-owned pipe, pins final output to a no-follow descriptor, and runs a
final descriptor-safe writable-state audit after settlement.
**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>`.
- Manus research → `run_manus.sh <topic>` for one private bounded task, or
`run_manus.sh --wide --items-file <roster.json> [--file <source>] <goal>` for Cobbler-managed
native-Wide-first research with exact coverage repair; use `--fanout` for deterministic
one-task-per-item execution and `--resume <manifest>` for duplicate-safe continuation; new
manifests are reserved before provider uploads, and ambiguous paid creates fail closed pending
operator reconciliation
- Grok Build task → `run_grok.sh <instructions>` (headless, non-bypass permissions, disposable
tracked-source snapshot in a required outer kernel sandbox, built-in inner `strict`, isolated `dontAsk`
plus bypass lock, explicit `XAI_API_KEY`, a key-scrubbing tool shell, and no Linux procfs; no
shared OAuth file)
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.
- Devin task → `run_devin.sh <instructions>` (remote session, bounded wait, no default stored
secret or knowledge grants; creation and polling share one hard wall-clock bound)
- Oh My Pi task → `run_omp.sh <instructions>` (optional headless worker shortcut under other hosts;
never `opm`; omp is also a supported main driver via `~/.omp/agent/skills/elves`; run-scoped
profile isolation; Linux omits procfs and has no Codex `/proc/self/exe` view)
Codex uses the `$elves` or natural-language forms above, not invented top-level `/fugu`, `/manus`,
`/grok`, `/devin`, or `/omp` commands. Explicit invocation authorizes the provider call and any associated
provider usage, but not merge, protected-ref, secret, or approval-bypass authority.
## Workflow pointers (SKILL.md owns every contract)
- **Default path:** one kickoff; **chat-to-work** stops at a landable PR, **chat-to-land** merges
only with explicit authorization; the default worker is a separate
subscription-native Codex/Claude worker using SKILL.md's exact same-model/lower-effort route map
(plan-matched effort for unlisted routes), with no transferable parent/worker prompt-cache
promise (SKILL.md, `references/adaptive-worker-routing.md`, and
`references/e2e-chat-to-land.md`)
- **Landable is plan Acceptance with proof** — landing check:
`python3 "$ELVES_SKILL_ROOT/scripts/elves_landing_check.py" --session <session-path> --repo-root .`
(session `plan_path` is authoritative; explicit `--plan` is only an equality assertion)
- **Project landing profiles:** a tracked `.elves/landing-profile.json` may add bounded,
declarative exact-HEAD path co-change checks. Executable checks are unsupported; missing is
neutral; present invalid or blocking-failed is red; live results are recomputed host-owned digest
inputs that worker reports cannot override, and never authority. Host-owned
observe/propose/promote/waive learning stays under `.elves/runtime/landing-profile/` with no
auto-promotion (`references/project-landing-profiles.md`)
- **Helper paths:** `python3 scripts/...` is **source-checkout shorthand**; installed skills
(`~/.claude/skills/elves`, `~/.codex/skills/elves`, `~/.grok/skills/elves`, or `~/.omp/agent/skills/elves`) resolve helpers from the
**active Elves skill root** while keeping the target repository as the working directory. An
installed Elves bundle never requires a repo-only helper (`references/runtime-helper-paths.md`)
- **Stop control:** honor the **Stop Gate** and `continuation_guard`; no final response while
stopping is disallowed
- **Handoff standard:** every worker packet carries intent/why, **Build On** targets,
**owned surfaces**, **forbidden surfaces**, **acceptance evidence**, failure modes, and
identity/output format — an incomplete handoff is a **blocking coordinator defect**; for
delegable runs the consolidated packet is a staging deliverable recorded as
`worker_packet_path`; an explicitly declared handoff-v1 session/capsule is strict and
host-neutral (`references/schema-and-acceptance.md`)
- **Git history as operator UI:** subjects use
`[<branch> · Batch N/total · Contract|Implement|Validate|Review|Close] <concrete outcome>`;
**Forbid vague subjects** (anti-patterns: `[feat/auth · Batch 3/12] Updates`,
`[feat/auth · Batch 3/12 · Implement] progress`); commit cadence and phase roles per SKILL.md
(≥1 pushed non-Close slice before the single acceptance-backed Close; driver reconciles use
Review)
- **Worker failure recovery:** transient provider errors back off and resume without consuming
the re-drive budget; workers keep an untracked progress ledger under `.elves/runtime/`
(SKILL.md Worker failure recovery)
- **Confidence-guided review:** attach the terminal full-run
`review_context.review_prompt_block` verbatim, or derive the identical table from native
`Confidence:` trailers; Claude Code/Codex semantics are identical
(`references/review-subagent.md`; `references/host-parity.md`)
- **Parallel lanes (Parallelves):** serial default; `worker.parallel=auto` is recommend-only and
nothing auto-launches (`references/parallelves.md`; SKILL.md Parallel lanes)
- **Prewalk:** exact-session guide→execution continuity only; a cold packet handoff is not prewalk,
and post-edit cold fallback is forbidden (`references/prewalk.md`; SKILL.md Exact-session prewalk)
- **Worktree lifecycle:** One run owns one branch and one checkout; staging records
`worktree_path`; post-merge teardown uses the separate gc helper
(`./scripts/preflight.sh --gc-worktrees`)
- **Unattended:** gates and helper subprocesses run with closed stdin and explicit timeouts
(`references/autonomy-guide.md`)
- **Public API surface snapshots:** optional regression evidence; `required: true` only by
explicit survival-guide opt-in (SKILL.md)
- **Preferences:** safe worker convenience at `${XDG_CONFIG_HOME:-~/.config}/elves/config.json`;
repository safety vetoes outrank everything
## Host check (Grok Build)
Supported main drivers are Claude Code, Codex, Grok Build, and Oh My Pi (omp). If this skill is loaded inside
**Grok Build** as the orchestrator, **stage and run Elves** under the normal workflow. Required
prewalk runs the bounded automatic qualification canary before task launch when matching proof is
absent; experimental prewalk accepts qualification uncertainty without relaxing runtime checks.
Grok remains an optional **worker** under Claude/Codex as well. Full wording: SKILL.md
`## Supported main drivers (host check)`.
## Recovery (same as SKILL)
After compaction: survival guide (Stop Gate + Run Control) → `.elves-session.json` → learnings →
plan → execution log → `.ai-docs/manifest.md` → constitution. Resume the single next required
action immediately.
## Authoritative sources when this file and SKILL disagree
**`SKILL.md` wins** for workflow. This adapter wins only for Codex invocation wording. If you find
divergence, fix this file to re-point at SKILL rather than re-forking protocol text.
## Docs hygiene
Treat stale user-facing docs as **PENDING-DOCS** until updated (see SKILL.md).
Runtime helpers (v2.22): `planning_harvest`, `tool_output_compact`,