etanhey/repogolem

repoGolem — Unified Launcher System

Every project has launchers: {name}Claude, {name}Codex, {name}Cursor, {name}Gemini, {name}Kiro. The launcher handles EVERYTHING: cd to repo, MCP wiring, secrets, iTerm profile, badge. You NEVER need source ~/.zshrc && cd ~/Gits/X && claude -s. Just: brainlayerClaude -s.

---

UNIFIED FLAGS (same across ALL CLIs)

| Flag | Short | What It Does | Claude | Codex | Cursor | |------|-------|-------------|--------|-------|--------| | Skip permissions | -s | Auto-approve tool calls | --dangerously-skip-permissions | --dangerously-bypass-approvals-and-sandbox | --yolo --approve-mcps | | Continue/resume | -c | Resume last session | --continue | Resume last | (no-op, not supported) | | Model override | -m <model> | Use specific model | Model string | gpt-5.5 default (recommended per Codex CLI 2026-04-23 announcement; previously gpt-5.4) | Cursor model string | | Headless/print | -p "prompt" | Run and print (scripting) | --print -p "prompt" | Headless prompt | --print --output-format text | | Worktree | -w <path> | Launch from git worktree cwd | cd <path> | cd <path> | cd <path> |

CRITICAL:

• -s = skip permissions. Capital -S = Sonnet model (separate flag, Claude only)
• -p is for HEADLESS/SCRIPTING ONLY. For interactive use: brainlayerCursor -s then send prompt
• -c on Cursor is a no-op (not supported yet)

---

LAUNCHER NAME PATTERN

{projectName}{CLI}

Examples:
  brainlayerClaude    brainlayerCodex    brainlayerCursor
  golemsClaude        golemsCodex        golemsCursor
  orcClaude           orcCodex           orcCursor
  6pmClaude           6pmCodex           6pmCursor
  dashboardClaude     dashboardCodex     dashboardCursor

The name is the project key from ~/.config/ralphtools/registry.json, lowercased.

Agent-style projects

Registry entries can include an agent field:

{
  "yash": {
    "path": "/Users/etanheyman/Gits/golems",
    "agent": "yash",
    "clis": ["claude", "codex", "cursor", "gemini", "kiro"]
  }
}

Claude launchers pass this through as --agent <name>. Codex, Cursor, Gemini, and Kiro do not read Claude Agent SDK files directly, so repoGolem reads ~/.claude/agents/<name>.md and injects it as the launcher's initial prompt. It preserves the frontmatter initialPrompt block when present, strips the rest of the YAML metadata, then appends the Markdown body. This is intentional: yashCodex, yashCursor, yashGemini, and yashKiro should inherit the same agent protocol instead of acting like generic shells in the project directory.

WARNING — launcher names strip hyphens from repo names

repoGolem launcher names are generated from the registry key, not the raw repo folder name. If a repo name contains hyphens, the launcher drops them:

repo: skill-creator
wrong launcher guess: skill-creatorClaude
actual launcher:      skillcreatorClaude

This matters when another tool tries to build a launcher name from repo directly. Known live failure: mcp__cmux__spawn_agent({repo:"skill-creator", cli:"claude"}) guessed skill-creatorClaude, hit zsh: command not found, and left the agent stuck at booting.

Before relying on a generated launcher for a new repo, verify the real launcher first:

which skillcreatorClaude
which skillcreatorCodex
which skillcreatorCursor

If the launcher guess is wrong, use the verified repoGolem launcher manually until cmuxlayer normalizes repo -> launcher with the same hyphen-stripping rule.

---

KEY REGISTERED PROJECTS

