Coniso

Coniso: context-isolated agent teams for Claude Code

by Palatine Labs · pronounced CON-ih-so (short for context isolation)

Call a role and it brings its team. Every agent works in a clean, small context, and a deterministic script handles the bookkeeping so no model has to.

Status: v1.2. The core is stable and in daily use. Expect sharp edges on uncommon setups. Please report them as issues.

Claude Code only. Coniso runs a local Python script, git worktrees and nested subagents, so it needs Claude Code: the terminal, an IDE extension, or the desktop app's Code tab. In claude.ai chat it installs but has nothing to run on. Cowork is untested.

The problem

Long Claude Code sessions on large codebases degrade in two predictable ways:

• Context bleed. One session accumulates file dumps, diffs, test logs and dead ends from every task it has touched. Later work is reasoned against that noise, instructions from early in the session get diluted, and quality drifts.
• Token waste. The same session re-reads all of that history on every turn. Ad hoc subagents help, but they usually hand raw output back up the chain, so the main context fills up anyway, just more slowly.

Coniso is built to reduce both, mostly through structure rather than prompting alone:

• Every subagent gets one packet in a fresh context and is told to return at most 12 lines. Detail (briefs, assignments, diffs, test logs, reports) lives in files under .coniso/, and agents are told to pass paths, not contents. That keeps raw output from climbing the hierarchy. It's a rule agents follow, not a limit the script enforces.
• A plain Python script, not an LLM, owns the bookkeeping: scheduling, dependency waves, sprint state, git worktrees, diffs, merges, plan validation and roadmap edits. No tokens are spent on graph math or rule checks a script can do.
• The main session is built to stay small for hours, and a sprint survives a restart ("director, continue").

Roles

The main session is always the top of the hierarchy. You call a role, and it brings the team it needs:

Support roles, spawned by leaders, never by you:

• Reviewer (coniso:reviewer, and coniso:reviewer-lite for small diffs: patch tickets, delta re-reviews, haiku batches): adversarial review against the acceptance criteria, within a tool-call budget the script sizes from the diff. Every finding needs evidence. It also hunts for gamed tests: deleted or loosened tests, hard-coded expected values, TODOs claimed as done. Builders never judge their own work.
• Auditor (coniso:auditor): a model one tier cheaper than the leader it audits. It challenges judgment calls (model tier, packet size, ordering, scope) and review rulings. Every overrule is logged, so the retro shows whose routing is going wrong.
• Scout (coniso:scout): read-only recon of a codebase area or docs question, written to a short map file.

Specialties (builder, tester, ui, net, level, audio, docs, batch, artisan, synth) are scoped guidance injected into a generalist engineer. They aren't personas with lanes to get stuck in.

Install

Inside Claude Code:

/plugin marketplace add Palatine-Labs/coniso
/plugin install coniso@coniso

Or from your shell:

claude plugin marketplace add Palatine-Labs/coniso

claude plugin install coniso@coniso

Install it from one source only. A copy added from Anthropic's directory on claude.ai appears in Claude Code as coniso@synced; if you also install coniso@coniso, disable one of them.

Requirements

• Claude Code with plugin support. Nested subagents give full parallelism; without them, relay mode keeps sprints working with less (see below). Developed and tested on v2.1.292. Older 2.1.x releases may work but aren't tested.
• Python 3.8+ on PATH as python3, python or py -3. Standard library only.
• git: each ticket builds in its own worktree. For non-code work, init with --no-worktrees.
• Windows, macOS and Linux.

Experimental flags

None required. Coniso runs on Claude Code's defaults. Two existing values would break nesting, and Coniso offers to fix them (see Permissions):

• CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH below 3: fix sets it to 3.
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1: fix sets it to 0. Coniso uses its own hierarchy, not experimental agent teams.

If nested spawning isn't available at all, leaders switch to relay mode on their own: they write spawn requests and the main session spawns for them. Sprints keep working; only parallelism drops. preflight (run on every call) reports which mode you're in.

Quickstart

1. Open Claude Code in a git repo with at least one commit.
2. Make a roadmap (optional for one-off calls, needed for sprints):

   /coniso:roadmap new My Project
   

   Claude settles the goal, stack and phases with you, then writes docs/roadmap/<Project>-Roadmap.html.
3. Call a role:

   /coniso:lead P1-01
   

   or describe a feature: /coniso:lead add CSV export to the reports page.
4. For a long session:

   /coniso:director P1
   

   The Director schedules ready tickets into waves, builds each in its own worktree, reviews them, and merges the ones that pass. It stops at phase gates for your go/no-go.
