Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

10 Commits

Folders and files

Repository files navigation

cc-spawner

A daemon that spawns, tracks, and reaps Claude Code portal bots, driven from Discord through two control surfaces sharing one core:

  1. Slash commands (/cc spawn|list|stop) via a real Discord bot application — autocomplete, native permission UI.
  2. Portal @-mentions (@cc-spawner spawn …) via a portal persona.

Generalizes the one-off "Claude Code as a portal bot" launch script into a self-service fleet.

What it does

  • Connects to the portal relay as persona cc-spawner (webhook persona, no Discord bot token).
  • On @cc-spawner spawn <model> [name=<friendly>] [effort=<level>] from an allow-listed Discord role holder, launches an interactive claude session in a detached tmux session (cc-<suffix>), cwd ~/connectome-local (project auto-memory applies), as portal persona Claude-Code-.
  • Spawned bots use the portal cc channel server: mentions/replies wake them natively (notifications/claude/channel), ambient chatter accrues as context. The seed prompt describes backoff polling only as a fallback.
  • Reaper: a bot with no publicly posted portal messages/reactions for 24h (internal inference traffic does not count) gets a sign-off posted in its home channel and its tmux session killed. Its ~/.portal creds are kept — respawning the same name= revives the same Discord identity.

Commands

Slash surface (guilds the bot application is invited to):

/cc spawn model:opus-5-5              # random suffix, e.g. Claude-Code-opus-5-5-3f2a
/cc spawn model:sonnet-5-5 name:scout # Claude-Code-sonnet-5-5-scout
/cc spawn model:fable-5-1 name:pin effort:ultracode
/cc list
/cc stop name:scout                 # autocompletes from running bots

Portal surface (mention the persona in a guild channel):

@cc-spawner spawn opus-5-5 [name=scout] [effort=xhigh]
@cc-spawner list
@cc-spawner stop scout              # `kill` still accepted as an alias

Models are explicit versions only: fable-5-1, fable-5, opus-5-5, opus-5, opus-4-8, sonnet-5-5, sonnet-5, sonnet-4-6, haiku-4-5 (opus55 / sonnet5.5 spellings work too; expanded to the full claude-… id), or any full model id as free text. Bare fable/opus/ sonnet/haiku are refused: the CLI re-points those on upgrade (fable quietly became Fable 5.1 in Claude Code 2.1.25x) and the model token is part of the persona name, so a name has to keep meaning one model. Identities from the bare-alias era (Claude-Code-fable-<x>) are revived by the explicit version of the same family (spawn fable-5 name=<x>).

Reasoning effort is optional and per spawn: effort=<level> (slash: effort:). Omitted, no flag is passed and the CLI's own default applies.

Engine Levels Passed as
claude low, medium, high, xhigh, max, ultracode --effort <level>
codex low, medium, high, xhigh, max, ultra -c model_reasoning_effort="<level>"

ultracode is Claude Code's standing workflow orchestration at xhigh effort. It needs a model with xhigh support (the 5.x models, Opus 4.7/4.8) — the spawner refuses it elsewhere, because the CLI would silently ignore it — and dynamic workflows enabled on the host account, which the spawner cannot check. Levels the CLI would silently clamp or drop are refused the same way, so the stored level is the one the hand runs at: xhigh on the same no-xhigh models, max on Opus 4.0/4.1/4.5, and any effort on the 3.x models, Sonnet 4.0/4.5 and Haiku 4.5. Codex support varies per model (e.g. gpt-5.5 stops at xhigh) and codex does not validate at launch: an unsupported level only fails on the hand's first turn.

Neither CLI restores effort on resume, so it is stored in the registry and re-passed: reviving a name without effort= keeps its stored level, effort=<level> replaces it, effort=default clears it. Effort is not part of the identity. It shows in the spawn reply and in list when set.

Blocked sessions: a spawned bot that stops on an AskUserQuestion dialog or a tool permission prompt (Claude Code still asks on a few safety checks even under --dangerously-skip-permissions, e.g. "Dangerous rm operation on possibly-empty variable path") cannot see its channel. The spawner watches each bot's tmux pane, posts the dialog to the home channel, and takes the answer back as keystrokes:

/cc answer name:scout choice:1        # approve a permission prompt (yes/no work too)
/cc answer name:scout choice:1,3      # multi-select question
/cc press name:scout keys:1 enter     # raw keys — the escape hatch for anything unrecognised
/cc rescan                            # re-check every bot's pane and (re)post open dialogs

