Other

/repogolem

repoGolem launchers: {repo}Claude/Codex, flags -s/-c/-w/--worker, regenerate launchers. NOT generic agent spawning.

$ golems-cli skills install repogolem
9 evals

Updated 1 week ago

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}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.

Cursor launchers are retired; use T3 delegate_task (providerInstanceId: "cursor", model: "default") for Cursor work; see /agent-routing for details.


UNIFIED FLAGS (same across ALL CLIs)

FlagShortWhat It DoesClaudeCodex
Skip permissions-sAuto-approve tool calls--dangerously-skip-permissionsCompatibility no-op; host config supplies the policy
Continue/resume-cResume last session--continueResume the newest usable rollout for the launch cwd
Model override-m <model>Explicit model selectionJudgment role for full panes; cheap role headless/subagent onlyAny model string passes through
Reasoning effort-E <effort>Explicit Codex effort—low, medium, high, xhigh, max, ultra
Headless/print-p "prompt"Scripted one-shot only; NOT agent sessions or verification gates--print -p "prompt"Headless prompt
Worktree-w <abs-path>Launch from pre-created git worktree cwdcd <path>cd <path>

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.

LAUNCHER NAME PATTERN

{projectName}{CLI}

Examples:
  brainlayerClaude    brainlayerCodex
  golemsClaude        golemsCodex
  orcClaude           orcCodex
  6pmClaude           6pmCodex
  dashboardClaude     dashboardCodex

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", "gemini"]
  }
}

Claude launchers pass this through as --agent <name>. Codex 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 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 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

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

ProjectPathLaunchers
golems$HOME/Gits/golemsgolemsClaude, golemsCodex
brainlayer$HOME/Gits/brainlayerbrainlayerClaude, brainlayerCodex
voicelayer$HOME/Gits/voicelayervoicelayerClaude, voicelayerCodex
orc (orchestrator)$ORCHESTRATOR_REPOorcClaude, orcCodex
dashboard$HOME/Gits/golems-dashboarddashboardClaude, dashboardCodex
6pm$HOME/Gits/6pm-mini6pmClaude, 6pmCodex
portfolio$HOME/Gits/etanheyman.comportfolioClaude, portfolioCodex
taskowl$HOME/Gits/taskowltaskowlClaude, taskowlCodex
taskowl$HOME/Gits/TaskOwl-apptaskowlClaude, taskowlCodex
cmuxlayer$HOME/Gits/cmuxlayercmuxlayerClaude, cmuxlayerCodex
mcplayer$HOME/Gits/mcplayermcplayerClaude, mcplayerCodex
metacomlayer$HOME/Gits/metacomlayermetacomlayerClaude, metacomlayerCodex
qwan$HOME/Gits/qwan-drillqwanClaude, qwanCodex
coach$HOME/Gits/golems/packages/coachcoachClaude, coachCodex
content$HOME/Gits/golems/packages/contentcontentClaude, contentCodex
services$HOME/Gits/golems/packages/servicesservicesClaude, servicesCodex
skills$HOME/Gits/golemsskillsClaude, skillsCodex
eval$ORCHESTRATOR_REPOevalClaude, evalCodex
maintenance$ORCHESTRATOR_REPOmaintenanceClaude, maintenanceCodex
teller$HOME/Gits/tellerGolemtellerClaude, tellerCodex
monitor$HOME/Gits/monitorGolemmonitorClaude, monitorCodex
rudy$HOME/Gits/rudy-monoreporudyClaude, rudyCodex
songscript$HOME/Gits/songscriptsongscriptClaude, songscriptCodex
union$HOME/Gits/unionunionClaude, unionCodex
ralph~/.config/ralphralphClaude, ralphCodex
taba$HOME/Gits/tabatabaClaude, tabaCodex
project2~/Desktopproject2Claude, project2Codex
maakaf$HOME/Gits/maakaf_homemaakafClaude, maakafCodex

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.