super-claude-code

/plugin marketplace add sitkowsp/super-claude-code
/plugin install council@super-claude-code

---

Why

You already pay for several AI subscriptions. Claude Code is the best of them at understanding a repo, but its 5-hour usage window is the scarce resource, and the others sit idle in separate windows. council fixes that:

• 🏛️ Claude is the chair. It splits work into disjoint task cards, delegates, reviews every diff, runs your gates and merges.
• ⚡ Executors work in parallel — Codex, Antigravity, Copilot, Grok, Ollama, or a cheap claude -p — each in its own copy of the repo, each on its own council/<id> branch.
• 💸 Your Claude tokens are protected. A delegation policy sends docs, assets, chores and anything over ~40 lines to an executor. When the window is about to end, /council:offload hands the rest over.
• 🎨 Images too. Codex (ChatGPT) and Antigravity (Google) generate real PNG logos and icons straight into your repo.
• 🎮 3D and gamedev. Codex runs GPT-6 Astra by default (reasoning medium, context 256k, both configurable): texture sets, Blender bpy scripts run headless, Unreal C++/Python — all left in the task branch. /council:doctor shows whether Blender or Unreal are installed (Unreal is found on any local disk, e.g. D:/GAMES/Unreal/UE_5.8, or via UE_ROOT); without them executors still deliver scripts plus run instructions.
• 🔒 Secrets never leave. Executors get a git archive export without .git and without your never_share files; everything they write is data, not instructions.
• 🔁 Fallback built in. Out of quota? Not responding? The task is re-queued on the fallback model and the failing model gets a cooldown.
• 🎚️ Right-sized executors. Every dispatch scores the card's complexity (deterministic: scope, role, keywords, criteria, retry count) and picks the tier and effort to match — a typo fix runs on the cheap model at low effort, a refactor goes to GPT-6 Astra / Fable at high. council_why shows the reasoning; delegation.auto_effort: false turns it off.
• 💸 OpenAI and Anthropic APIs, with caching always on. Besides the logged-in CLIs, council calls the APIs directly — the key comes from your environment variables (on Windows straight from the user environment, where Claude Code hides ANTHROPIC_API_KEY from its own processes), never from a config file. The list of available models is refreshed on every plugin run, you pick the one that codes first (/council:chair coder anthropic:claude-opus-5-5), and every request is prompt-cached: a typical task reads ~11k tokens from cache while paying full price for a dozen. Usage is measured, not estimated.
• 📡 Always-current model list. Before delegating, a stale availability probe (older than probe_ttl_hours, default 24 h) reruns automatically — per provider: installed, logged in, discovered model list where the CLI can list one (Ollama tags, agy models), and the reasoning-effort values it accepts. council_models shows it all, with a warning when your configured model is not on the discovered list.
• 🪑 Chair options. Let GPT-6 Astra draft the plan and summarise reviews for Claude (/council:chair plan-assist codex), or let Claude Fable 5.1 write the code at medium effort (/council:chair coder fable). Defaults stay as they are; see "Choose your chair setup".
• 📓 Obsidian as the project's memory. Plans, decisions, task cards and reports are mirrored into your vault; with the Claudian plugin the vault talks back.

What it looks like