5. Check progress any time with /coniso:status. To resume in a fresh session, say "director, continue".

The first call runs init, which:

• installs .coniso/ and git-excludes it;
• finds your roadmap and your build and test commands;
• reports which permission rules would stop agents stalling on prompts. Claude then asks whether to add them (below).

Permissions

Coniso never changes your Claude Code settings without your yes. On the first call, Claude shows you exactly what it would add to .claude/settings.local.json and asks:

• allow rules for the Coniso script and your build and test commands, so agents don't stop on every prompt;
• an env fix, only if one of your current values breaks nested subagents (see above).

Say yes and it runs permissions --write. Say no and it records that and stops asking; Coniso still works, but agents may pause for approval. That file is local to you and git-excluded.

You can change your mind at any time, by asking Claude or running the script yourself:

Natural language works too ("call a lead on P2-04", "run a sprint on phase 2").

The HTML prompt roadmap

The roadmap is a single self-contained HTML file per project. It needs no server and no internet, and you open it in any browser. It holds phases, small tickets, a copy-ready prompt per ticket, and a recommended model and effort per ticket.

• On the page: set statuses, tick done-when items and write notes. These stay in your browser.
  • Copy prompt gives a fresh-session prompt with the project preamble included.
  • Copy Coniso command gives /coniso:lead <id>, or /coniso:director <phase> from a phase header.
  • Save updated file downloads the roadmap with your changes.
  • Copy status for Claude gives a summary to paste into a session.
• Keep it current: /coniso:roadmap next shows what's next. Pasting status, or asking to "expand phase 2" or "revise tickets after we switched to Postgres", updates the file through the script. The script validates every write, merges browser and Claude edits without clobbering, and refuses to delete done tickets.
• How sprints use it: the Director builds from it. After each wave, roadmap-sync moves merged tickets to review with Claude: notes and bumps the revision. Tickets are never marked done for you. Clicking through and marking done stays yours.

Roadmap work needs no Coniso setup and works in non-git folders too.

Token usage and cost

Being straight about this:

• Coniso does not use fewer total tokens than doing the same work yourself in one session. A ticket costs one builder plus at least one reviewer, and leaders add auditors. Each agent reads the brief and its own assignment. That overhead is the price of independent review and isolated contexts.
• What it does is keep every context small and bounded. The main session doesn't grow with the work, so it doesn't pay to re-read hours of history on every turn, and late work isn't reasoned against the noise of early work. For long sessions on large codebases we expect this to be a net saving, though we haven't published measurements. For a ten-minute fix it isn't. Just ask Claude directly.
• It spends where it matters: haiku for mechanical packets, sonnet as the workhorse, opus only for load-bearing work and leadership. A ticket that fails twice moves up one model tier, and a third fail stops and asks you. S and M tickets run as one engineer plus one reviewer, with no team overhead.
• Parallelism multiplies spend rate. By default, a Director sprint can run up to ~20 subagents at once. That finishes sooner but burns your plan's usage or API budget faster.
• Levers:
  • /coniso:director … light halves concurrent builds and uses single reviewers.
  • Prefer /coniso:lead for single tickets over a full sprint.
  • When cost has to drop, Coniso cuts breadth (fewer concurrent units) before it ever cuts review.
• The main session stays lean by construction (v1.1):
  • Compound commands. dispatch, review, verdict and land turn the Director's per-ticket bookkeeping (worktree, assignment file, plan validation, review setup, verdict rules, merge, roadmap sync) into a handful of script calls, chained with &&. A solo ticket now costs the Director about 5 tool calls instead of about 13.
  • Mechanical rules go to the script, not to auditors. Reviewers record their own verdicts with verdict, which applies the ruling rules and asks a leader only when judgment is needed. Plans that are exactly the scheduled plan (MATCHES SCHEDULE) and lead hand-offs (validate-handoff) are checked without an auditor. Auditors still review every judgment call.
  • Quiet run. The Director writes nothing between tool calls. An optional output style makes that session-wide (below).
  • Measured, not guessed. Each agent's reported token use is recorded per ticket (--tokens), and retro totals it per ticket and per role.
  • Coordinators rotate. A fresh Review Lead every 3 review rounds, a fresh manager every 3 waves, and a restart point for the Director every 3 merged waves keep long-lived contexts short. All state is on disk.
