Genie Hacks

Hacks Registry

The canonical hacks live in the docs at genie/hacks.mdx. Below is the embedded registry for list, search, show, and help commands. Use this data directly — do not require an external file.

hack: provider-switching

• ID: provider-switching
• Title: Provider Switching — Right Model for the Job
• Category: providers
• Problem: You're using one provider for everything, but some tasks need speed (Codex) and others need precision (Claude).
• Solution: Use --provider flag to switch per-task. Configure provider per agent role in team config.
• Code:

  # Fast scaffolding with Codex
  genie agent spawn engineer --provider codex
  
  # Careful review with Claude
  genie agent spawn reviewer --provider claude
  
  # Team-level: set default per role
  genie team create my-feature --repo . --wish my-slug
  genie team hire engineer --provider codex
  genie team hire reviewer --provider claude
  

• Benefit: 2-3x faster scaffolding with Codex, higher-quality reviews with Claude. Match the model to the cognitive demand.
• When to use: Teams with mixed workloads — boilerplate generation vs. nuanced code review. When cost or speed matters per task.

hack: team-coordination

• ID: team-coordination
• Title: Multi-Team Coordination at Scale
• Category: teams
• Problem: You have multiple wishes that depend on each other, and running them sequentially wastes time.
• Solution: Use /dream to batch-execute wishes with dependency ordering. Same-layer wishes run in parallel.
• Code:

  # Queue wishes for overnight execution
  /dream
  
  # Or manually create parallel teams
  genie team create auth-refactor --repo . --wish auth-refactor
  genie team create api-v2 --repo . --wish api-v2
  
  # Monitor both
  genie task status auth-refactor
  genie task status api-v2
  
  # Cross-team messaging
  genie agent send 'auth-refactor is done, you can proceed' --to api-v2-team-lead
  

• Benefit: Parallel execution of independent wishes. Overnight batch runs that produce PRs by morning.
• When to use: Projects with 3+ wishes queued. Sprint planning where multiple features can be parallelized.

hack: overnight-batch

• ID: overnight-batch
• Title: Overnight Batch Execution with /dream
• Category: batch
• Problem: You have a backlog of approved wishes but limited daytime hours to supervise execution.
• Solution: Use /dream to queue SHIP-ready wishes, set dependency order, and let agents execute overnight. Wake up to PRs and a DREAM-REPORT.md.
• Code:

  # 1. Ensure wishes are in brainstorm.md under "Poured"
  cat .genie/brainstorm.md
  
  # 2. Launch dream run
  /dream
  # Select wishes: 1 3 5 (or "all")
  # Confirm DREAM.md execution plan
  # Go to sleep
  
  # 3. Morning: check results
  cat .genie/DREAM-REPORT.md
  gh pr list --author @me
  

• Benefit: 8+ hours of unattended execution. Multiple PRs ready for review by morning.
• When to use: End of day with 2+ SHIP-ready wishes. Sprint velocity needs a boost without more human hours.

hack: custom-skills

• ID: custom-skills
• Title: Custom Skills for Repeated Workflows
• Category: skills
• Problem: You keep typing the same sequence of commands or giving the same instructions repeatedly.
• Solution: Create a custom skill in skills/<name>/SKILL.md with YAML frontmatter. Claude loads it when invoked via /<name>.
• Code:

  mkdir -p skills/deploy-check
  cat > skills/deploy-check/SKILL.md << 'EOF'
  ---
  name: deploy-check
  description: "Pre-deploy checklist — tests, migrations, env vars."
  ---
  # /deploy-check
  1. Run `bun test`
  2. Check migrations: `bunx prisma migrate status`
  3. Verify env vars are set
  4. Build: `bun run build`
  5. Report pass/fail table
  EOF
  
  # Use it
  /deploy-check
  

• Benefit: Encode tribal knowledge as reusable skills. New team members get instant access to workflows.
• When to use: Any workflow you've explained more than twice. CI-like checks you want to run locally before pushing.

hack: hook-automation

• ID: hook-automation
• Title: Git Hook Automation with Genie Hooks
• Category: hooks
• Problem: You want agents to automatically react to git events — spawning a reviewer on PR creation, running tests on commit.
• Solution: Use Genie's hook system and Claude Code hooks in .claude/settings.json to trigger actions on events.
• Code:

  # Auto-spawn is built in — set GENIE_AGENT_NAME for dispatch:
  export GENIE_AGENT_NAME=my-agent
  
  # Claude Code hook example (.claude/settings.json):
  {
    "hooks": {
      "PreToolUse": [{
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "echo 'Tool being used: Bash'"
        }]
      }]
    }
  }
  