/council:plan  Build a one-page business-card site: logo + icons (PNG), copy from public data, HTML/CSS
   → T-001 assets  → codex         (logo.png, icons/*.png)
   → T-002 docs    → copilot       (copy.md)
   → T-003 implement → antigravity (index.html, styles.css)   depends_on: T-001, T-002
/council:run          # three executors start in parallel, each in .council/work/<id>/
/council:status       # board + new events; blocked? /council:answer T-002 "use the public registry"
/council:review T-001 # gates + diff + flags (+ assistant summary if enabled) → verdict; a rejection re-dispatches
/council:merge        # rebase + merge --no-ff in id order, after-merge gates, MEMORY.md line

That epic is real: it built a one-page business-card website with three executors and zero hand-written code (lessons in DESIGN.md §19.16).

Claude Code ──/council:plan──▶ task cards (.council/tasks/T-001.json)
            ──/council:run───▶ council-mcp: branch council/T-001
                                           worktree .council/worktrees/T-001  (owned by council-mcp)
                                           workdir  .council/work/T-001      (executor's copy: no .git, no secrets)
                                           executor process (codex / agy / copilot / grok / ollama loop / claude -p)
executor ──── REPORT.md ─────▶ watcher: parse → enforce scope → copy back → snapshot commit → events.jsonl
Claude   ◀── /council:status ── board + new events;  blocked? ──/council:answer──▶ ANSWER.md, re-dispatch
Claude   ── /council:review ── gates + diff → verdict ── /council:merge ── rebase, --no-ff, gates

Who does what

Work	role	goes to
code, refactors	implement, refactor	Codex → Antigravity → Copilot → local → Grok (or Fable 5.1 first with /council:chair coder fable)
logos, icons, illustrations, diagrams (PNG via Codex or Antigravity)	assets	Codex → Antigravity → Copilot
textures, materials, Blender scripts, Unreal code (GPT-6 Astra via Codex)	3d	Codex → Antigravity
documentation, copy	docs	Copilot → Antigravity → cheap Claude → local
review, second opinion, chores	review, chores	local Ollama first (free tokens) → cloud
company data	data	local only, never leaves your machine

Override any card with assigned_to. Routing is data (.council/council.json), not prompts.

Install (2 minutes)

Prerequisites: Claude Code, Python 3.12, uv, git, Node.js (for the npm CLIs).

1. In Claude Code (the desktop app has no /plugin dialog — use the terminal form there):

   /plugin marketplace add sitkowsp/super-claude-code
   /plugin install council@super-claude-code
   

   claude plugin marketplace add sitkowsp/super-claude-code && claude plugin install council@super-claude-code
   

2. Restart the Claude Code desktop app (or your terminal session). A running Claude Code keeps the environment it started with, so new PATH entries (uv, agy, npm CLIs) and variables like COUNCIL_OBSIDIAN_VAULT are invisible until it restarts. Skipping this shows up as council MCP server: CONNECTION_CLOSED.

3. Open any project. The first session initialises .council/ and prints which executors are ready. Then, still inside Claude Code:

   /council:setup --install    # installs missing npm CLIs (Codex, Copilot, Grok); lists logins needed
   /council:doctor             # installed / logged in / action, Obsidian status, routing gaps
   

4. Log in to the executors you own (each opens a browser, in a terminal): codex login (ChatGPT), gh auth login (Copilot), agy once (Google, Antigravity), grok login (xAI). Ollama needs no login. Restart Claude Code afterwards.

There is no council command on your PATH with a plugin install — everything is a /council:<name> slash command or a council_* MCP tool. The terminal form, if you ever need it:

uv run --directory ~/.claude/plugins/cache/super-claude-code/council/<version> council doctor

• Every council tool fails — call council_ping (/council:doctor falls back to it): it shows the repo root the server resolved and the environment it got; tool errors carry the real exception.
• council_doctor is "missing" — Claude connected to a stale project-level .mcp.json written by an older council init (it pins one cached plugin version). With the plugin installed, delete the council entry from the project's .mcp.json; since rc4 init no longer writes it from the plugin.
• CONNECTION_CLOSED — almost always uv is not on the PATH of the process that launched Claude Code: restart Claude Code after installing uv, or set COUNCIL_UV to the full path of uv.exe, then /mcp to reconnect. Plugin versions before rc7 could also fail this way in headless claude -p sessions (the manifest used a defaulted variable); update the plugin.
• Merge says "rebase failed" but lists no conflicting files — a gate modified a tracked file inside the task worktree (a formatter, or uv run refreshing a stale uv.lock). Since rc10 such gate side effects are discarded before the rebase and the real git error is shown; on older versions run git -C .council/worktrees/<id> checkout -- . and merge again. Keep uv.lock in sync with pyproject.toml (uv lock) so gates do not rewrite it.
• Invalid manifest / stale version — claude plugin marketplace update super-claude-code, then claude plugin update council@super-claude-code, restart. The first start builds a private virtualenv in the plugin cache (10–30 s). The marketplace clones over HTTPS; no SSH key needed.

git clone https://github.com/sitkowsp/super-claude-code && cd super-claude-code && uv sync
cd /path/to/your/project
uv run --directory /path/to/super-claude-code council init      # writes .council/ and .mcp.json
uv run --directory /path/to/super-claude-code council doctor

In a clone the CLI is uv run council … (init, setup, doctor, events, obsidian, report, session-start); the .mcp.json written by init points Claude Code at the clone. The clone's own .mcp.json is the plugin manifest (${CLAUDE_PLUGIN_ROOT} is set only by the plugin loader), so when you open the clone itself as a project that entry shows as skipped — expected.

Executors

• Ollama (local or remote) with a tool-capable model — qwen3:8b works on a laptop; init picks a model you already pulled (coder > qwen3 > …, skipping embedding/vision models) if the default is missing
• ChatGPT Codex — npm i -g @openai/codex (≥0.153), codex login; default model gpt-6-astra at medium effort (generates PNGs, textures)
• GitHub Copilot — npm i -g @github/copilot, gh auth login
• Grok Build — npm i -g @xai-official/grok, grok login
• Google Antigravity agy — from https://antigravity.google, run agy once (generates PNGs; the successor to Gemini CLI for individual accounts — Gemini CLI itself now needs an API key)
• Cursor CLI (optional, disabled by default) — curl https://cursor.com/install -fsS | bash (PowerShell: irm https://cursor.com/install | iex), then cursor-agent login or CURSOR_API_KEY; one CLI, many models (Composer, GPT, Opus, Gemini, Grok) — cursor-agent models feeds the daily probe. Detected automatically by /council:doctor; enable with "enabled": true on the cursor model
• OpenAI API (optional, off until /council:setup --api) — no CLI, no browser login: an OPENAI_API_KEY environment variable. Reasoning models (gpt-5*, gpt-6*, o*) run on the Responses API with a real reasoning-effort knob
• Anthropic API (optional, off until /council:setup --api) — an ANTHROPIC_API_KEY environment variable (a Windows user variable works even though Claude Code hides it from its children). Prompt caching is always on, output_config.effort follows task complexity, and all four token counters (including cache_read/cache_write) land in /council:stats
• Claude as a cheap executor and fallback — claude -p --model haiku

Quick start

/council:ask codex "review council_mcp/config.py for pydantic mistakes" --files council_mcp/config.py
/council:plan add a --json flag to the CLI and document it
/council:run
/council:status
/council:review T-001
/council:merge

Full walkthrough: docs/getting-started.md. Every command, where it runs (repo session vs Claudian vault vs terminal) and what to do per task state: docs/manual.md. Recipes (bug-hunt with /council:compare, assets epics, end-of-session offload): docs/recipes.md.

Use the OpenAI / Anthropic APIs (optional)

1. Put the keys in environment variables — OPENAI_API_KEY, ANTHROPIC_API_KEY (on Windows: user environment variables). Never in council.json.
2. In the project's Claude Code session: /council:setup --api — switches on the API models whose key is found and prints each provider's live model list.
3. Pick the model that codes first: /council:chair coder anthropic:claude-opus-5-5 (or openai:gpt-6-astra, or any id from the list). /council:chair coder executors goes back.
4. Plan and run as usual (/council:plan …, /council:run). Each session start prints API models refreshed: …; /council:stats shows the measured tokens including cache reads.

The same from a terminal: council setup --api --coder anthropic:claude-opus-5-5 --root <repo>. API calls are billed per token to your API account; details in docs/reference.md.

Choose your chair setup (optional)

Claude Code is always the chair: it decides, approves and merges. Two switches change how much of the chair's own work is offloaded and who writes code. Defaults are unchanged: Claude plans and reviews alone, Codex (GPT-6 Astra, medium) codes and draws, Copilot documents, Ollama reviews.

Switch	Values	What changes
plan_assist	off (default) / codex / any model	/council:plan first asks that model for a draft of the task cards (repo analysis, playbook, memory, vault notes go in; validated cards come out). Claude and you approve; nothing is saved by the assistant. Saves the most Claude tokens, because planning is where Claude reads the whole repo.
review_assist	off (default) / codex / local / any model	council_review adds a 12-line summary from that model (assistant_review). Claude still reads gates, flags and diff-stat and gives the verdict.
coder	executors (default) / fable	fable = Claude Fable 5.1 via claude -p --effort medium is put first for implement/refactor; graphics, 3D, docs, review keep their routing. Fallback for fable is the normal chain (Codex → …).

Set it per project, effective immediately, no restart:

/council:chair                      # show current setup
/council:chair plan-assist codex    # Astra drafts plans for Claude
/council:chair review-assist codex  # Astra summarises diffs for Claude
/council:chair coder fable          # Claude Fable 5.1 (medium) writes code; codex remains the graphics/3D model
/council:chair coder executors      # back to default

/council:doctor prints the active line, e.g. chair: claude · plan_assist: codex · review_assist: off · coder: fable (claude-fable-5-1, effort medium).

How to run these commands. In the Claude Code desktop app type the slash command in the chat box (/council:chair coder fable). In the terminal, the same slash commands work inside an interactive claude session; from a shell script use headless mode or the CLI:

claude -p "/council:chair coder fable"
uv run --directory ~/.claude/plugins/cache/super-claude-code/council/<version> council setup --coder fable --plan-assist codex

Honest note: coder: fable spends your Claude usage window (every claude -p counts against the same 5-hour limit) — it saves your interactive session's context and lets several cards run in parallel, not your quota. The assistants save quota for real. Everything the assistants return is treated as untrusted data; the plugin's own hooks stay silent inside claude -p executors (COUNCIL_EXECUTOR=1).

Two Claude accounts (optional)

If you have seats in two organisations (or two Claude accounts), claude -p executors (fable, cheap) can run under either one and fail over automatically when one hits its usage limit:

/council:accounts add work2        # registers a profile (its own CLAUDE_CONFIG_DIR), prints the login command
# run that one command in a terminal: it opens the browser, you pick the org (council never touches credentials)
/council:accounts verify           # enables fable-work2 / cheap-work2 once the profile is logged in
/council:accounts                  # table: profile, logged in, account/org, models, cooldown; fallback chains

add creates <model>-<profile> copies of every Claude executor, disabled until you log in, and puts them first in that model's fallback chain (fallback.by_model): a usage-limit error on fable moves the task to fable-work2 and puts fable on cooldown until the reset time quoted in the error (or 60 min if none). Other providers stay in the chain after that.

What this cannot do: switch your own chair session. Claude Code logs in once per config directory and the desktop app uses the default one, so when the chair's window ends the plugin shows the recipe (switch_hint in /council:accounts, /council:offload, council_budget): handoff, close the app, claude auth login with the other org (or a terminal claude with CLAUDE_CONFIG_DIR of the other profile), reopen — council_status returns the handoff.

Policy note, also printed by the command: using several accounts to get around usage limits may violate Anthropic's usage policy. Team seats in different organisations each come with their own allowance; whether that applies to you is your and your admin's call. The plugin provides the mechanism, not the permission.

Saving Claude tokens — the point of all this

How much did it save? /council:savings (or council_savings, council report, the Obsidian note Council/<project>/Savings.md, and one line at session start) shows an estimate of the Claude tokens the chair did not spend: per merged task a base by role plus a value per changed line (implement 1500 + 60/line, docs 800 + 40/line, assets/3d 2500 + 20/line, review/chores 600 + 20/line), plus 3000 per plan draft and 800 per review summary from an assistant. It is a documented heuristic, not a measurement: the CLIs report no token counts and Claude's own review and merge tokens are not subtracted. /council:savings --backfill counts tasks merged before the estimate existed, from their merge commits. Per-model breakdown and per-project totals land on the Obsidian dashboard.

The plugin enforces a delegation policy (delegation in council.json, default mode: auto):

• docs, assets, chores, review and data work always go to an executor;
• any change of roughly 40+ lines or 2+ files goes to an executor; Claude keeps contracts, integration, merge and small hotfixes;
• borderline cases: Claude asks you once (mode: ask always asks, off disables);
• council_should_delegate gives the deterministic answer; the SessionStart hook reminds Claude of the policy every session;
• after ~3.5 h the hooks warn that the 5-hour window may end and /council:offload turns the remaining work into executor tasks plus a handoff note, so the next session only reviews and merges.

If an executor runs out of quota, stops responding or is unavailable, the task is re-queued on the fallback model (cheap = claude -p, configurable) and the failing model gets a cooldown.

Trust, lessons, playbooks

Every model starts on probation: small cards, second opinion required, merge only after review. Three first-pass approvals promote it; two consecutive rejections demote it; a defect found after merge (/council:defect) always demotes. Every rejection carries a one-line lesson; the last ten lessons for that model and role are injected into its next TASK.md. Executors may raise dissent: true when they object to the contract itself — that goes to you, not to another model.

Playbooks (playbooks/*.json, override in .council/playbooks/) tell the planner how to split work: feature (default), bug-hunt (split hypotheses, /council:compare, Claude fixes), data-internal (everything local-only), game-assets (textures / Blender / Unreal via the 3d role).

Obsidian (optional)

council finds your vault (or the one in COUNCIL_OBSIDIAN_VAULT) and mirrors MEMORY, HANDOFF, LESSONS, task cards (Dataview frontmatter) and reports into <vault>/Council/<project>/.

• Write Plan.md, DECISIONS.md or notes tagged #council/spec — /council:plan reads and cites them.
• A blocked task creates inbox/T-007.md; fill its answer: in Obsidian and the next council_status resumes the task.
• council_obsidian(kit=true) installs Claudian slash commands (/council-status, /council-answer, /council-decide, /council-handoff) in the vault.

Where to find things, a Dataview dashboard with All tasks across every model and project (plus blocked / in review / failed / per-model counts), Phase B details: docs/obsidian.md.

MCP tools

25 tools, all council_*: models · ask · probe · plan · dispatch · status · answer · cancel · review · verdict · merge · handoff · obsidian · defect · stats · why · compare · playbooks · context · analyze · should_delegate · budget · doctor · ping · setup. Reference with arguments and return shapes: docs/reference.md. Adapters and what each CLI can do (verified live): docs/adapters.md. Security model: docs/security.md.

Configuration

.council/council.json — schema in council_mcp/config.py, example in templates/council.json. No secrets in the file; use ${ENV_VAR}. A task goes to the first model in by_role[role] that is also in by_privacy[privacy] and passed the probe. local-only tasks never leave your Ollama. Gates (gates.before_review, gates.after_merge) run in the task worktree before review and on the base branch after merge. Budget per task: 20 min soft / 25 min hard, 30 agent turns.

Development

uv sync
uv run pytest -q                 # respx / fake adapters; no live models
uv run ruff format . && uv run ruff check .
uv run mypy

CI runs the same gates on Ubuntu and Windows plus scripts/privacy_check.py. Design document (single source of truth, Polish): DESIGN.md. See CONTRIBUTING.md and SECURITY.md. Social graphics and post copy: docs/social/.

License

MIT. Company-specific profiles and examples live outside the core (profiles/, examples/).