genie

Give /wish one decided task. It checks that the task fits, builds it in its own worktree, runs your repository's own check, has an agent that did not write the code review the exact commit, and opens a pull request. Merging stays with you.

curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh | bash

Claude Code runs it as /wish, Codex as $wish, and other agents by name. Docs · Skills · Discord

One /wish from a real run, shortened:

You:    /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.

Genie:  I started the wish workflow in the background on branch
        wish/delete-dead-defaults. It checks that the task fits a single wish,
        makes the change in its own worktree, runs the full check, gets an
        independent review and opens a PR against dev.

Genie:  Review: SHIP. Checks: pass. The PR is open and its remote head matches the
        local one. This run merged nothing. Merging is yours.

How it works

Designs and plans stay in your repository as markdown, with the reviews that approved them, so the next agent you use reads the same context. Each step is a skill. One decided task goes straight to wish. Anything bigger takes the whole loop, where every gate is run by an agent that did not do the work:

brainstorm → design review → wish → plan review → work → implementation review → PR

• brainstorm settles an idea into a DESIGN.md. A design review approves it before any plan is written.
• wish delivers one task end to end and returns a pull request ready for you to merge. Work bigger than one task becomes a WISH.md with execution groups, and a plan review approves it before anything is built.
• work runs the approved groups in dependency order, each with its own scoped worker, and ends at an implementation review.
• review runs those reviews. After work, it checks the result against the plan's criteria and returns SHIP, FIX-FIRST or BLOCKED. fix repairs the blocking gaps with bounded retries and a fresh reviewer.
• council sits beside the loop. It pressure-tests a decision through independent lenses and changes nothing.

Designs, plans and verdicts land in git under .genie/brainstorms/<slug>/ and .genie/wishes/<slug>/. Task state lives in one SQLite file per repository, .genie/genie.db, and genie board shows it as a kanban. Genie is built with Genie: this repository's own designs and plans are in .genie/brainstorms and .genie/wishes.

Skills

Genie v6.261003.1 ships 18 skills. The skill catalog groups them by category, and the Skills docs show a card for each one.

• authoring: Write a Genie skill that passes the shipped contract
• brainstorm: Settle an idea into a reviewed design
• council: Pressure-test decisions through independent lenses
• deslop: Clean up scoped prose, code or interface without losing meaning
• docs: Audit docs and DX against the live product; write on request
• fix: Repair review gaps with bounded retries
• genie: Route or resume work only where Genie adds value
• genie-hacks: Find grounded Genie workflow patterns and recipes
• merge: Resolve a merge or rebase by intent, then re-run the gate
• refine: Improve prompts for OpenAI or Claude
• report: Diagnose a failure to root cause; file issues on request
• research: Investigate against primary sources and cite every claim
• review: Assess plans, code, PRs, and repository quality
• skill-audit: Audit the skill catalogue for overlap, staleness, drift
• verify: Prove completion with fresh gate, diff, and check output
• wish: Deliver one task end to end, or plan a multi-group wish
• work: Execute approved wishes with evidence
• workfly: Build a saved workflow from a procedure

Workflows

A saved workflow is a Claude Code script for a procedure worth running the same way twice. genie install and genie update deliver the catalog to ~/.claude/workflows. Genie v6.261003.1 ships 12. The Workflows docs describe each one. In Codex and other agents without saved workflows, the skills that start them (wish, brainstorm, council, docs, research, skill-audit, workfly) run the same stages by hand.

• brainstorm: runs one round of a brainstorm whose state lives in DRAFT.md, so you answer between rounds, and ends in a reviewed DESIGN.md
• council: architecture, delivery, product, security and dissent lenses, then a synthesis; assess only
• docs-audit: audits every documentation surface against the live product and ranks the drift; assess only
• evidence-gate: verifies a frozen contract of files, commands and claims against the artifact it covers; its only write is the report
• observability-review: reviews traced Claude Code sessions in Phoenix and proposes rule changes, each tied to cited evidence; proposal only
• pm-ledger-verify: adversarial lenses over uncommitted wish ledger edits
• research-sweep: investigates a frozen question against a frozen source list and keeps every claim cited; read only
• skill-audit-sweep: sweeps the shipped skills into a keep, improve, update, merge or retire table; assess only
• skill-intake: assesses candidate skills from outside the catalog and assigns each exactly one disposition; mutates nothing
• test-simplify: audits every test file in scope and proposes batches of tests to delete or consolidate; deletes nothing
• wish: the engine behind the wish skill: admission, one executor in a worktree, a gate, an independent review, bounded repair and a PR; merging stays with you
• workfly: discovers a procedure and builds its saved workflow, checked by a static test and refuters

