genie

Wishes in, PRs out.

Describe the problem. Genie interviews you, plans the work, dispatches agents, and reviews the code.
You approve and ship.

Install · Quick Start · Features · Discord

What is Genie?

Genie is a CLI that turns vague ideas into shipped PRs through a structured pipeline. Describe what you want — Genie interviews you to capture the full context, builds a plan with acceptance criteria, dispatches specialized agents to execute in parallel, and runs automated review before anything reaches your eyes. You make decisions. Genie does everything else.

Genie is right for you if

• ✅ You've re-explained your codebase architecture to Claude Code for the third time this week
• ✅ You have 5+ AI coding tabs open and can't remember which one is doing what
• ✅ You've watched an AI agent spiral for 20 minutes because it lost the original context
• ✅ You want AI to ask you the right questions before writing code, not the other way around
• ✅ You want to go to lunch and come back to reviewed PRs, not a stuck terminal
• ✅ You want a repeatable process that works the same whether you're focused or half-asleep

Install

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

Sets up everything: Bun, tmux, Claude Code plugin, orchestration config. Update anytime with genie update.

Alternative: npm install

npm install -g @automagik/genie

Installs the CLI only. You'll need Bun 1.3.10+, tmux, and genie setup for full plugin integration.

Requirements: macOS or Linux, Claude Code

Quick Start

Interactive (you drive):

Step	Command
01. Launch	genie
02. Wish	/wish fix the authentication bug in the login flow
03. Ship	Genie asks questions, builds a plan, executes it. You approve the PR.

Autonomous (team-lead drives):

Step	Command
01. Plan	/wish — define scope, acceptance criteria, execution groups
02. Launch	genie team create auth-fix --repo . --wish auth-bug
03. Ship	Team-lead hires agents, dispatches work, runs review loops. You approve the PR.

Features

🧞 Wish Pipeline Brainstorm, plan, execute, review, ship — consistent results every time.	🤖 Autonomous Team-Lead genie team create --wish — team-lead hires agents, dispatches work, runs fix loops, and opens the PR. You approve.	🧠 Context Preservation Scoped specialists instead of one bloated window. No context rot.
💾 Persistent Memory Knowledge vault that agents search before answering. Compounds daily.	🔍 Automated Review Severity-tagged review. Nothing ships with CRITICAL or HIGH issues.	🌙 Overnight Execution Queue wishes before bed. Wake up to reviewed PRs.
👥 10-Critic Council 10 specialists critique your design before you commit to anything.	🎯 Behavioral Learning Genie adapts to your codebase conventions and preferences.	📦 Portable Context Identity, skills, memory — markdown files you own. Git-versioned.

Without Genie vs. With Genie

❌ Without Genie	✅ With Genie
Re-explain your codebase to Claude every session	Genie interviews you once. Context flows to every agent.
Copy-paste requirements, hope it understood	/wish captures scope and acceptance criteria upfront
One Claude tab per task, alt-tab between 5 of them	Parallel agents in live terminal sessions
Eyeball generated code, miss a bug, fix at 2am	Automated /review with severity-tagged gaps
45 min in, Claude forgets your instructions	Scoped specialists — no context window accumulates junk
10 min of setup before any work starts	genie team create auth-fix --repo . --wish auth-bug — team-lead handles the rest

The Wish Pipeline

💭 /brainstorm → 🧞 /wish → ⚙️ /work → 🔍 /review → 🚀 ship

Stage	What happens
Brainstorm	Think out loud. Genie asks clarifying questions until the idea is concrete.
Wish	Crystallize intent into a plan with scope and acceptance criteria.
Work	Agents spawn in isolated worktrees, execute in parallel.
Review	Automated review with severity gates. Nothing merges without passing.
Ship	PR created, checks pass, you merge.

CLI Reference

Entry point:

Command	Description
genie	Persistent session in current directory
genie --session <name>	Named/resumed leader session

Team (autonomous execution):

Command	Description
genie team create <name> --repo <path>	Form team + git worktree
genie team create <name> --repo <path> --wish <slug>	Form team and auto-spawn team-lead with wish context
genie team hire <agent>	Add agent to team
genie team hire council	Hire all 10 council members
genie team fire <agent>	Remove agent from team
genie team ls [<name>]	List teams or team members
genie team done <name>	Mark team done, kill all members
genie team blocked <name>	Mark team blocked, kill all members
genie team disband <name>	Kill members, remove worktree, delete config

Dispatch (lifecycle orchestration):

Command	Description
genie brainstorm <agent> <slug>	Spawn agent with brainstorm context
genie wish <agent> <slug>	Spawn agent with design for wish creation
genie work <agent> <slug>#<group>	Check deps, set in_progress, spawn with context
genie review <agent> <slug>#<group>	Spawn agent with review scope
genie done <slug>#<group>	Mark group done, unblock dependents
genie reset <slug>#<group>	Reset in-progress group back to ready
genie status <slug>	Show wish group states

Agent lifecycle:

Command	Description
genie spawn <name>	Spawn registered agent or built-in role
genie kill <name>	Force kill agent
genie stop <name>	Stop current run, keep pane alive
genie ls	List agents, teams, state
genie history <name>	Compressed session timeline
genie read <name>	Tail agent pane output
genie answer <name> <choice>	Answer agent prompt

Messaging:

Command	Description
genie send '<msg>' --to <name>	Direct message (scoped to own team)
genie broadcast '<msg>'	Leader to all team members
genie chat '<msg>'	Team group channel
genie chat read	Read team channel history
genie inbox [<name>]	View inbox

Directory (agent registry):

Command	Description
genie dir add <name>	Register agent (--dir, --prompt-mode, --model, --roles)
genie dir rm <name>	Remove agent from directory
genie dir ls [<name>]	List all or show single entry
genie dir edit <name>	Update entry fields

Infrastructure:

Command	Description
genie setup	Interactive setup wizard
genie doctor	Diagnose configuration issues
genie update	Update to latest version (--next for dev builds, --stable for releases)
genie shortcuts show|install|uninstall	tmux keyboard shortcuts

Configuration

Agent Directory

Register custom agents with a directory path, prompt mode, and optional model. Built-in roles (engineer, reviewer, qa, fix, refactor, trace, docs, learn, council) are available out of the box.

genie dir add my-agent --dir /path/to/agent --prompt-mode append
genie dir ls                          # List all registered agents
genie dir ls --builtins               # Include built-in roles
genie dir edit my-agent --model opus  # Update config
genie dir rm my-agent                 # Remove registration

Worktrees

Teams work in isolated git worktrees so agents never conflict with your working tree.

~/.genie/worktrees/<project>/<team>/

Configurable via genie setup --terminal → worktreeBase. Worktrees are created on genie team create and cleaned up on genie team disband.

Setup

genie setup              # Interactive wizard (hooks, terminal, shortcuts, sessions)
genie setup --quick      # Recommended defaults
genie setup --show       # Show current configuration
genie setup --reset      # Reset to defaults

Config Files

File	Purpose
~/.genie/config.json	Terminal settings, session config, worker profiles
~/.claude/settings.json	Claude Code settings (hooks registered here)

Development

bun run build     # Build CLI
bun run check     # Typecheck + lint + dead-code + test
bun test          # Run tests
genie doctor      # Diagnose issues

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

---

GitHub · Discord · MIT License

_{You make the decisions. Genie does everything else.}