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> | ⛔ BANNED for agent sessions (2026-06-07 Etan order — see CRITICAL). Non-agent scripted one-shots only, Etan-asked | Model string | Codex model string | Cursor model string | | Headless/print | -p "prompt" | Scripted one-shot only; NOT agent sessions or verification gates | --print -p "prompt" | Headless prompt | --print --output-format text | | Worktree | -w <abs-path> | Launch from pre-created git worktree cwd | cd <path> | cd <path> | cd <path> |

CRITICAL:

• -s = skip permissions. Capital -S/--sonnet = Sonnet model (separate flag, Claude only)
• ⛔ NEVER pass -m to a launcher for an agent session — not even -m opus. -m opus resolves to PLAIN Opus 4.8 (200K) and SILENTLY KILLS the 1M pin (live incident 2026-06-07: voicelayerClaude -s -m opus booted "Opus 4.8 · Claude Max" with no 1M context; Etan, verbatim: "some of y'all just send the -M opus instead of just letting it spawn as the default, which is opus with 1 million. I fucking want this fixed now"). The BARE launcher IS the model policy. Same law as spawn_agent's model-param ban (#478) — this closes the launcher-flag half.
• Launcher defaults are the authoritative model source for agent sessions. Never pass model params through cmux spawn_agent; use repoGolem launchers as-is unless Etan explicitly asks for a model change.
• Claude launchers pin Opus 4.8 1M-context (claude-opus-4-8[1m]) by DEFAULT — they boot on the 1M model without a manual /model flip. Post-boot verify: the status bar must read "Opus 4.8 (1M context)" — plain "Opus 4.8" means the pin was lost; kill and respawn bare.
• -p is NOT for agent sessions or verification gates. Open scope: it may survive for non-agent scripted one-shots; confirm with Etan before using it in automation.
• -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

# Create the worktree FIRST — bare names fail silently
git -C ~/Gits/golems worktree add ~/Gits/golems.wt/my-task -b feat/my-task origin/master
golemsCodex -s -w /Users/etanheyman/Gits/golems.wt/my-task

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

The launcher consumes -w/--worktree, cds to the literal argument, and does not pass --worktree to the underlying CLI.

-w contract (gen-12 weave E16): the path must be a pre-created absolute worktree directory that already exists on disk. The launcher does NOT resolve bare names, create worktrees, or fall back to the main checkout.

WRONG: golemsCodex -s -w weave-edits-a
       → _golem_launch_codex:cd:22: no such file or directory: weave-edits-a
       → 120s boot-timeout waiting for a pane that never started (ea8514a2:[643])
RIGHT: git worktree add … then golemsCodex -s -w /Users/etanheyman/Gits/golems.wt/weave-edits-a

Alternative fix (not shipped here): teach the launcher to resolve/create worktree paths from bare names — until then, briefs must inline absolute verified paths.

Scripted one-shot (NOT agent sessions; scope under review)

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

Do not use this form for workers, leads, or verification gates. Those are interactive repoGolem launcher sessions (brainlayerCursor -s, then send the prompt). Whether -p should remain for non-agent scripted one-shots is an open scope question for Etan; keep the flag documented, but do not apply it to agent sessions.

Model override

orcClaude -s                   # Default: Opus 4.8 1M-context (claude-opus-4-8[1m])
brainlayerClaude -s -S         # Sonnet shortcut
# ⛔ -m EXAMPLES REMOVED (2026-06-07 Etan order): NEVER pass -m for agent sessions.
# `-m opus` boots PLAIN 200K Opus and silently kills the 1M pin. Bare launcher = the policy.
brainlayerClaude -s   # CORRECT: bare launcher boots the pinned Opus 4.8 (1M context)

Launcher enforcement refuses -m/--model on {repo}Claude, {repo}Codex, and {repo}Cursor agent sessions. -p scripted one-shots may still pass a model because they are not worker/lead sessions. For scripted automation that intentionally needs an interactive override, set REPOGOLEM_ALLOW_MODEL=1 in that command's environment and document why the bare launcher law does not apply.

Via cmux (spawning from orchestrator)

spawn_agent({ repo: "brainlayer", cli: "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 })

Do not include a model field in spawn_agent. repoGolem launchers are the model source; stale model strings silently downgrade or mislabel live panes.

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 launcher/default Codex model is fine for code tasks. Don't add -m unless specifically asked, and never pass a model field through cmux spawn_agent.

Cursor model: expect default/Auto

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

-p is NOT for agent sessions

For interactive agents (monitored via cmux), launch WITHOUT -p: brainlayerCursor -s. Then send prompt separately. This includes verification gates. -p remains documented only for possible non-agent scripted one-shots; that scope needs Etan confirmation before automation depends on it.

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)