Installation

Genie runs on Linux and Apple Silicon macOS. Windows is not supported; WSL2 works but is not on the tested matrix.

Before you install

The genie binary carries its own runtime, so the CLI needs nothing else to run. The install and the skills need a few tools:

Tool	What needs it
curl and tar	`install.sh` downloads and unpacks the release with them
Git	Genie keeps its state per repository and works in git worktrees
Node.js with `npx` on your PATH	The skills step runs the pinned skills.sh CLI through `npx`
A coding agent	Claude Code runs the skills and the saved workflows; Codex and the other agents skills.sh supports run the skills
GitHub CLI (`gh`), signed in	`/wish` opens its pull requests with it

Install Genie

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

To read the script before it runs, download it first:

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

The script does three things:

Fetch and verify the signed release
It reads the stable channel manifest, downloads the release for your platform and verifies its signature and provenance before it unpacks anything.
Link the binary
It installs the binary under ~/.genie and links genie into ~/.local/bin. When that directory is not on your PATH yet, it adds one line to your shell's startup file and tells you to open a new shell.
Hand over to genie install
genie install delivers the skills through skills.sh into every agent skills home it detects, copies the saved workflows into ~/.claude/workflows, and records what landed in ~/.genie/skills-install.json.

An agent counts as detected when its own home directory, such as ~/.claude or ~/.codex, already exists. Genie never creates one. 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.

Install the binary without the skills

The script passes its arguments to genie install. Its --integrations option is your consent for the skills step: any value other than none installs the skills to every detected agent. To install only the binary:

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

--skip-integrations does the same. genie install then writes no install record and reports skills: skipped (consent: none).

Coming from an earlier version

Older Genie releases were installed globally through a package manager. When install.sh finds one of those installs, it prints the exact command that removes it, because the older genie would otherwise keep running ahead of the new one on your PATH. The release notes list what v6 removed and what to do instead.

Skills without the Genie CLI

The skills are published through skills.sh, so an agent can use them without the Genie CLI:

1npx skills add automagik-dev/genie -g

-g installs for your user, under your home directory. Without it the command is project scoped: it writes the skills into the current directory and nothing machine wide.
The command asks which agents and which skills to install. --agent and --skill answer those questions on the command line.
--all answers both with everything: every skill, and every agent skills.sh knows, which creates a skills home for agents you do not use. Name your agents with --agent instead.
--copy writes plain files instead of symlinks, for an agent or sandbox that does not follow links.

The public command tracks `main`, not a release

npx skills add automagik-dev/genie installs the skills on the repository's default branch, main, whatever @<ref> suffix you add: the skills CLI treats that suffix as a skill filter, so the command still resolves to main. main can be ahead of or behind any release.

genie install and genie update point the same CLI at the skill tree inside the signed release you are running. Use them when you need the skills that match your binary.

Verify your install

1genie doctor

genie doctor checks the binary, your repository and the skills channel, and suggests a remedy for every line that needs one. An excerpt from a healthy install of v6.261003.1, with the home directory shortened to ~:

12345678  ✔ genie version — 6.261003.1
  ✔ genie on PATH — ~/.local/bin/genie
  ✔ git present — /usr/local/bin/git
  ✔ skills: claude — 18/18 @ v6.261003.1
  ✔ skills: agents — 18/18 @ v6.261003.1
  ✔ skills: goose — not detected
  ✔ skills: windsurf — not detected
  ✔ workflows: catalog — 12/12 in ~/.claude/workflows @ v6.261003.1

Run it from inside a git repository: outside one, the repository checks warn.

Reading the skills lines

genie doctor is a read-only observer of the skills channel. It compares the install record Genie wrote at ~/.genie/skills-install.json against what is actually on disk under each agent's skill home, and reports the drift. It never installs, retires, or repairs anything, not even under --fix. genie update owns every mutation on this surface.

Line	Meaning	What to do
`skills: <agent> — <n>/<n> @ v<version>`	Every recorded skill is present in that agent's home, installed from release `v<version>`	Nothing
`skills: <agent> — not detected`	That agent's config home does not exist on this machine. That is a healthy state, reported as a pass	Nothing
`skills: <agent> — <n>/<m> @ v<version>` (warn)	Skills are missing from that home	`genie update`
`skills: <agent> — <n>/<n> @ v<version> (stale, binary is v<newer>)` (warn)	The skills on disk came from an older release than the binary you are running	`genie update`
`skills: <agent> — <n>/<n> @ v<version> (unrecorded)` (warn)	Skills are on disk but no install record exists, so Genie cannot say which release put them there	`genie update`
`skills: channel — no install record` (warn)	Genie has never installed the skills channel on this host	`genie update`

The workflows: catalog line reads the same record for the saved workflows. It names any recorded workflow file that was edited by hand, deleted, or left by another release, and it repairs nothing either.

Restart required. After any install or update, most agents only pick up new skills on the next session start. If a skill doesn't autocomplete, restart your agent session before assuming the install failed.

Environment variables

Variable	Default	Description
`GENIE_HOME`	`~/.genie`	Relocates all of Genie's global state: config, install record, backups and worktrees
`GENIE_AGENT_NAME`	none	Worker identity for task claims and stage log entries
`GENIE_AGENT_ID`	none	Worker identity when `GENIE_AGENT_NAME` is unset; with neither set, the identity is `cli`
`GENIE_WORKTREES_DIR`	`<GENIE_HOME>/worktrees`	Moves the worktrees directory out of `GENIE_HOME`
`GENIE_CHANNEL`	`stable`	Read by `install.sh`: set it to `dev` to install the latest dev build

Updating

123genie update            # update on your current channel
genie update --dev      # switch to the dev channel
genie update --stable   # switch back to the stable channel

genie update verifies the signed release offline, swaps the binary and then reinstalls the skills and the saved workflows from the tree that shipped inside that release, so what is on disk always matches the binary. A failed skills install never rolls the binary back: the command prints the exact remedy, exits non-zero, and stays retryable. Run genie doctor afterwards to confirm the skills lines are green.

Uninstalling

1genie uninstall

Uninstall is record-driven and digest-verified. It reads ~/.genie/skills-install.json and, for each agent skill home that record names, deletes only the skill directories that record named and whose content still hashes to the digest recorded at install time. The saved workflows get the same treatment in ~/.claude/workflows. Then it removes the install record, the ~/.local/bin links and the ~/.genie directory, keeping ~/.genie/state-backups.

What that means in practice:

Skills you added yourself are left alone. A skill the record never named is structurally out of reach of the removal.
A directory Genie cannot prove is still its own is preserved, not deleted. If you edited a Genie skill in place, or the record predates content digests, the directory stays and genie uninstall reports it. Data safety beats cleanliness.
A foreign directory that --copy overwrote at install time is not restored. The install snapshots and backs up any foreign same-named skill directory before overwriting it, and tells you where the backup went; uninstall does not put it back. Restoring it is a manual step.
If anything could not be removed cleanly, uninstall keeps ~/.genie and the install record so the whole operation stays retryable.
Your project's local .genie/ state directory is preserved.

What's next

Quickstart

Deliver one task as a pull request with /wish.

Skills catalog

The skills the install delivered, one line each.

CLI reference

Every genie command, from genie --help at the release tag.

Security and releases

How each release is signed and verified.

Ask AI about this page