• Benefit: Automated reactions to development events. Less manual orchestration.
• When to use: Teams wanting CI-like automation within the agent workflow. Projects where wish-to-PR should be fully autonomous.

hack: cost-optimization

• ID: cost-optimization
• Title: Cost Optimization Strategies
• Category: cost
• Problem: Agent usage costs add up, especially with large teams or long-running dream runs.
• Solution: Provider switching (Codex for bulk, Claude for review), tight wish scoping, /refine for prompt optimization, and usage monitoring.
• Code:

  # 1. Cheaper providers for boilerplate
  genie team hire engineer --provider codex
  genie team hire reviewer --provider claude
  
  # 2. Tight wish scoping
  # BAD: "Refactor the entire codebase"
  # GOOD: "Extract auth middleware into src/middleware/auth.ts"
  
  # 3. Refine prompts before dispatching
  /refine
  
  # 4. Monitor token usage
  genie agent log engineer --transcript --ndjson | jq '.tokens' | paste -sd+ | bc
  

• Benefit: 30-50% cost reduction by matching provider to task complexity. Tighter scoping means fewer fix loops.
• When to use: Budget-conscious teams. High agent concurrency. Before scaling to /dream batch runs.

hack: integration-patterns

• ID: integration-patterns
• Title: Integration Patterns — Connect Genie to Your Stack
• Category: integration
• Problem: You want Genie to integrate with existing tools — Slack notifications, CI/CD pipelines, monitoring.
• Solution: Use shell commands in skills for custom integrations, GitHub CLI for PR/issue management, webhooks for notifications.
• Code:

  # Post to Slack via webhook
  curl -X POST "$SLACK_WEBHOOK_URL" \
    -H 'Content-Type: application/json' \
    -d '{"text": "Genie: wish auth-refactor done. PR #123"}'
  
  # Create GitHub issues from findings
  gh issue create --title "Bug: auth token expiry" \
    --body "Found during /trace: refresh fails silently"
  
  # Trigger CI after PR
  gh workflow run ci.yml --ref feat/my-feature
  

• Benefit: Genie becomes part of your existing workflow. Notifications go where your team already looks.
• When to use: Teams with Slack/Discord channels. Projects with CI/CD pipelines that should trigger on agent PRs.

hack: debugging-tips

• ID: debugging-tips
• Title: Debugging Agent Issues Like a Pro
• Category: debugging
• Problem: An agent is stuck, producing wrong output, or a team isn't making progress.
• Solution: Use genie agent log --raw for live output, genie agent log --transcript for transcripts, /trace for root cause analysis, and genie reset for recovery.
• Code:

  # Live agent output
  genie agent log engineer --raw
  
  # Compressed timeline
  genie agent log engineer --transcript
  
  # Filter to tool calls
  genie agent log engineer --transcript --ndjson | jq 'select(.type == "tool_use") | .name'
  
  # Systematic investigation
  /trace
  
  # Check team status
  genie team ls my-team
  genie task status my-wish-slug
  
  # Unstick a blocked group
  genie reset my-wish-slug#2
  

• Benefit: Full visibility into agent behavior. Systematic debugging instead of guessing.
• When to use: Agent taking too long. Output quality dropping. Team progress stalled. Post-mortem on failed dream run.

Command: list

Display all hacks from the registry in a formatted table.

Output format:

Genie Hacks — Community Patterns & Tips

| ID                   | Title                                    | Category    |
|----------------------|------------------------------------------|-------------|
| provider-switching   | Provider Switching — Right Model for Job | providers   |
| team-coordination    | Multi-Team Coordination at Scale         | teams       |
| overnight-batch      | Overnight Batch Execution with /dream    | batch       |
| custom-skills        | Custom Skills for Repeated Workflows     | skills      |
| hook-automation      | Git Hook Automation with Genie Hooks     | hooks       |
| cost-optimization    | Cost Optimization Strategies             | cost        |
| integration-patterns | Integration Patterns — Connect to Stack  | integration |
| debugging-tips       | Debugging Agent Issues Like a Pro        | debugging   |

8 hacks available. Run `/genie-hacks show <id>` for details.
Contribute your own: `/genie-hacks contribute`

Command: search <keyword>

Search hack titles, problems, solutions, and code for the keyword (case-insensitive). Display matching hacks.

Output format:

Search results for "<keyword>":

1. [provider-switching] Provider Switching — Right Model for the Job
   Problem: You're using one provider for everything...
   Category: providers

2. [cost-optimization] Cost Optimization Strategies
   Problem: Agent usage costs add up...
   Category: cost

2 hacks matched. Run `/genie-hacks show <id>` for full details.

If no matches: No hacks found for "<keyword>". Try broader terms or run /genie-hacks list to browse all.

