Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Quickstart

Your first wish is one decided task. /wish checks that the task fits a single wish, makes the change in its own git worktree, runs your repository's checks, has a different agent review the commit and opens a pull request. Merging stays with you.

Before you start

  • A git repository whose origin is on GitHub, and the GitHub CLI signed in (gh auth status says so).
  • An integration branch on origin for the pull request to target. /wish uses dev unless you name another branch, and it refuses main and master.
  • Checks the gate can run. At v6.261003.1 the scout reads your repository's root files for its install and check commands: the frozen install for its lockfile, and a check script, make check, just check or task check, else a test script or make test. A command the scout finds runs only in one of those exact forms. With a hook system, such as husky, lefthook, the pre-commit framework or core.hooksPath, the gate needs a live pre-push or pre-commit hook and runs the check once. With no hook system, or no check to find, it runs the validation command frozen for the task, and CI is the authority. A wish proves only what the gate's command proves.
  • A repository you trust. /wish runs the repository's own install and check commands, so point it only at repositories you trust.
  • Claude Code, which runs /wish as a saved workflow. In Codex, $wish runs the same stages by hand.

Your first wish

  1. Install and check
    Install Genie (the installation guide lists what the install needs), then run genie doctor inside your repository. Its skills: lines and its workflows: catalog line should pass.
    curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh | bash
genie doctor
  2. Prepare the repository
    From the repository root:
    genie init
    genie init writes .genie/INDEX.md and the .gitignore rules that keep Genie's machine-local state out of git. Running it again changes nothing.
  3. Ask for one task
    Open Claude Code in the repository and give /wish one decided, bounded task. Name the files and the outcome you expect. This is the request from the run in the video below:
    /wish Delete dead code: src/lib/defaults.ts has no production callers (only a type import of AgentDefaults in src/lib/workspace.ts) and src/__tests__/dir-ls.test.ts reimplements a removed handler and asserts on its own copy. Move the AgentDefaults type into workspace.ts, delete defaults.ts, defaults.test.ts and dir-ls.test.ts.
    The workflow runs in the background. /workflows in Claude Code shows its progress.
  4. Read the report
    The run ends in one state:
    StateMeaning
    merge-readyThe checks pass, the remote matches the local commit, the pull request holds exactly the declared files and the review says SHIP
    pr-openThe pull request exists but its checks had not finished; read them again with gh pr checks
    refusedAdmission sent the task elsewhere and nothing was created
    blockedSomething stopped the run before or after publishing; the report names it
    missedThe repair budget ran out or a stage returned nothing; the branch, commit and worktree are kept
    After every run the skill also runs genie wish report <runId> --append, which prints the run's tokens and time per stage.
  5. Merge it yourself
    Read the diff and the verdict, then merge the pull request. Genie never merges. The report ends with the command that removes the worktree and the branch after the merge; it refuses a branch that is not merged.

A real run

A time-lapsed replay of a real /wish run in Claude Code. Edited in two places: host details hidden (paths shown as ~/, account plan and quota), and the agent launch line removed.
The video replays the request above, run in Genie's own repository. It asked no questions, and by its own genie wish report it took 19.9 min and 387,079 tokens to reach merge-ready. That is one sample from one run: another task, repository or model gives other figures. The status line shows the session ran with Claude Code's permission prompts bypassed.
The report, as the run printed it:
wish wf_617946b4-8f2 (session b7cfff55-2b82-4b3e-8df0-351c35d8834c, variant unlabeled)
total: 19.9 min, 387079 tokens, 38 tool calls, 6 agents, state merge-ready
stage model   tokens  toolCalls       seconds
admit:scout   claude-sonnet-5-5       77729   10      154
admit:judge   claude-opus-5-5 58571   1       18
work:executor claude-opus-5-5 66285   11      82
gate:check    claude-sonnet-5-5       59186   5       541
review:diff   claude-opus-5-5 64032   4       84
publish:pr    claude-sonnet-5-5       61276   7       317
appended to ~/.genie/metrics/wish-runs.jsonl

When /wish refuses

A read-only scout estimates the change and a judge that never sees the repository picks the route. A task that is too big, or that touches a trust boundary, comes back refused with a route and nothing created. At v6.261003.1 the trust boundaries are .github/, .husky/, .claude/hooks/, .claude/settings*.json, the package.json scripts, the lint and commit-message config, release scripts, and auth, secret and permission surfaces:
RouteWhat to do
planThe task is too big for one pass or touches a trust boundary. Ask /wish for a plan and it writes a WISH.md for work
brainstormA product decision is still open. Settle it with brainstorm first
reportThe cause is unknown. Find it with /report before asking for the fix

Bigger work

Work bigger than one task takes the whole loop: brainstorm settles the design, wish writes the plan, work builds it group by group, review checks it against the plan and fix closes what review blocks. The Introduction shows the loop in one table.

What's next

The wish skill
Everything /wish can be asked to do.
Skills catalog
All 18 skills, one line each.
Workflows
The saved workflows behind /wish and the other skills.
CLI reference
genie wish report, genie board and every other command.