When not to use it, and what it costs

Genie adds steps around the code. They pay off when a change deserves review, and they cost you time when it does not.

• Small, obvious edits. The run above asked 0 questions and, by its own genie wish report, took 19.9 min and 387,079 tokens to delete dead code. That is one sample. An edit you can make and check by hand is faster without Genie.
• Big plans. Plan size predicts delivery. In an observational sample of 50 wishes, the share merged within 8h fell from 100% (n=9) for the smallest plans to 95% (n=19), 67% (n=12) and 30% (n=10) for the largest. Split big work before it starts.
• Diffs you will not read. Agents miss things, reviewers included. The reviewer passed a wrong gate command in #3045, and #2935 met 68 of 86 blind criteria with 3 HIGH gaps. Read the diff and the verdict before you merge.
• Weak checks. The gate runs your repository's checks, so a wish proves only what those checks prove.
• Untrusted repositories, or no integration branch. /wish runs the repository's own install and check commands, so point it only at repositories you trust. It opens its pull request against dev by default and refuses main or master as the base.

How it compares

Superpowers, Spec Kit and GSD work the same ground. Each of their rows comes from that project's own README.

Install

The one-paste install at the top fetches the signed binary for Linux or Apple Silicon macOS and finishes with genie install. Stable is declared for Linux and macOS: both run in the release gate, so a change that breaks either one does not ship. Windows is not supported; WSL2 works but is not on the tested matrix. Coming from an earlier version? UPGRADING.md covers what changed, what left, and how to clean up.

Genie ships exactly two surfaces:

• The signed binary, installed and updated by install.sh and genie update.
• The skills and the saved workflows, delivered through the skills.sh channel. genie install and genie update run the pinned skills CLI over the tree the signed release put on disk, copy the workflows into ~/.claude/workflows, and record what landed in ~/.genie/skills-install.json.

The installer hands its arguments to genie install. --integrations auto|codex|claude|all|none (or --skip-integrations) is the consent scope for the skills channel: any value other than none installs to every detected agent skill home, because the skills CLI already installs per agent; none skips the channel, writes no record, and reports skills: skipped (consent: none). To install the binary and skip the skills channel:

curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh | bash -s -- --integrations none

Each detected agent gets the skills in its own skills home: ~/.claude/skills for Claude Code, and the shared ~/.agents/skills for Codex and the other agents that read it. genie install and genie update install the skills from the tree the signed release delivered, never from a GitHub ref. The public npx skills add automagik-dev/genie command serves the repository's default branch instead, so it can be ahead of or behind any release.

Every release is cosign-signed with SLSA provenance, and genie update verifies it offline, with no GitHub credential. The repository-hosted .well-known/latest.json and dev.json manifests are the authoritative channel pointers. GitHub's /releases/latest route and prerelease badge are deliberately not channel authority: a promotion advances only a monotonic manifest and never rewrites already-published assets or channel-significant draft/prerelease/latest metadata. Security and releases has the details.

Commands

Genie v6.261003.1 has 18 CLI commands. Nothing runs in the background: every command does its work and exits. The CLI reference has the full --help output.

Repository packages

Mikro lives in mikro/ with its original Git history, npm lockfile, Node build and independent CI. Its runtime and dependencies are not part of the Genie binary or release payload. Root Bun, Biome and Knip discovery exclude that package; its full npm checks run separately.

The standalone runtime requires Node 22.19 or newer and pins the Pi SDK family to 1.0.2. genie mikro call <agent> --engine rlm|pi selects an engine explicitly; otherwise the agent's engine wins, then rlm. RLM remains the default. Pi uses an isolated native session with read, grep, glob, hermetic git and emit_done, not the RLM Python tool pack or an ambient Pi installation. Both paths retain the caller's schema and citation checks. Missing or partial provider usage is unknown: an observed subtotal is not a complete bill. See the agent schema and standalone upgrade boundary.

Repository checks use Bun 1.3.11 or newer, matching CI: subtree test pruning relies on test.pathIgnorePatterns. This development prerequisite does not change Genie's existing CLI runtime floor.

bun run check
npm --prefix mikro run deps:ci
npm --prefix mikro run build
npm --prefix mikro run check
npm --prefix mikro test

mikro update is for a standalone Mikro Git worktree, including linked worktrees. It refuses the nested package before acquiring update ownership or changing Git state. Update the owning Genie source checkout explicitly instead; genie update remains the signed installed-release update path.

Links

Docs: Skills, Workflows, CLI reference, Security and releases · UPGRADING.md · Releases · automagik-dev, the org behind Genie · Discord · MIT License