Command: show <hack-id>

Display the full hack with all fields. Look up by exact ID (case-insensitive).

Output format:

## <Title>

**Category:** <category> | **ID:** `<hack-id>`

### Problem
<problem text>

### Solution
<solution text>

### Code
<code block>

### Benefit
<benefit text>

### When to Use
<when-to-use text>

---
Found this useful? Share your own: `/genie-hacks contribute`
Full docs: https://docs.automagik.dev/genie/hacks

If not found: Hack "<id>" not found. Did you mean: <suggest closest IDs>? Run /genie-hacks list to see all.

Command: help <problem>

Fuzzy-match a problem description to relevant hacks. Extract keywords, score by overlap across all fields, show top 3.

Keyword mapping hints:

• "speed", "fast", "slow" → provider-switching, cost-optimization
• "cost", "expensive", "budget", "tokens" → cost-optimization, provider-switching
• "team", "parallel", "coordinate", "multiple" → team-coordination, overnight-batch
• "overnight", "batch", "sleep", "queue" → overnight-batch, team-coordination
• "repeat", "workflow", "automate", "reuse" → custom-skills, hook-automation
• "hook", "event", "trigger", "auto" → hook-automation, custom-skills
• "slack", "ci", "integrate", "notify" → integration-patterns
• "stuck", "debug", "broken", "error", "fail" → debugging-tips
• "codex", "claude", "model", "provider" → provider-switching
• "dream", "night", "unattended" → overnight-batch

Output format:

Based on your problem: "<problem>"

Best matches:

1. [provider-switching] Provider Switching — Right Model for the Job
   Why: Matches your need for speed/cost optimization across providers
   Quick tip: Use `genie agent spawn engineer --provider codex` for fast scaffolding

2. [cost-optimization] Cost Optimization Strategies
   Why: Directly addresses cost reduction techniques
   Quick tip: Scope wishes tightly and use `/refine` before dispatching

3. [team-coordination] Multi-Team Coordination at Scale
   Why: Parallel execution reduces wall-clock time
   Quick tip: Use `/dream` for batch overnight execution

Run `/genie-hacks show <id>` for full details on any hack.

If no reasonable matches: No hacks closely match your problem. Try describing it differently, or run /genie-hacks list to browse all. Got a solution? Run /genie-hacks contribute!

Command: contribute

Overview

Guide the user through contributing a new hack to the community docs via an automated PR to automagik-dev/docs. This is the full end-to-end flow.

Step 1: Gather Hack Details

Prompt the user for each field interactively. Wait for each response before proceeding.

Prompt sequence:

1. Title: "What's your hack title? (short, descriptive)"

   • Example: "Provider Switching for Speed vs Safety"

2. Problem: "What problem does it solve? (1-2 sentences)"

   • Example: "Different tasks need different AI providers — speed for scaffolding, careful reasoning for security-sensitive code."

3. Solution: "How does it work? Show the commands, config, or code. (Use code blocks)"

   • Example: multi-line code block with genie commands

4. Category: "What category? Pick one: providers | teams | skills | hooks | cost | integration | debugging | batch | other"

   • Validate input is one of the allowed categories. If invalid, re-prompt.

5. Benefit: "What's the key benefit? (one line)"

   • Example: "Right tool for each job — 3x faster scaffolding, safer reviews."

6. When to use: "When should someone use this? (one line)"

   • Example: "When your project has both speed-critical and safety-critical tasks."

Step 2: Preview & Confirm

Format the hack in the standard template and show the user:

### <Title>

**ID:** `<generated-id>`
**Category:** <category>

**Problem:** <problem>

**Solution:**

<solution with code blocks>

**Benefit:** <benefit>

**When to use:** <when>

Ask: "Does this look good? (yes/edit/cancel)"

• yes → proceed to Step 3
• edit → ask which field to change, re-prompt for that field, re-preview
• cancel → abort with "No worries! Run /genie-hacks contribute anytime."

Step 3: GitHub CLI Preflight

Run these checks in order. Stop at first failure with a helpful error.

# 1. Check gh is installed
command -v gh >/dev/null 2>&1
# If missing: "GitHub CLI (gh) is required. Install: https://cli.github.com/"

# 2. Check gh is authenticated
gh auth status 2>&1
# If not authenticated: "Run `gh auth login` to authenticate with GitHub first."

# 3. Check git is available
command -v git >/dev/null 2>&1
# If missing: "git is required but not found in PATH."

If any check fails, display the error message and suggest manual steps:

Manual contribution steps:
1. Fork https://github.com/automagik-dev/docs
2. Edit genie/hacks.mdx — add your hack in the correct category section
3. Commit: git commit -m "hack: <title>"
4. Open PR to automagik-dev/docs (base: dev)

