mosaicstack/stack
1
0
Fork 0
Code Issues 74 Pull Requests 1 Actions Packages Projects Releases 15 Wiki Activity

feat(launcher): 'mosaic yolo claudex' — GPT-in-Claude-Code launcher via claude-code-proxy #790

New Issue
Closed
opened 2026-07-16 19:13:21 +00:00 by jason.woltje · 0 comments
jason.woltje commented 2026-07-16 19:13:21 +00:00
Owner
Copy Link

Summary

Make Claudex an official Mosaic framework feature: a mosaic yolo claudex launcher that runs GPT models (gpt-5.6-sol and siblings) inside the Claude Code harness via raine/claude-code-proxy authenticated with ChatGPT-subscription OAuth (no OpenAI platform key). Jason verified the raw setup on the Kinoite workstation on 2026-07-16 via a hand-rolled ccgpt wrapper; this issue promotes that into a first-class, Mosaic-composed launcher.

Authoritative spec

jarvis-brain @ main → docs/claude-code/CLAUDEX-GPT-PROXY.md (SHA-256 196ad82974c72e479579500d060b025a478e1ea99ada6731b792bdbdf719e5b2). Implementers MUST read it; the env-var table, gotchas, and handoff design notes are normative.

Classification (non-negotiable)

Claudex sessions are EXPERIMENTAL / second-opinion capacity — NOT orchestration-grade until Mosaic gates (hooks/queue-guard/sequential-thinking/completion gates) are re-validated under GPT. Mosaic hooks and gates were tuned against Claude models; expect prompt-behavior drift. The launcher must surface this classification in-session (banner and/or composed-contract note) so a claudex session is never mistaken for an orchestrator/delivery lane. Aligns with Jason's standing GPT-caution steer.

