Using Elves

New here? Paste this to your agent

Open Claude Code or Codex 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 and/or Codex), 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`
   Install only for hosts that are actually present. If both exist, install both.

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

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

4. In plain language, explain:
   - Elves is a skill for Claude Code or Codex (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 Build, Devin, OpenCode, …) are not required. Native works with no extra keys.
   - Grok Build is an optional *worker*, not a supported main driver for the Elves skill itself.

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 or Codex.
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.

ELVES_TMP="$(mktemp -d)"
git clone 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 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"

Check the install

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

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

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.

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. If Fable explicitly routes to Opus, Elves names the cross-model route as claude-opus-4-8 at medium. Unlisted native routes remain plan-matched. The live driver is not downgraded. Devin 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 when qualified

Prewalk lets one native 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 for Claude Code or --host grok for Grok Build.

The preference defaults to safe auto, while direct launch defaults to off for compatibility. Help output proves only that exact-resume and route flags are advertised. Actual prewalk stays off until the exact installed host version has behavioral evidence for session, worktree, and stream continuity, route change, no packet replay, and honest instruction fidelity. The current persisted-instruction transport activates only for proven retained_safe; pruned and turn_scoped remain future delivery states. required fails before launch if proof is absent; no paid canary runs implicitly.

Grok prewalk has an additional maintainer-owned launch gate. A recorded grok_prewalk_qualification_canary must be supplied together with --probe-grok, which binds it to the version and build commit reported by the installed binary. Even valid retained_safe evidence cannot open launch_ready by itself. While that gate is closed, auto reports grok_prewalk_unqualified:launch_feature_gate_closed with actual mode off, and required fails before launch.

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

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

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.

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, 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.

Troubleshooting

Deeper references

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