• Small fixes get a small path. An XS ticket (adhoc --size XS) is a patch: one engineer told to make the smallest change, then one light reviewer (coniso:reviewer-lite, sonnet at medium effort) with a budget sized to the diff. Every reviewer's budget is sized that way (12 tool calls under 60 changed lines, up to the full 40 or 60 above 300), so small tickets stop paying for a ceiling they never used. An XS diff that grows past 80 lines or 4 files is promoted to the normal review by the script, never downgraded.
• Your test suite runs once per tree, not three times per ticket. test reuses a passing run while the worktree is unchanged, land reuses it when the squash is byte-identical to the tree it passed on, and several passed tickets land as one batch with one integration run (a failure falls back to one at a time). --fresh forces a rerun.
• The Director can make a bounded quick fix. When a review or integration fail comes down to a few named lines (a seam between two tickets, a missed import), quickfix lets the Director fix it in the ticket's worktree instead of resuming a builder. The script enforces the limit (20 changed lines in 2 files, one attempt), runs the checks, and sends the change to a delta review. It never merges unreviewed.
• Auditors read a slice, not the sprint. Every validated plan comes with a .ctx.md of one line per ticket; that, not the ever-growing sprint.json, is the auditor's context.
• Idle cost is small: about 600 tokens per session while installed, whether or not you use it. The compaction hook prints nothing outside an active sprint.
• Rule of thumb: use Coniso on a usage-based plan with headroom or an API budget you've set limits on. Watch your first sprint's usage before running unattended (permissions --accept-edits).

Hooks and output style

• Compaction hook. Coniso ships one plugin hook (hooks/hooks.json): on SessionStart with matcher compact, it prints the open sprint board and the current wave, so a Director whose context was just compacted picks up from files instead of memory. In a project without an active sprint (.coniso/sprint.json) it prints nothing and exits 0. It runs python3, python or py -3, whichever works, through Claude Code's hook shell (Git Bash on Windows).
• Quiet output style (optional). Coniso Quiet (output-styles/quiet.md) tells Claude to write nothing between tool calls and speak only for status lines, decisions you own, errors and final reports. It keeps Claude Code's coding instructions and is never forced on. Pick it in /config → Output style for long sprints.

Commands

Always-on footprint: about 600 tokens per session (measured with claude plugin details coniso): one short skill description, one-line agent descriptions, and role commands that Claude can't auto-invoke. Each role's full procedure loads only when you call it.

Script reference (.coniso/coniso.py)

Stack packs

init --stack <name> installs a pack from the plugin's stacks/<name>/ folder. A pack can provide:

• rules.md, added to the brief;
• specialties/*.md, extra engineer specialties;
• stack.json, with optional check_cmd, setup_cmd, build_cmd and review_lens;
• proving.md, a pass the Director runs after each wave.

{python} and {stack} in commands expand to the interpreter and the installed pack folder. Coniso ships no packs yet. The mechanism is there for your own. Contributions are welcome.

Guarantees and notes

• Coniso doesn't push. The script has no push command, and agents are told never to push. Sprint sync never marks roadmap tickets done, and merges refuse to run over uncommitted work rather than stashing or touching it.
• What it runs and touches: your build and test commands, git (worktrees, branches, squash merges on your current branch), and its own files under .coniso/ and .git/info/exclude. With your yes, it edits .claude/settings.local.json. Agents' own web lookups (scouts) go through Claude Code's tools. Coniso sends nothing anywhere itself.
• The merge gate checks the integrated code. A ticket needs a passing review. Each merge then squashes it, runs your build and tests on the integrated result, and resets the branch untouched if anything fails or conflicts. Limits: with no build or test command set, preflight warns and the merge rests on review alone; merge --force and --no-test overrides exist (--force is reserved for your say-so); --no-worktrees mode has no merge gate; and it's a rule, not a lock, so an agent with shell access could still commit directly.
• Worktrees live in .coniso/wt/. If a tool in your repo scans dot-folders (some eslint or jest setups), add .coniso to its ignore list.
• Leave the main checkout alone during a sprint: merges need it clean.
• Lessons loop: when you critique an agent's work, a one-line lesson goes to docs/agent-feedback/<specialty>.md, and engineers read it before working.

Contributing and security

• Contributions: see CONTRIBUTING.md.
• Vulnerabilities: report privately per SECURITY.md. Please don't use public issues.
• Privacy: Coniso collects and sends nothing. See PRIVACY.md.

License

Apache License 2.0. See LICENSE and NOTICE.

Coniso is an independent project by Palatine Labs and is not affiliated with or endorsed by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic, PBC.