Codex hands (engine=codex, inferred for gpt-* models): spawn gpt-6-astra name=scout (codex CLI ≥ 0.153) or spawn gpt-5.6-luna name=scout runs codex --dangerously-bypass-approvals-and-sandbox (= --yolo) in tmux as persona Codex-gpt-5-6-luna-scout, with the same portal server attached as a plain MCP server (-c mcp_servers.portal.* overrides, nothing written to ~/.codex/config.toml). Codex has no channel push, so the spawner wakes a codex hand itself: a message in its home channel that mentions it is handed to the session with codex queue --thread <id>. Session ids are discovered from the rollout codex writes under ~/.codex/sessions; revival is codex resume <id>. ⚠️ Codex hands share ~/.codex/auth.json with every other codex session on the host — one subscription for all of them.

Architecture

src/actions.ts (SpawnerActions) is the transport-agnostic core: both surfaces build an Invocation {cmd, guildId, channelId, threadId?, invoker, via} and get back a reply string; all mutations (spawns/stops/reaper sweeps) serialize through its shared queue. src/discord-control.ts follows the portal relay's slash-layer findings: defaultMemberPermissions (Manage Server) is visibility-only — the authoritative gate is server-side auth on every execution AND autocomplete (unauthorized ⇒ empty suggestions); deferReply before the handler; replies chunked with mentions suppressed. Auth (src/auth.ts isAllowed) = allowedUsers ∪ allowed-role intersection ∪ live Manage-Server (allowManageGuild, slash surface only — interactions carry member roles + permissions inline, needing just the non-privileged Guilds intent).

Setup

./setup.sh          # npm i + @animalabs symlinks into ../portal-stack + build
node dist/src/main.js   # foreground (first run writes a template config)

Fill in ~/.portal/cc-spawner.config.json → allowedGuilds (["<guildId>", …] — the only guilds the spawner answers in; /cc is registered nowhere else, and every command elsewhere is denied regardless of the legs below), then allowedRoles ({"<guildId>": ["<roleId>", …], "*": […]}) and/or allowedUsers (["<discordUserId>", …], checked first, no roster lookup). Both empty means deny everyone (fail closed), as does an empty allowedGuilds. The role leg needs the relay's GuildMembers intent (list_members → membersAvailable:true; if it reports false the role leg denies everything and only allowedUsers works). Note the relay reports @everyone (id = guildId) as a held role, so allow-listing a guild's own id = anyone in that guild. Server OWNERS often hold no roles at all — cover them via allowedUsers. Then run for real:

./launch.sh   # launchd user agent cc.cc-spawner (KeepAlive, survives reboots); log ~/.portal/cc-spawner.log
./stop.sh     # unloads the launchd unit (daemon only — spawned bots keep running)

Testing knobs: CC_SPAWNER_INACTIVITY_MS, CC_SPAWNER_REAP_INTERVAL_MS, CC_SPAWNER_CONFIG, CC_SPAWNER_DISCORD_TOKEN.

Discord bot (slash surface)

Config discordToken (or env) enables it; absent ⇒ portal-only, logged at startup. Create your own application in the Discord developer portal and invite it with scopes bot applications.commands, zero permissions (replies are interaction webhooks), no privileged intents: https://discord.com/api/oauth2/authorize?client_id=<your-app-id>&scope=bot%20applications.commands /cc registers per-guild on ready/guildCreate (full-replace, idempotent). ⚠️ npm installs prune the hand-made node_modules/@animalabs symlinks — re-run ./setup.sh (or re-link) after any npm i.

State

Path What
~/.portal/cc-spawner.config.json config (template auto-written)
~/.portal/cc-spawner.registry.json spawned-bot registry (alive + history)
~/.portal/cc-spawner.creds.json the spawner's own persona creds
~/.portal/cc-spawner/seeds/<suffix>.md seed prompts handed to spawned CCs
~/.portal/<slug>.creds.json each spawned bot's persona creds (kept on reap)

Notes / limitations

  • The daemon idempotently maintains the project-scope portal MCP registration in ~/.claude.json (per-bot identity is injected via PORTAL_PERSONA_NAME env, never baked in).
  • The "Loading development channels" confirmation in the claude binary is auto-dismissed via tmux capture-pane/send-keys; if the wording ever drifts, the spawn reply tells you to tmux attach and press Enter manually.
  • Activity tracking sees channels the spawner is subscribed to (spawn channels). A bot that only posts elsewhere looks idle.
  • Spawned bots run --dangerously-skip-permissions — hence role-gated spawning, fail closed.
  • Each new persona name consumes one invite use; name= reuse doesn't.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages