Genie Hacks
These are patterns from working with Genie every day: habits that save a review round, a wasted run or a confused afternoon. Each one uses commands and skills that exist in the current release.
genie --help is the source of truth, and the CLI reference has its output.Browse them from your agent: the
genie-hacks skill lists, searches and shows these entries, and genie-hacks contribute helps you submit one.Got one we missed? Contribute it, or bring it to Discord.
Planning
Let one task skip the plan
ID:
one-task-skips-the-plan
Category: planningProblem: A change that fits in one sentence gets a
WISH.md, a plan review and a dispatch before anyone touches the code.Solution: Hand
wish one decided task. It 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. Only work bigger than one task becomes a WISH.md.1/wish rename the --lane flag to --to across task move and its tests
Benefit: A decided change ships in one pass, and plans are kept for the work that needs them.
When to use: When the whole change and the way to check it fit in a sentence. If you find yourself writing "and also", it is a wish.
Lint the wish before anything acts on it
ID:
lint-the-wish-first
Category: planningProblem: An agent works against a wish whose group has no acceptance criteria, and the review has nothing to check against.
Solution: Run
genie wish lint over the repository's .genie/wishes. It checks the template sections, the metadata and every link into .genie/brainstorms/, writes nothing, and exits non-zero when it finds a problem, so it fits a pre-commit hook or a CI step. A --dir you type that does not resolve is refused instead of reported clean.12genie wish lint # this repository genie wish lint --dir ../other # any other checkout
Benefit: A malformed plan fails before an execution wave is spent on it.
When to use: In CI, and by hand right after you write a large plan, before you approve it.
Parallel
Shape groups for waves
ID:
shape-groups-for-waves
Category: parallelProblem: A wish with many groups runs almost one group at a time, because every group quietly depends on the one before it.
Solution: Dependencies decide the waves, so write each group's
depends-on deliberately and keep independent work independent. work runs each wave through your agent's own subagents, and groups that share no dependency run together.12genie board # the live kanban, derived by query genie task status <task-id> # dependencies, stage log, assignment
Benefit: A wish takes about as long as its longest chain of dependencies, and the bottleneck moves to review.
When to use: Any wish whose groups touch different files.
One database, every worktree
ID:
one-database-every-worktree
Category: parallelProblem: Work fans out into several git worktrees, and every one of them needs to see the same tasks.
Solution: Genie already shares them. Every linked worktree resolves the same
.genie/genie.db through the git common directory, so there is no sync step between worktrees. The board snapshot .genie/roadmap.json is the one piece of task state that lives in git, and genie task sync reconciles it with the database.12git worktree add ../feature-x -b feature-x (cd ../feature-x && genie task list) # the same cards, from the same database
Benefit: Each worktree keeps its own files, and the task state stays whole.
When to use: Every time work fans out.
Teams
Coordinate several wishes
ID:
team-coordination
Category: teamsProblem: Several approved wishes depend on each other, and running them one at a time wastes time.
Solution: Run each approved wish with
work, in the order its depends-on edges give. Independent wishes can run in parallel through your agent's subagents; give parallel writers disjoint files or their own worktrees. The shared database shows all of them from any terminal.123genie board --wish auth-refactor genie board --wish api-v2 genie task list --status in_progress
Benefit: Independent wishes run side by side, with one view of their state.
When to use: When several approved wishes are queued at once.
Providers
Pick the model per stage of a wish run
ID:
provider-switching
Category: providersProblem: One model serves every stage of a run, although reading a check's result and reviewing a diff need very different strength.
Solution: In Claude Code, the
wish workflow already splits its stages into tiers: the worker stages (scout, gate, publisher) run on a faster model, and the reasoner stages (judge, executor, reviewer, repair) on a stronger one. Name a model in your request to change that. The wish skill takes model, which pins one model for every stage, and gateModel and publishModel, which pin only the gate (it runs your check and reads the exit code) and the publisher (it pushes and opens the pull request) and win over model. In other agents the skill runs the same stages by hand, and your agent's own settings choose the model.1/wish rename the --lane flag to --to across task move and its tests; use <model> for the gate and the publisher
Benefit: The mechanical stages stop running on a model they do not need, and the stages that judge the work keep the strongest one.
When to use: Any run whose check is long and simple to read, or when you want one specific model from start to finish.
Skills
Turn a repeated procedure into a skill
ID:
custom-skills
Category: skillsProblem: You keep typing the same sequence of steps for a recurring task, and explaining it every time is slow and error-prone.
Solution: Write it down as a skill: a folder holding a
SKILL.md with YAML frontmatter (a name and a description) and the instructions. Put it in your agent's skills home, ~/.claude/skills/<name>/ for Claude Code or ~/.agents/skills/<name>/ for Codex and the other agents that read it, and the agent runs it by name. When the procedure should run the same way every time in Claude Code, the workfly skill turns it into a saved workflow.123456789101112131415161718192021222324# Create your custom skill mkdir -p ~/.claude/skills/reset-dev cat > ~/.claude/skills/reset-dev/SKILL.md << 'EOF' --- name: reset-dev description: "Reset the dev environment: migrate, seed, restart" --- # Reset Dev Environment Run these steps in order: 1. **Stop services:** `docker compose down` 2. **Reset database:** `docker compose run --rm api rails db:reset` 3. **Run migrations:** `docker compose run --rm api rails db:migrate` 4. **Seed data:** `docker compose run --rm api rails db:seed` 5. **Start services:** `docker compose up -d` 6. **Verify:** `curl -s http://localhost:3000/health | jq .status` Report the health check result when done. EOF # Now use it anytime: # /reset-dev
Benefit: Your team's know-how becomes a versioned skill that every new teammate, human or agent, runs the same way.
When to use: Any procedure you keep explaining: deploying to staging, running a specific test suite, regenerating API docs.
Teach a microagent the repository's own taste
ID:
microagent-taste
Category: skillsProblem: A general model keeps missing conventions everyone on the team knows, and you cannot tell whether a prompt change helped.
Solution:
genie mikro runs repository-local microagents: a prompt plus an answer schema, whose answer is validated JSON with every citation checked against the tree. Seed the default agents, build a fixture set from your own commits, score the agent mechanically, then run a coaching round that patches a copy of the prompt and benches it before and after. genie mikro init prints the prerequisites your host needs and the next steps.12345genie mikro init genie mikro fixtures --from-commits <range> --agent wish-context genie mikro bench wish-context genie mikro coach wish-context --null-control # the drift band; run it first genie mikro coach wish-context
Benefit: A prompt change gets a before and after score over fixtures drawn from your own history.
When to use: Any narrow judgement that repeats, where the same conventions would otherwise be explained again in every prompt.
Ops
Read doctor's JSON
ID:
read-doctors-json
Category: opsProblem:
genie doctor prints one summarized line per check, which is easy to read and hard to script.Solution:
genie doctor --json carries every entry behind each summarized line. Doctor only observes the skills channel: even --fix leaves it alone, and genie update owns every change there.1genie doctor --json | jq '.checks[] | select(.status == "warn") | .name'
Benefit: The full list without scrolling, and the same command works in CI.
When to use: Whenever a script or a CI step acts on doctor's output.
Tighten a budget in config
ID:
tighten-budgets-in-config
Category: opsProblem: The repair loop should give up sooner on your machine.
Solution: Budgets live in Genie's global config,
~/.genie/config.json, and the skills read them through the CLI instead of restating a number. Configuration can only tighten a gate: every key has a ceiling in the schema, and a value past it makes the whole file fall back to the defaults, which genie config get --json reports as "source": "default".12genie config get budgets.maxEscalationsPerGroup genie config get budgets.maxEscalationsPerGroup --json
Benefit: One place to change it, and no drift between the config and what a skill believes.
When to use: When the repair loop spends its budget on work that should go back to review.
Cost
Spend where the work needs it
ID:
cost-optimization
Category: costProblem: Agent usage adds up over long runs and many parallel wishes.
Solution: Scope each task tightly, so the agent has a clear finish line: "extract the auth middleware into
src/middleware/auth.ts" instead of "refactor the codebase". Run the refine skill on a brief before you hand it to an agent, and put the mechanical stages of a wish run on a faster model (Pick the model per stage of a wish run). Then read what a run really cost from its own record: in Claude Code, genie wish report <runId> prints the tokens and time of each stage of a saved workflow run.1genie wish report <runId> # tokens and time per stage of one saved workflow run
Benefit: Spend follows how hard each task is, and you measure it on your own runs.
When to use: Before you scale up parallel
work runs, or when a run costs more than the change was worth.Integration
Send results where your team already looks
ID:
integration-patterns
Category: integrationProblem: Your team watches chat and CI, and the result of a run should show up there.
Solution: Prefer the connectors your agent already has for GitHub and chat, and use the shell or a webhook only for what they do not cover. Every outward write (a chat message, an issue, a workflow dispatch) needs your explicit go-ahead and an exact target. The
report skill follows the same rule: it files a GitHub issue only when you ask.1234curl -X POST "$SLACK_WEBHOOK_URL" -H 'Content-Type: application/json' \ -d '{"text": "Genie: wish auth-refactor is ready for review"}' gh issue create --title "Bug: auth token expiry" --body-file report.md gh workflow run ci.yml --ref feat/my-feature
Benefit: Results land where people already look, and nothing leaves your machine without a decision.
When to use: Teams with chat channels or pipelines that should react to an agent's pull request.
Debugging
Find where a run is stuck
ID:
debugging-tips
Category: debuggingProblem: An agent is stuck, its output is wrong, or a run stopped making progress.
Solution: Use the
report skill for a root-cause investigation; it files an issue only when you ask. genie doctor checks the install, and the task state shows where the work stopped. Before you re-claim a task that is still in_progress, confirm who holds the claim and that the worker is gone. genie task done is the orchestrator's call, after the work is reviewed.12345genie doctor # install health genie task list --status blocked # blocked cards genie task status <task-id> # dependencies and stage log genie board --wish my-wish-slug genie task export # the whole state as JSON, for a post-mortem
Benefit: You investigate with evidence and stop guessing.
When to use: A slow agent, a drop in output quality, a stalled run, or a post-mortem.
Other
Automate with your agent's own hooks
ID:
hook-automation
Category: otherProblem: You want automatic reactions to development events, such as blocking an unsafe tool call or tagging work with an agent's identity.
Solution: Genie installs no hooks into any agent. If your agent offers hooks, follow its own documentation for the hook surface and schema. Keep hook commands deterministic and local, review each one before you trust it, and never use a hook to install or update software silently.
1export GENIE_AGENT_NAME=my-agent # the identity genie task checkout uses by default
Benefit: Automation you have reviewed and can see, with no hidden workflow behind it.
When to use: CI-like checks inside your agent's workflow, once you have confirmed how its hooks work.
Contributing
Have a hack that is not here? The best entries come from people who hit the problem.
The quickest path is the
genie-hacks skill: genie-hacks contribute asks for each field, shows you a preview and opens the pull request after you confirm it.Format
Every entry follows this template. Keep it concrete, and use only commands that exist in the current release.
12345678910111213141516### Your hack title **ID:** `your-hack-id` **Category:** <category> **Problem:** What situation does this solve? **Solution:** How does it work? \`\`\`bash # Concrete commands or code \`\`\` **Benefit:** What do you gain? **When to use:** In what situations should someone reach for this?
The ID is lowercase kebab-case and must not collide with an existing ID on this page.
Categories
| Category | ID | Examples |
| Planning | planning | Task or wish, acceptance criteria, linting a plan |
| Parallel | parallel | Wave shape, worktrees, the shared per-repository database |
| Ops | ops | Doctor, budgets, install hygiene, release verification |
| Providers | providers | Model selection per stage or per role |
| Teams | teams | Coordinating several wishes |
| Skills | skills | Custom skills, microagents, automation |
| Cost | cost | Token use, model routing, budget control |
| Integration | integration | External tools, APIs, CI/CD, chat notifications |
| Debugging | debugging | Stuck runs, wrong output, post-mortems |
| Other | other | Anything else |
Submit a pull request by hand
1234567891011# 1. Fork and clone the docs repository gh repo fork automagik-dev/docs --clone cd docs git checkout -b hack/<your-hack-id> # 2. Add your entry at the end of its category section in genie/hacks.mdx # 3. Commit and open the pull request git add genie/hacks.mdx git commit -m "hack: your hack title" gh pr create --title "hack: your hack title"
Ask AI about this page