repoGolem — Unified Launcher System

Fleet law: canon #5 owns model policy; canon #6 owns launcher naming, registry override precedence, and skip-perms. This skill keeps invocation mechanics, examples, and troubleshooting.

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

UNIFIED FLAGS (same across ALL CLIs)

CRITICAL:

• -s = skip permissions. For Codex it is a compatibility no-op; golem-install validates approval_policy = "never" and sandbox_mode = "danger-full-access" in host config. Capital -S/--sonnet is a separate Claude-only model request and is refused for full panes.
• Model/session policy lives in canon #5. Resolve claude.judgment and codex.implement through standards/model-roles.json with node scripts/model-roles.mjs <role> --field model|alias (one field). Verify bare launcher pins against those roles; Claude full panes retain 1M. Choose effort per /large-plan phase with a why and pass it explicitly at dispatch. Explicit Codex -m and -E values pass through, including when supplied through cmux spawn_agent.
• -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.
• Codex resume is fail-closed. -c requires at least one usable rollout for the launch cwd and skips malformed newer candidates; a fresh cwd with no usable rollout exits loudly. Bare resume picker mode is refused because the launcher cannot recover model/effort before the picker selects a session.
• Codex -p/--print cannot be combined with -c or explicit resume; that combination exits loudly instead of silently starting a fresh headless session. A resumed session restores its recorded model and effort; explicit -m and/or -E override the recovered field, and when both are explicit the launcher skips rollout-state recovery and lets Codex validate the requested session.
• -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": "$HOME/Gits/golems",
    "agent": "yash",
    "clis": ["claude", "codex", "cursor", "gemini"]
  }
}

Claude launchers pass this through as --agent <name>. Codex, Cursor, and Gemini 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, and yashGemini should inherit the same agent protocol instead of acting like generic shells in the project directory.

Plain Codex worker mode

Agent-style *Codex launchers keep registry persona injection by default. Opt into a plain worker with the long-only --worker flag or GOLEM_ROLE=worker:

orcCodex --worker -s -E high -w $HOME/Gits/orchestrator.wt/my-lane # reasoning
GOLEM_ROLE=worker orcCodex -s -E high -w $HOME/Gits/orchestrator.wt/my-lane # reasoning

The generated *CodexWorker aliases remain compatible and select the same mode. --worker is the one worker signal: on Codex, Cursor and Gemini it also exports GOLEM_ROLE=worker to the launched agent, for that call only. Claude is the exception: --worker there keeps the lead effort and sets no GOLEM_ROLE. Worker mode adds only a one-line role banner before an optional caller prompt; it does not inject registry agent front-matter or boot-store instructions. Short -w remains the worktree-path flag and always requires an absolute path.

Per-launch Codex overrides (Etan, 2026-10-09)

~/.codex/config.toml is never edited; *Codex launchers pass -c overrides (codex-cli 0.160.1):

• Computer use stays on for every launch, workers included ("that's how they can properly test").
• Locals T3code defaults on in ALL Codex launches: workers, leads, bare, aliases, prompts, fresh/resume/continue and scan. Its normalized locals_t3code name resolves from Codex's normal cache; no opt-in, special flags or F2 binding is required. Missing cache/name does not block launch.
• Other connectors are fail-safe stripped. Every agent-shaped launch loses the other codex_apps cloud connectors (Gmail, Calendar, GitHub…) and any browser-tools-mcp server, matched by name or package. That includes workers, -p, prompts, resume, and cmuxlayer spawns. Google Drive stays read-only: apps.<drive>.default_tools_enabled=false plus an allowlist of its read tools, so new Drive tools default to off.
• Keeping them: --lead (a worker signal still wins), or the bare human shape (no args, a TTY, no agent markers). cmuxlayer lead spawns must pass --lead.
• Opt-in, per launch, by name: GOLEM_CODEX_WORKER_ALLOW=gmail,google_drive,browser-tools …. Names come from codex's connector cache. google_drive means full Drive. An unknown name refuses the launch, and the variable never reaches the launched codex.
• --scan (security route): a worker seat that runs -s workspace-write with approval_policy="never" and no bypass, because codex-security Deep Scan refuses a parent without a managed filesystem permission profile. It is the one seat with computer use off: a scanner doesn't test. It keeps the default Locals exception and read-only Drive, strips other connectors, ignores --lead, and resolves its model from the codex.security role (-m overrides). It refuses (exit 2) the bypass flag and its alias --yolo, --approve-for-me, --add-dir, -C/--cd, a caller -p/--profile, any -s/--sandbox other than workspace-write or -a/--ask-for-approval other than never (every X/=X/attached spelling), and any -c sandbox/approval/permissions/computer-use key. It also exports a per-launch [deep_scan] cap via CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH: 2 workers, 2 subagents, 10 discovery runs, 2 h (Etan-confirmed; plugin default 4/3/40/96 h). A caller-set path wins.
• Bare dotted keys only: codex keeps quotes inside a -c key segment, so a quoted key is a silent no-op. The last -c wins and --enable beats -c. So without --lead, any caller --enable/--disable, or any -c features*/apps*/connectors* key, is refused in all five spellings (-c K, -cK, -c=K, --config K, --config=K). connectors is codex's alias of the apps feature.

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__cmuxlayer__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

brainlayer topology — bare-mirror-style hub, main lives elsewhere (2026-06-07 weave E12)

