repogolem

name	repogolem
description	Launch agents in any repo via repoGolem launchers ({name}Claude, {name}Codex, {name}Cursor). Unified flags: -s skip, -c continue, -m model, -p headless, -w worktree cwd. 40 projects registered. Triggers on: spawn agent, launcher, repoGolem, brainlayerClaude, flags.

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 = Sonnet model (separate flag, Claude only)
• 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. Override with -m <model> or -S for Sonnet.
• -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

orcClaude -s                   # Default: Opus 4.8 1M-context (claude-opus-4-8[1m])
brainlayerClaude -s -S         # Sonnet shortcut
brainlayerClaude -s -m sonnet  # Use Sonnet instead of default Opus
brainlayerClaude -s -m claude-opus-4-8  # Opus 4.8 standard 200K context
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)