| Project | Path | Launchers | |---------|------|-----------| | golems | ~/Gits/golems | golemsClaude, golemsCodex, golemsCursor | | brainlayer | ~/Gits/brainlayer | brainlayerClaude, brainlayerCodex, brainlayerCursor | | voicelayer | ~/Gits/voicelayer | voicelayerClaude, voicelayerCodex, voicelayerCursor | | orc (orchestrator) | ~/Gits/orchestrator | orcClaude, orcCodex, orcCursor | | dashboard | ~/Gits/golems-dashboard | dashboardClaude, dashboardCodex, dashboardCursor | | 6pm | ~/Gits/6pm-mini | 6pmClaude, 6pmCodex, 6pmCursor | | portfolio | ~/Gits/etanheyman.com | portfolioClaude, portfolioCodex, portfolioCursor | | domica | ~/Gits/domica | domicaClaude, domicaCodex, domicaCursor | | mehayom | ~/Gits/Mehayom-app | mehayomClaude, mehayomCodex, mehayomCursor | | cmuxlayer | ~/Gits/cmuxlayer | cmuxlayerClaude, cmuxlayerCodex, cmuxlayerCursor | | mcplayer | ~/Gits/mcplayer | mcplayerClaude, mcplayerCodex, mcplayerCursor | | metacomlayer | ~/Gits/metacomlayer | metacomlayerClaude, metacomlayerCodex, metacomlayerCursor | | qwan | ~/Gits/qwan-drill | qwanClaude, qwanCodex, qwanCursor | | coach | ~/Gits/golems/packages/coach | coachClaude, coachCodex, coachCursor | | jobs | ~/Gits/golems/packages/jobs | jobsClaude, jobsCodex, jobsCursor | | content | ~/Gits/golems/packages/content | contentClaude, contentCodex, contentCursor | | services | ~/Gits/golems/packages/services | servicesClaude, servicesCodex, servicesCursor | | skills | ~/Gits/golems | skillsClaude, skillsCodex, skillsCursor | | eval | ~/Gits/orchestrator | evalClaude, evalCodex, evalCursor | | maintenance | ~/Gits/orchestrator | maintenanceClaude, maintenanceCodex, maintenanceCursor | | recruiter | ~/Gits/recruiterGolem | recruiterClaude, recruiterCodex, recruiterCursor | | teller | ~/Gits/tellerGolem | tellerClaude, tellerCodex, tellerCursor | | monitor | ~/Gits/monitorGolem | monitorClaude, monitorCodex, monitorCursor | | rudy | ~/Gits/rudy-monorepo | rudyClaude, rudyCodex, rudyCursor | | songscript | ~/Gits/songscript | songscriptClaude, songscriptCodex, songscriptCursor | | union | ~/Gits/union | unionClaude, unionCodex, unionCursor | | ralph | ~/.config/ralph | ralphClaude, ralphCodex, ralphCursor | | taba | ~/Gits/taba | tabaClaude, tabaCodex, tabaCursor | | project2 | ~/Desktop | project2Claude, project2Codex, project2Cursor | | maakaf | ~/Gits/maakaf_home | maakafClaude, maakafCodex, maakafCursor |

---

USAGE PATTERNS

Interactive agent (most common)

brainlayerClaude -s          # Claude in brainlayer repo, skip-permissions
orcCodex -s                  # Codex in orchestrator repo, skip-permissions
golemsCursor -s              # Cursor in golems repo, skip-permissions

Continue/resume a session

brainlayerClaude -s -c       # Resume last Claude session in brainlayer
orcClaude --resume            # Session picker for orchestrator

Launch in a worktree

mcplayerCodex -s -w /tmp/mcplayer-gen10-track
metacomlayerClaude -s -w /tmp/metacomlayer-gen10-track

The launcher consumes -w/--worktree, changes directory to that path, and does not pass --worktree to the underlying CLI.

Headless/scripting (print output, no interactive)

brainlayerCursor -s -p "Audit all .py files for stubs"
# → runs cursor agent --yolo --approve-mcps --print --output-format text "prompt"

Model override

brainlayerClaude -s -m sonnet  # Use Sonnet instead of default Opus
orcCodex -s -m gpt-5.3         # Use GPT-5.3 instead of default 5.5

Via cmux (spawning from orchestrator)

spawn_agent({ repo: "brainlayer", cli: "codex", model: "codex", prompt: "Fix the FTS5 sync issue in search.py" })
→ returns agent_id

wait_for({ agent_id, target_state: "ready", timeout_ms: 120000 })
send_to_agent({ agent_id, text: "Keep the fix narrow and cite the changed file", press_enter: true })

