Skip to content

Self-Serve Claude Code Session Launcher, design + build, 2026-06-12

URL: https://mkdocs.justinsforge.com/memory/handoffs/self-serve-session-launcher-2026-06-12/

You are a Fable 5 worker. Justin wants to improve his AI conversation workflow. Design and build a self-serve way to start a Claude Code session running on Forge.

The actual want (in Justin's words)

Today his AI surfaces are: a few Telegram bots (LifeOS coordinator, inbox/capture, remote-bridge bot) plus the claude.ai/code Remote Control website where his tmux sessions on Forge (Console) show up. To start a NEW worker session he currently has to go talk to home-base (a running Claude session) and ask it to /spawn. He does not want that hop.

"I wish I had a place where I could click the plus button and start a session with Claude Code that is running on Forge, without having to go talk to home-base to spawn one."

So: a self-serve launcher. A "+" button (web, ideally; Telegram fast-path acceptable as a secondary surface) that, when clicked, boots/claims a Claude Code session on Console and hands back the claude.ai/code/<bridge> URL. No human-in-the-loop home-base step.

What already exists (read before designing, do NOT rebuild)

  • /spawn = forge/scripts/forge_spawn_session.sh (shared with the remote-bridge bot). Boots tmux + claude, types /remote-control, returns the bridge URL. This is the engine; the launcher should CALL it, not reinvent it.
  • /new + warm pool = pre-booted Opus spares claimed in ~1s (reference_spawn_pool). A "+" button that claims from the warm pool is the fast path you want; cold /spawn is the fallback for model/name choice.
  • Remote-bridge bot already spawns sessions from Telegram via the same script (feedback_remote_session_spawning.md) — proof the headless-trigger path works. Study how it invokes the script and returns the URL; the web launcher is the same call behind a button.
  • Sessions lifecycle: forge/.claude/skills/sessions/ (list/kill/status). The launcher's companion is a session LIST so Justin sees his running sessions and can click into or kill them.
  • The hub redesign (running in parallel: site-redesign_Fable5, brief at memory/handoffs/justinsforge-home-redesign-2026-06-12.md) is rebuilding the justinsforge.com landing page of fleet tiles. The "+" button most naturally lives on that hub. Coordinate: read that brief so your launcher drops into the redesigned home page cleanly (a "+ New Session" control + a live list of active sessions). Do not fork a competing page.
  • Spawn-audit (running: brief memory/handoffs/spawn-new-workflow-audit-2026-06-11.md) is auditing spawn robustness incl. a known prompt-typing race and a bridge-registration miss. Read its findings doc if present (...-findings-2026-06-11.md); your launcher must not inherit those bugs. If the launcher exposes the same flakiness, note it and lean on the warm-pool path which sidesteps the typing race.

Design the launcher

Think hard about the cleanest architecture, then recommend ONE: - A tiny authed web endpoint (behind Cloudflare Access, Security Rule #4 — never expose unauthenticated) that on POST claims a warm-pool session (or cold-spawns with a chosen model/name) and returns {url, name}. Front it with a "+" button + a model picker + an optional first-prompt box on the hub page. - A live "Active Sessions" list (read ~/.claude/sessions/*.json + tmux) so the page shows what's running with click-to-open and kill buttons. - Consider whether the existing Forge dashboard / context-api (infra/context-api, FastAPI on 127.0.0.1:7358) is the right host for the endpoint vs a new small service. Reuse before building (Single source of truth, CLAUDE.md 9.5). - Mobile-first: Justin triggers from Venus/Astra iPhone. The "+" must work great on phone.

Guardrails

  • Auth required. The spawn endpoint runs shell that boots real sessions; it MUST sit behind Cloudflare Access. No open endpoint.
  • Reuse forge_spawn_session.sh / the warm-pool claim; never hand-roll a second spawn path (would violate single-source-of-truth and re-introduce the audited bugs).
  • Robust over quick: handle warm-pool-empty (fall back to cold spawn + show a "booting…" state), and surface the bridge URL only once it actually registers (the audit found bridge registration can lag/miss).

Deliverable

Write forge/memory/handoffs/self-serve-session-launcher-findings-2026-06-12.md (mkdocs URL line at top): 1. Recommended architecture (one pick, with why) + where the endpoint lives. 2. The UX: what the "+" does, model picker, active-sessions list, kill control. 3. What you BUILT this pass vs what's blocked on Justin (e.g., Cloudflare Access policy, hub page merge). 4. How it coordinates with the hub redesign and avoids the spawn-audit bugs. 5. Prioritized next steps + the deploy/preview command.

Build behind a preview, do NOT deploy to a live authed URL without Justin's ok. Notify with the findings path.

Start

Read the spawn engine + warm pool + remote-bridge invocation + the two parallel briefs, design the launcher, stand up a preview (behind auth), write findings, notify. Coordinate with the hub redesign so the "+" lands on the new home page, not a separate orphan.