Step 4: Fork & Clone

# Cache directory for docs repo
DOCS_CACHE="$HOME/.genie/cache/docs-fork"

# Fork the docs repo (idempotent — no-op if already forked)
gh repo fork automagik-dev/docs --clone=false 2>/dev/null || true

# Get the user's GitHub username for the fork URL
GH_USER=$(gh api user --jq '.login')

# Clone or update the cached fork
if [ -d "$DOCS_CACHE/.git" ]; then
  cd "$DOCS_CACHE"
  git fetch origin
  git checkout dev
  git pull origin dev
else
  gh repo clone "$GH_USER/docs" "$DOCS_CACHE" -- --branch dev
  cd "$DOCS_CACHE"
  git remote add upstream https://github.com/automagik-dev/docs.git 2>/dev/null || true
  git fetch upstream
fi

# Create a branch for the hack
BRANCH="hack/$(echo '<title>' | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')"
git checkout -b "$BRANCH" origin/dev

If clone/fork fails, show the error and fall back to manual steps (same as Step 3 fallback).

Step 5: Append Hack to hacks.mdx

Read genie/hacks.mdx from the cloned repo. Find the correct category section (look for ## <Category> heading — e.g., ## Providers, ## Teams, etc.). Append the new hack entry just before the next ## heading or at the end of the category section.

If the category section doesn't exist (e.g., for other), append a new section at the end of the file, before the Contributing section:

## Other

### <Title>

**ID:** `<generated-id>`

**Problem:** <problem>

**Solution:**

<solution>

**Benefit:** <benefit>

**When to use:** <when>

---

Step 6: Commit & Push

cd "$DOCS_CACHE"
git add genie/hacks.mdx
git commit -m "hack: <title>"
git push -u origin "$BRANCH"

Step 7: Create PR

# Create PR targeting the dev branch of the upstream docs repo
PR_URL=$(gh pr create \
  --repo automagik-dev/docs \
  --base dev \
  --head "$GH_USER:$BRANCH" \
  --title "hack: <title>" \
  --body "$(cat <<'PREOF'
## New Community Hack

**Title:** <title>
**Category:** <category>
**Problem:** <problem>

**Solution:**
<solution summary>

**Benefit:** <benefit>
**When to use:** <when>

---

*Submitted via `/genie-hacks contribute`*
PREOF
)")

echo "PR created: $PR_URL"

Step 8: Success

Display the result to the user:

Your hack has been submitted!

PR: <PR_URL>
Title: hack: <title>
Target: automagik-dev/docs (dev branch)

What happens next:
- A maintainer will review your hack
- They may suggest edits via PR comments
- Once approved, it'll appear on the hacks page

Thank you for contributing to the Genie community!
Join the discussion on Discord: https://discord.gg/automagik

Error Recovery

At any point if a step fails:

Offline / Manual Fallback

If GitHub operations fail entirely, save the hack locally and guide the user:

# Save hack to local file
mkdir -p ~/.genie/cache/pending-hacks
cat > ~/.genie/cache/pending-hacks/<hack-id>.md << 'EOF'
<formatted hack content>
EOF

Then display:

Saved your hack locally at: ~/.genie/cache/pending-hacks/<hack-id>.md

To submit manually:
1. Fork https://github.com/automagik-dev/docs
2. Copy the hack content into genie/hacks.mdx under the "<category>" section
3. Commit with message: "hack: <title>"
4. Open PR targeting the `dev` branch

Categories Reference

Docs Cache

The docs repo is cached at ~/.genie/cache/docs-fork/ to avoid re-cloning on every contribute. The cache is updated (git pull) on each contribute invocation. If the cache becomes corrupted, delete it and re-run — the contribute flow will re-clone automatically.

Rules

• All hack IDs are lowercase kebab-case.
• Never invent hacks that don't exist in the registry — only show what's listed above.
• For help, always try to find at least one relevant hack. Only say "no matches" if truly nothing fits.
• Keep output concise — tables for list, full format only for show.
• Always end list and show with a nudge toward contribute.
• The contribute command should be friendly and low-friction — one question at a time.
• Link to Discord (https://discord.gg/automagik) for community discussion.
• Link to docs (https://docs.automagik.dev/genie/hacks) for the full hacks page.
• Always target the dev branch for PRs — never main/master.
• Hack IDs must be unique — check existing IDs before appending.
• All hacks must be realistic and tested — do not submit aspirational or untested patterns.
• Preserve the standard format: problem, solution, code, benefit, when to use.
• Keep code examples concise — show the minimum needed to understand the hack.