The High Council

Try it in 30 seconds

npx the-high-council council demo

No keys, no network, $0. Add it to Claude Code as an MCP server:

claude mcp add council -- npx -y the-high-council council --mcp

Claude Desktop, the plugin and other clients: Use it with your coding agent.

Contents

• This page: What you get · What's new · Your first run · Pricing · Known limits · Privacy
• The manual: AI-Readme (the full text) · Your first ten minutes · How it works · Chains · The spend cap · Accessibility
• More: Troubleshooting · Agent skills · Personas · Contributing · Changelog

What you get

1. Criteria before planning. Your request becomes a short list of yes/no checks the plan has to pass, written before anyone plans.
2. Blind proposals and a recorded debate. Each lab proposes without seeing the others, then reads the rest with the names hidden and posts support, an objection or a merge. Every author then keeps, amends or withdraws its own proposal, on the record.
3. Review and revision. A panel of judges checks the draft against the criteria, and a failed check sends it back for a revision. The planning chains judge in three layers. An objection that was never settled stays on the record; nothing is averaged away.
4. A handoff for building. HANDOFF.md is written for whoever builds the plan: the acceptance checks and the instructions a coding agent works from, and in the planning chains the milestones too.

Every run writes a folder, runs/<id>/:

On what this does and doesn't claim. This repo publishes the mechanism: the chains, the seat rosters, the stage order. Exact effectiveness numbers are not measured yet. We did have a selected Council debate measured by frontier AI on the run that planned update 0.8.3: the plan improved in every measured rubric but one, and that one was that it got longer and harder to read. What the repo does, concretely, is make disagreement between models visible and recorded instead of averaged away - you can read who objected to what, who withdrew a proposal under argument, and who held their position.

What's new in 0.8.4

• The ladder is the shape of every shipped planning chain. Layer 1 revises in blocks, layer 2 is asked in visits, then layer 3 reads. There is no round limit, so a run ends on agreement, on a stall the top layer holds, or at the limit you type or when you stop it.
• A plan the panel did not agree on can be accepted as it stands. council accept records who accepted it, when and why, and which objections and late findings still stand. It agrees with no judge and marks nothing agreed.
• You can give the judges a ruling in the middle of a run. council ruling-add asks for a ruling; once you have approved it, the judges and the reviser read it from the next pass on.
• Excerpts. The session that handles the run can add text from your project during the run: files it read, or passages a judge or a proposer asked for. Every later seat is shown the text.
• Seat personas. A seat can carry a name as its title or, with an optional feature, debate in the voice of that persona (PERSONAS.md).
• Gone: the experimental advice add-on. Changed: the default spending cap is $12 (it was $7), and Node.js 24 or newer is the supported version.

0.8.4 also changes things a script or a client may rely on. Read "Changes that can break a script or a client" in the CHANGELOG before you update.

What's new in 0.8.3

• Recursive Councils - "Plans within Plans within Plans"

Your first run