NEVER do this:

# WRONG — raw CLI, no launcher
send_input(surface, "source ~/.zshrc && cd ~/Gits/brainlayer && codex --dangerously-bypass-approvals-and-sandbox")

---

WHAT LAUNCHERS HANDLE (so you don't have to)

1. cd to repo — changes to the correct directory
2. MCP wiring — builds .mcp.json from registry, merges with repo's .mcp.json
3. Secrets — sets up 1Password-backed env vars via ralph-secrets.zsh
4. iTerm profile — switches to "Golems" profile with correct font
5. Tab title + badge — sets emoji + project name (e.g., "🌔 golemsClaude")
6. BrainLayer project tag — worktree path becomes the project tag automatically (e.g., brainlayer-p0-hybrid → project:"brainlayer-p0-hybrid")

---

HOW TO ADD A NEW PROJECT

1. Edit ~/.config/ralphtools/registry.json:

"myproject": {
    "path": "/Users/etanheyman/Gits/myproject",
    "displayName": "My Project",
    "mcps": [],
    "secrets": {},
    "created": "2026-04-05T00:00:00Z",
    "clis": ["claude", "codex", "cursor"]
}

2. Regenerate launchers:

_ralph_generate_launchers_from_registry
source ~/.config/ralphtools/launchers.zsh

3. Verify: which myprojectClaude should resolve.

---

HOW TO ADD A NEW CLI TO ALL PROJECTS

Example: adding cursor to all 27 projects (done April 4, 2026):

1. Edit registry.json — add "cursor" to each project's clis array
2. Regenerate: _ralph_generate_launchers_from_registry
3. Source: source ~/.config/ralphtools/launchers.zsh
4. Verify: which brainlayerCursor for a few projects

---

CRITICAL GOTCHAS

-s is a LAUNCHER flag, not a Claude CLI flag

-s only works with repoGolem launchers (brainlayerClaude -s). When using raw claude --agent, you MUST spell out --dangerously-skip-permissions. Evidence: claude --agent skill-creator -s failed; had to use claude --agent skill-creator --dangerously-skip-permissions.

Codex: use default model, no flag needed

User correction: "Just use it with default; no need for the model flag." The default Codex model (currently gpt-5.5, previously gpt-5.4) is fine for code tasks. Don't add -m unless specifically asked.

Cursor model: expect default/Auto

User complained when Cursor defaulted to GPT-5.4 instead of Auto. Don't override with --model for Cursor data-gathering tasks.

-p is headless ONLY

For interactive agents (monitored via cmux), launch WITHOUT -p: brainlayerCursor -s. Then send prompt separately. -p is for scripted one-shot runs that print output and exit.

TROUBLESHOOTING

| Problem | Fix | |---------|-----| | command not found: brainlayerClaude | source ~/.config/ralphtools/launchers.zsh | | Launcher doesn't cd to repo | Check path in registry.json | | MCP not available in session | Check mcps array in registry.json, regenerate | | Wrong iTerm badge | Check emoji field in registry.json | | No launcher for a repo | Add to registry.json, regenerate (see above) | | --agent flag with -s | -s is a launcher flag, NOT a Claude flag. Use --dangerously-skip-permissions explicitly | | -force error on Cursor | Use --force (double dash), not -force |

---

INTEGRATION

| Skill | How repoGolem Integrates | |-------|-------------------------| | /agent-routing | Routing says WHO (Cursor/Codex/Claude). repoGolem says HOW to launch them. | | /cmux-agents | spawn_agent is the default visible-worker path; repoGolem still defines the launcher names underneath (R10) | | /orc | R10 iron rule: "Use repoGolem launcher functions. ALWAYS. NEVER raw CLI." | | /session-handoff | Agent resume table includes launcher commands for crash recovery |

---

REGISTRY LOCATION

~/.config/ralphtools/registry.json     — project definitions, MCP configs, CLI lists
~/.config/ralphtools/lib/ralph-registry.zsh  — generator (creates launcher functions)
~/.config/ralphtools/launchers.zsh     — auto-generated launcher functions (source this)