$HOME/Gits/brainlayer is the repo HUB, not the canonical main checkout: main is checked out at $HOME/Gits/brainlayer-prod (the prod/deploy worktree), and feature branches live in worktrees under $HOME/Gits/brainlayer/.worktrees/. Two rules:

1. Briefs must PIN the exact worktree path (-w $HOME/Gits/brainlayer/.worktrees/<task>). A brief that just says "brainlayer" leaves the worker guessing among three checkouts — live failure: worker's git status failed despite .git existing because the brief never pinned a path (bl-orqi-codex#2).
2. Local merges fail there. Because main is held by brainlayer-prod, gh pr merge --delete-branch from any other checkout dies with 'main' is already used by worktree at '…/brainlayer-prod' — see /pr-loop "Worktree-Locked Local Merge" for the remote fallback.

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
brainlayerCodex -s -c         # Resume newest usable Codex rollout for this cwd
brainlayerCodex -s resume ID  # Resume an explicit Codex session UUID

Codex deliberately refuses bare resume picker mode, -c in a cwd with no usable rollout, and every resume combined with -p/--print. These are fail-closed continuity guards: use -c from the session's cwd or pass its UUID, and send any follow-up prompt after the interactive resume opens. The fresh-cwd -c failure says Cannot honor Codex resume: no rollout found for selector --last in ${CODEX_HOME:-$HOME/.codex}/sessions.; bare resume says Cannot honor Codex resume: no session id or --last selector was provided. If matching rollouts exist but none carries usable state, it says Cannot honor Codex resume: no usable model/effort state found for selector --last.

Launch in a worktree

Follow the canonical worktree launch guard before creation; it owns exact-base verification and the T3 one-read preparation rule.

# Outside T3: create the authorized worktree from the preflight receipt commit OID.
# T3: use managed isolation instead; never shell-create its checkout.
golemsCodex -s -w $HOME/Gits/golems/.worktrees/my-task

# (legacy sibling $HOME/Gits/<repo>.wt/ paths resolve read-only until 2026-09-30, then die)

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

Before the agent starts, -w runs worktree-bootstrap.sh <worktree> (installed next to the dispatcher). It picks the installer from the lockfile: bun, pnpm, npm ci, uv sync, or a no-op for SwiftPM. A node_modules symlink into the main checkout is replaced by a real install. It prints one timed line; a failed install warns and the launch continues. Each installer is killed (with its children) after WORKTREE_BOOTSTRAP_TIMEOUT seconds (default 900) and reported FAILED … (timed out after Ns).

-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 $HOME/Gits/golems/.worktrees/weave-edits-a

An absolute path that does not exist yet dies the same way, one step earlier: when the repo has a .mcp.json, the launcher copies it into the worktree before the cd (golem-dispatch.zsh:486), so a missing directory aborts at the cp and drops you back at the shell. The pane looks like it simply never booted — silent lane death (2026-08-09).

-w never creates — spawn_agent does. Use spawn_agent({repo, cli, worktree:true}) (or worktree:{name|path|branch|base}) to create/reuse the worktree at launch; -w is launch-in-an-already-existing-worktree only.

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 policy

: "${phase_effort:?Choose effort per /large-plan phase before dispatch}"
orcClaude -s -E "$phase_effort"           # claude.judgment: verify role pin and 1M
brainlayerCodex -s -m "$(node scripts/model-roles.mjs codex.implement --field model)" -E "$phase_effort" "<phase implementation>"
# claude.subagent.cheap: resolve alias for an Agent child; not a visible full pane
# codex.subagent.mechanical: CANDIDATE, bench before use; do not dispatch

Launcher enforcement is defined by canon #5. Claude reserves full panes for the judgment role; legacy cheap-tier selectors are headless/subagent-only. Codex passes explicit model and effort values through; its own runtime validates the requested model. -p remains scripted one-shot mode, not a worker/lead session or verification gate.

Via cmux (spawning from orchestrator)

spawn_agent({ repo: "brainlayer", cli: "codex", model: <output of node scripts/model-roles.mjs codex.implement --field model>, effort: <effort selected for this /large-plan phase>, 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_id, text: "Keep the fix narrow and cite the changed file", press_enter: true })

cmuxlayer PR #396 is merged: an explicit Codex model is checked against the refreshed runtime catalog from codex debug models before a pane is created, then model and effort are passed to the repoGolem launcher as -m and -E. Pass the resolved codex.implement model; omit it only after verifying the launcher's bare pin matches the role config. Unsupported models fail before surface creation; if cmuxlayer prepared a new worktree first, it rolls that worktree back. At read time spawn_agent.effort accepts medium, high, xhigh, and ultra; use the launcher directly for supported low or max.

NEVER do this:

# WRONG — raw CLI, no launcher
send_to({ mode: "surface", surface, text: "source ~/.zshrc && cd $HOME/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": "$HOME/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: resolve the worker role; explicit selections are first-class

Canon #5 owns launcher policy. Resolve codex.implement for -m and choose effort per /large-plan phase for -E; verify a bare launcher against the config before relying on its pin. cmux spawn_agent.model is equivalent for model selection, while its current effort enum is the four-value subset documented above. Verify effective values from Codex session metadata rather than the agent's self-description.

Cursor model: expect default/Auto

Cursor model selection is owned by fleet canon #1.

-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

INTEGRATION

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)