Design constraints (from the spec)

  1. Isolated config dir — hard requirement. Compose the Mosaic layers the way mosaic claude does (CONSTITUTION/AGENTS/SOUL/USER injection, hooks, MCP) but into an isolated CLAUDE_CONFIG_DIR (e.g. ~/.claude-gpt or a Mosaic-owned path). NEVER point at ~/.claude, or GPT sessions will mutate real Claude state.
  2. Env-var set (from the spec's verified table): ANTHROPIC_BASE_URL=http://127.0.0.1:18765, ANTHROPIC_AUTH_TOKEN=unused (proxy holds the real credential), ANTHROPIC_MODEL=gpt-5.6-sol[1m], ANTHROPIC_SMALL_FAST_MODEL=gpt-5.6-luna[1m], CLAUDE_CODE_AUTO_COMPACT_WINDOW=272000, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1, plus the isolated CLAUDE_CONFIG_DIR.
  3. Preflight, respecting gotcha #1. Verify: proxy binary present; claude-code-proxy codex auth status valid (trigger re-auth device flow if expired — device codes expire ~5 min); proxy listening on 127.0.0.1:18765. Liveness = any HTTP response is alive; do NOT use curl -f (root path returns non-2xx; the original wrapper spawned duplicate proxies because of this).
  4. Proxy lifecycle. Prefer a systemd user unit (claude-code-proxy.service) over nohup-on-demand for a permanent command; fall back gracefully where systemd-user is unavailable.
  5. Model-tier mapping decision. Mosaic subagent tiers haiku|sonnet|opus do not map to Codex models. Either pin all tiers to one GPT model or maintain an explicit mapping in the launcher (default primary gpt-5.6-sol, small/fast gpt-5.6-luna). Document the decision.
  6. Credential hygiene. OAuth token lives at ~/.config/claude-code-proxy/codex/auth.json; the proxy holds the real credential and Claude Code sees only unused. Never print/log token values. No secrets in the composed config dir.

Target surface (verified against origin/main @ 9745bc3f)

All work in packages/mosaic (published as @mosaicstack/mosaic, the mosaic CLI):

  • src/commands/launch.ts — the launch seam. Reuse composeContract(runtime, mosaicHome) (layer injection, ~L325), ensureRuntimeConfig() (~L537), the preflight helpers (checkRuntime/checkSequentialThinking/auditClaudeSettings), and launchRuntime(runtime, args, yolo) (~L729). Note: execRuntime() (~L807) currently passes process.env unchanged — claudex needs an env-injection path (extend execRuntime/delegateToScript to accept env overrides, or a dedicated claudex launch path). The claude case today audits/uses ~/.claude — claudex must instead compose into and point at the isolated dir.
  • src/cli.ts — yolo already exists in the framework command list (~L69) and runtimes are registered via registerLaunchCommands(). Wire claudex as a yolo target / pseudo-runtime.
  • packages/mosaic/framework/tools/ (resolved via resolveTool/fwScript) — home for any new proxy-preflight / systemd-unit helper scripts.
  • Config-dir composition helpers under src/config/ and runtime MCP wiring under src/runtime/mcp-config.ts.

Phased plan

  • Phase 1 — Proxy preflight + lifecycle. Binary presence, codex auth status (+ re-auth flow), liveness probe (gotcha #1), optional systemd user unit management. Pure, well-tested helpers; no session launch yet.
  • Phase 2 — Isolated config-dir composition + launch. Compose Mosaic layers (CONSTITUTION/AGENTS/SOUL/USER + hooks + MCP) into the isolated CLAUDE_CONFIG_DIR; inject the env-var set; mosaic yolo claudex launches a working GPT-in-Claude-Code session. Env-injection path added to the launch code.
  • Phase 3 — Model-tier mapping. Implement + document the claude-tier→GPT-model mapping (or single-model pin).
  • Phase 4 — EXPERIMENTAL classification. In-session banner + composed-contract note marking claudex non-orchestration-grade; ensure it cannot be mistaken for a delivery/orchestrator lane.

Docs update (packages/mosaic/README.md + framework docs) accompanies the code.

Acceptance criteria

  • mosaic yolo claudex launches a GPT-backed Claude Code session using an isolated CLAUDE_CONFIG_DIR; ~/.claude is provably untouched.
  • Full Mosaic layer composition (CONSTITUTION/AGENTS/SOUL/USER, hooks, MCP) present in the isolated dir.
  • Preflight verifies binary + OAuth status + liveness without curl -f; re-auth path works; no duplicate proxy processes.
  • Proxy lifecycle via systemd user unit (with documented fallback).
  • Model-tier mapping decision implemented and documented.
  • Session is clearly classified EXPERIMENTAL / second-opinion in-session.
  • No credential values printed or written into the config dir.

Delivery gates (Mosaic standard)

  • TDD, tests-first, ≥85% coverage on new code; co-located *.spec.ts mirroring existing launcher tests (launch.spec.ts, commands/*.spec.ts).
  • Terminal-green Woodpecker CI (instance mosaic) on exact head.
  • Independent review (author ≠ reviewer) + security review (secrev) on the credential/config-composition surface (OAuth token handling, isolated-dir isolation guarantee, no ~/.claude mutation, no secret leakage).
  • Trunk-based: branch from main, reviewed squash PR, no direct push to main.
  • Completion only after merge + descendant-main green CI + this issue closed. Not part of the #758 fleet DAG; must not preempt the M5-001/#758 gate flow.

Filed by MS-LEAD (web1:mosaic-100) per Jason directive (Discord 2026-07-16 19:06Z) relayed by Mos.

## Summary Make **Claudex** an official Mosaic framework feature: a `mosaic yolo claudex` launcher that runs GPT models (`gpt-5.6-sol` and siblings) *inside the Claude Code harness* via [`raine/claude-code-proxy`](https://github.com/raine/claude-code-proxy) authenticated with ChatGPT-subscription OAuth (no OpenAI platform key). Jason verified the raw setup on the Kinoite workstation on 2026-07-16 via a hand-rolled `ccgpt` wrapper; this issue promotes that into a first-class, Mosaic-composed launcher. ## Authoritative spec `jarvis-brain` @ `main` → `docs/claude-code/CLAUDEX-GPT-PROXY.md` (SHA-256 `196ad82974c72e479579500d060b025a478e1ea99ada6731b792bdbdf719e5b2`). Implementers MUST read it; the env-var table, gotchas, and handoff design notes are normative. ## Classification (non-negotiable) Claudex sessions are **EXPERIMENTAL / second-opinion capacity — NOT orchestration-grade** until Mosaic gates (hooks/queue-guard/sequential-thinking/completion gates) are re-validated under GPT. Mosaic hooks and gates were tuned against Claude models; expect prompt-behavior drift. The launcher must surface this classification in-session (banner and/or composed-contract note) so a claudex session is never mistaken for an orchestrator/delivery lane. Aligns with Jason's standing GPT-caution steer. ## Design constraints (from the spec) 1. **Isolated config dir — hard requirement.** Compose the Mosaic layers the way `mosaic claude` does (CONSTITUTION/AGENTS/SOUL/USER injection, hooks, MCP) but into an **isolated `CLAUDE_CONFIG_DIR`** (e.g. `~/.claude-gpt` or a Mosaic-owned path). NEVER point at `~/.claude`, or GPT sessions will mutate real Claude state. 2. **Env-var set** (from the spec's verified table): `ANTHROPIC_BASE_URL=http://127.0.0.1:18765`, `ANTHROPIC_AUTH_TOKEN=unused` (proxy holds the real credential), `ANTHROPIC_MODEL=gpt-5.6-sol[1m]`, `ANTHROPIC_SMALL_FAST_MODEL=gpt-5.6-luna[1m]`, `CLAUDE_CODE_AUTO_COMPACT_WINDOW=272000`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`, `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1`, plus the isolated `CLAUDE_CONFIG_DIR`. 3. **Preflight, respecting gotcha #1.** Verify: proxy binary present; `claude-code-proxy codex auth status` valid (trigger re-auth device flow if expired — device codes expire ~5 min); proxy listening on `127.0.0.1:18765`. **Liveness = any HTTP response is alive; do NOT use `curl -f`** (root path returns non-2xx; the original wrapper spawned duplicate proxies because of this). 4. **Proxy lifecycle.** Prefer a **systemd user unit** (`claude-code-proxy.service`) over nohup-on-demand for a permanent command; fall back gracefully where systemd-user is unavailable. 5. **Model-tier mapping decision.** Mosaic subagent tiers `haiku|sonnet|opus` do not map to Codex models. Either pin all tiers to one GPT model or maintain an explicit mapping in the launcher (default primary `gpt-5.6-sol`, small/fast `gpt-5.6-luna`). Document the decision. 6. **Credential hygiene.** OAuth token lives at `~/.config/claude-code-proxy/codex/auth.json`; the proxy holds the real credential and Claude Code sees only `unused`. Never print/log token values. No secrets in the composed config dir. ## Target surface (verified against `origin/main` @ `9745bc3f`) All work in `packages/mosaic` (published as `@mosaicstack/mosaic`, the `mosaic` CLI): - `src/commands/launch.ts` — the launch seam. Reuse `composeContract(runtime, mosaicHome)` (layer injection, ~L325), `ensureRuntimeConfig()` (~L537), the preflight helpers (`checkRuntime`/`checkSequentialThinking`/`auditClaudeSettings`), and `launchRuntime(runtime, args, yolo)` (~L729). **Note:** `execRuntime()` (~L807) currently passes `process.env` **unchanged** — claudex needs an env-injection path (extend `execRuntime`/`delegateToScript` to accept env overrides, or a dedicated claudex launch path). The `claude` case today audits/uses `~/.claude` — claudex must instead compose into and point at the isolated dir. - `src/cli.ts` — `yolo` already exists in the framework command list (~L69) and runtimes are registered via `registerLaunchCommands()`. Wire `claudex` as a `yolo` target / pseudo-runtime. - `packages/mosaic/framework/tools/` (resolved via `resolveTool`/`fwScript`) — home for any new proxy-preflight / systemd-unit helper scripts. - Config-dir composition helpers under `src/config/` and runtime MCP wiring under `src/runtime/mcp-config.ts`. ## Phased plan - **Phase 1 — Proxy preflight + lifecycle.** Binary presence, `codex auth status` (+ re-auth flow), liveness probe (gotcha #1), optional systemd user unit management. Pure, well-tested helpers; no session launch yet. - **Phase 2 — Isolated config-dir composition + launch.** Compose Mosaic layers (CONSTITUTION/AGENTS/SOUL/USER + hooks + MCP) into the isolated `CLAUDE_CONFIG_DIR`; inject the env-var set; `mosaic yolo claudex` launches a working GPT-in-Claude-Code session. Env-injection path added to the launch code. - **Phase 3 — Model-tier mapping.** Implement + document the claude-tier→GPT-model mapping (or single-model pin). - **Phase 4 — EXPERIMENTAL classification.** In-session banner + composed-contract note marking claudex non-orchestration-grade; ensure it cannot be mistaken for a delivery/orchestrator lane. Docs update (`packages/mosaic/README.md` + framework docs) accompanies the code. ## Acceptance criteria - [ ] `mosaic yolo claudex` launches a GPT-backed Claude Code session using an **isolated** `CLAUDE_CONFIG_DIR`; `~/.claude` is provably untouched. - [ ] Full Mosaic layer composition (CONSTITUTION/AGENTS/SOUL/USER, hooks, MCP) present in the isolated dir. - [ ] Preflight verifies binary + OAuth status + liveness without `curl -f`; re-auth path works; no duplicate proxy processes. - [ ] Proxy lifecycle via systemd user unit (with documented fallback). - [ ] Model-tier mapping decision implemented and documented. - [ ] Session is clearly classified EXPERIMENTAL / second-opinion in-session. - [ ] No credential values printed or written into the config dir. ## Delivery gates (Mosaic standard) - TDD, tests-first, **≥85% coverage** on new code; co-located `*.spec.ts` mirroring existing launcher tests (`launch.spec.ts`, `commands/*.spec.ts`). - Terminal-green Woodpecker CI (instance `mosaic`) on exact head. - **Independent review** (author ≠ reviewer) + **security review (secrev)** on the credential/config-composition surface (OAuth token handling, isolated-dir isolation guarantee, no `~/.claude` mutation, no secret leakage). - Trunk-based: branch from `main`, reviewed squash PR, no direct push to `main`. - Completion only after merge + descendant-main green CI + this issue closed. Not part of the `#758` fleet DAG; must not preempt the M5-001/#758 gate flow. _Filed by MS-LEAD (`web1:mosaic-100`) per Jason directive (Discord 2026-07-16 19:06Z) relayed by Mos._
jason.woltje added this to the Phase 6: CLI & Tools (v0.0.7) milestone 2026-07-16 19:13:21 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No Label
Milestone
No items
No Milestone Phase 6: CLI & Tools (v0.0.7)
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#790
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?