The quick-start chain, plan-mini-council (it is also the default chain), needs an OpenRouter API key (one account that reaches many labs' models) and an agent session of your own, such as Claude Code, that answers its writer stages. With an Anthropic API key as well, its Claude seats are called at Anthropic directly; without one they go through OpenRouter.

1. Keys. Put the keys in a file called .env in the folder you run from:

   dotenv

   ANTHROPIC_API_KEY=your-key-hereOPENROUTER_API_KEY=your-key-here

   Add .env to your .gitignore (and runs/ if your ideas are private).

2. Your task.

   bash

   npx the-high-council initnpx the-high-council doctor

   init writes tasks/my-first-task.md. Edit it into your own idea, in plain words: what you want, the constraints that matter, and what done looks like.

3. Price it, then run it.

   bash

   npx the-high-council --task tasks/my-first-task.md --chain plan-mini-council --dry-runnpx the-high-council --task tasks/my-first-task.md --chain plan-mini-council --max-usd 12

• The limit. The first command spends nothing. A paid run starts only after you type its spending limit on a screen; --max-usd 12 puts $12 there as the suggestion.
• Pauses. A run can also pause and wait for an answer from your Claude Code session, or from you: the quick-start chain's writer stages (skeleton, build, revise and handoff) are such pauses, and so is a swing between two judge layers' objections.
• A stop at the limit. A run that stops at its limit keeps every stage it paid for. npx the-high-council --resume runs/<id> continues it: the screen asks for a new total above what the run has counted, and the finished stages cost nothing the second time.

Use it with your coding agent

Runs as an MCP server (so a coding-agent session such as Claude Code can drive it) or as a CLI. Bring your own API keys. Nothing is resold, nothing is hosted for you, and your keys go only to the providers you choose, never to us.

• Claude Code: the claude mcp add command under Try it in 30 seconds adds the server. Or install it as a plugin, which registers the same server and also installs the skills in skills/:

  bash

  claude plugin marketplace add muad-yasin/the-high-council-mcpclaude plugin install the-high-council@the-high-council

• Claude Desktop: download and open the-high-council-<version>.mcpb from Releases.

• Anything else: Other MCP clients · Plugin settings and keys · Standalone binaries

Pricing

What each shipped chain costs per run, in US dollars. council doctor prints the same expected figures; --dry-run prices your own task, and a longer task costs more.

• Expected is worked out by the code before anything is sent, from the shipped price table and the chain's own size estimates.
• The shipped planning chains have no round limit: there Expected assumes three top-layer reads, an assumption that a lower number you type with --rounds replaces.
• A run can cost more than Expected. The limit you type is what stops it.
• Tested is what real runs cost; – means no run has been reported yet.
• Seats your Claude Code session answers cost $0 here, because they run on your own subscription.

With recursive councils, a tree at the default limits runs up to 12 councils (the root and 11 sub-plans): the root on the chain you name with --chain, each sub-plan on the chain you name with --child-chain, or on the root chain when you name none. With one chain throughout, which is the default, you pay for up to 12 runs of that chain; council tree start --dry-run prints the projection for your own task and chains, and the limit you type stops the tree.

Ran one of these chains? CONTRIBUTING.md says how to send us the figure.

Recursive Councils: Plans within Plans within Plans

Since 0.8.3. A milestone of the plan can get a Council of its own, and its milestones can again, so the runs form a tree under one root plan. You type the tree's spending limit once, and every sub-plan runs under it. A sub-plan inherits the acceptance criteria its parent delegates to it and cannot narrow the ones that hold for the whole tree. Approvals, and the decisions taken when a run gets stuck, are recorded, and the record says who made each: you, or the Claude Code session driving the tree.

Price a whole tree before anything is spent:

npx the-high-council tree start --task tasks/my-first-task.md --chain plan-mini-council --dry-run

Without --child-chain the sub-plans run on the root chain, so a root on a High chain plans its sub-plans at High prices; the projection shows the price.

Tree commands and exit codes

Known limits, stated plainly

What this version cannot promise is written down limit by limit in KNOWN-LIMITS.md: what the spending limit can and cannot hold, what has run only with mock seats or has not been verified, and what a run's record cannot know.

Privacy

This tool collects nothing. Stated plainly, not as a claim about quality:

• No telemetry, no analytics, no tracking of any kind, anywhere in this repo.
• The network calls this tool makes are to the AI provider APIs you configure with your own keys (ANTHROPIC_API_KEY, OPENROUTER_API_KEY, and so on), when you start a real run with a non-mock, non-external seat, and two public requests to OpenRouter that send no key and nothing of your project: council refresh-zdr-list (OpenRouter's list of zero-retention hosts), and the look-up of the hosts that serve one model (named by its id in the address), which the price_raise tool makes and which a run makes at a terminal when a price refusal stops it (exit 24). council doctor and council demo make zero network calls; both are implemented to read only local files and environment variable names.
• The landing page in docs/ ships no JavaScript and loads no third-party resource - see test/landing-page.test.js, which fails the build if either ever changes.
• Everything a run produces - the task, the debate, the deliverable, the cost - is written to a folder on your own disk (runs/<id>/) and nowhere else. Deleting that folder deletes the record. See src/spend.js's own documentation for why spend accounting is derived from those folders rather than kept in a separate log.
• Personal data. A run sends your task to the providers your chain names. Keep personal data out of it where you can.
  • The check. Every run checks the task for an email address, an IBAN or a card number before anything is sent, and stops by default when it finds one: nothing is sent or spent. To send it anyway, run the same command again with --allow-pii <types>. It does not recognise names, addresses or other personal details.
  • What it shows. The stop and the logs name the kind of match and where it is (line and column), never the value: on a stop the lines are printed (over MCP they go to the start's log file) and no run folder exists yet; under warn the run goes on and writes the same lines to its run.log, and a tree member also to its WARNINGS.md.
  • The law. If you have to send personal data, use providers that sign a data processing agreement with you. Whether a run complies with the GDPR depends on those agreements and on what your task contains; THC makes no claim about it.
• If you opt in to the audit export ("audit": true, and on automatically whenever a policy.json exists), each run also writes audit.jsonl into its own folder: signed, hash-chained lines (each carries the previous line's hash) that verifyAuditLog in src/audit.js checks offline. Seat, cost and timing only, never task or prompt text. Format: docs/audit-schema.md.

Reporting a bug

Open an issue at github.com/muad-yasin/the-high-council-mcp/issues. For anything security-related, or that should not be public, write to [email protected] instead.

If this makes you money

The licence is MIT. You owe nothing, and that is the whole licence - nothing below changes it.

If The High Council ends up helping you build something that earns, I'd ask for 0.7% of what it earns. Not a fee, not a clause, not a subscription. A request between people who build things.

There is no reporting, no audit, no tracking, and nothing checks. No is a complete answer - use it, fork it, sell what you build with it, and never think about this section again. That is a fine outcome and it's why the licence says what it says.

If you'd rather say yes: pay what you think it's worth.

License

MIT. See LICENSE. The section above is a request, not a term of it.