claude-agent-kit

Seven Claude Code subagents, orchestration rules for the main session, and a read-budget hook.
Cheap models do the I/O and the implementation; Opus spends its context on judgment and on the
review gate.

Quick start

Inside Claude Code:

/plugin marketplace add FlaviusBurghila/claude-agent-kit
/plugin install agent-kit@agent-kit

Then, in each project:

/agent-kit:init      # writes the project's ## Agent contract into its CLAUDE.md
/agent-kit:doctor    # checks the setup, changes nothing

From a shell: claude plugin marketplace add FlaviusBurghila/claude-agent-kit && claude plugin install agent-kit@agent-kit
(add --scope project to the install to record it in the repo's .claude/settings.json).

Prerequisites: Claude Code 2.1.293 or later (2.1.246 is the minimum, for maxTurns partial
results), Node.js 18+ for the hooks, and model access to Opus, Sonnet and Haiku. The install
script also needs macOS, Linux or WSL, bash, and curl and tar (or git).

What you get

The plugin names the agents agent-kit:scout, agent-kit:builder and so on; the install script
uses the bare names.

Also included: the orchestration rules (agent-kit/orchestration.md), the read-budget hook
(agent-kit/hooks/shunt.js), the init and doctor skills, and templates for a project
CLAUDE.md and its ## Agent contract with starter lines for Flutter/Dart, Rust,
flutter_rust_bridge, TypeScript/Node, Python and Go.

How it works

The orchestration rules tell the main session (the Orchestrator) how to brief, delegate and
review. The plugin's SessionStart hook reaches only the main session and injects a short stub; a
UserPromptSubmit hook loads the full rules once the context passes 80,000 tokens (set
AGENT_KIT_ENGAGE_TOKENS to change it; 0 loads them at session start, the old behavior). The
rules re-engage after compact or clear. The install script loads them always, with an @ import
in CLAUDE.md; the hooks stay quiet when they find that import. A run that does not load user
memory (--setting-sources project,local, SDK settingSources without user) should set
AGENT_KIT_IGNORE_SCRIPT_INSTALL=1, or the plugin's hooks stay quiet and no rules load. The rules engage on the next prompt after the threshold is crossed, so a single
long headless claude -p turn keeps the stub (the read-budget hook applies from the first call).
After a compact they re-engage on the first prompt (the last usage recorded is the pre-compact
size); that is intended, since compaction drops them. They do not depend on the project's
CLAUDE.md or CLAUDE.template.md. To confirm they loaded, run /context and look under "Memory
files" (script install); with the plugin they appear once the context passes the threshold, or
set AGENT_KIT_ENGAGE_TOKENS=0. The workers don't spawn agents of their own (disallowedTools: Agent), so every
delegation goes through the Orchestrator.

Project facts (verify commands, test policy, excluded paths, generated files, traps) live in the
## Agent contract section of the project's CLAUDE.md, which every subagent loads, so the agents
stay stack-agnostic. Without a contract the orchestration still runs, but the agents have no
verify commands or exclusions to follow.

A file read into the main session stays in the prompt for every later turn. The hook denies
whole-file reads over 350 lines (Read, and cat, head, tail, sed -n, git show through
Bash) in the main session, builder, refuter and debugger, and points to a ranged read or
the Bulk-reader. The I/O agents (scout, bulk-reader, code-writer, researcher) are exempt.

Credits

The read budget, the Bulk-reader and the Code-writer come from Spotify's
shunt plugin, described
in "Portal by Spotify cut my Claude Code token usage by 90%" (see Sources). Its key idea is that a
frontier model should not spend its context on I/O. Shunt blocks large reads and sends them to a
cheaper external model through scripts. The kit keeps the idea and the SHUNT_MIN_LINES=350
threshold, but delegates to Claude Code subagents, so it needs no external CLI or model. The hook
is a separate Node.js implementation. It also counts ranged reads, sed -n, git show and
multi-file cat, and it applies to the main session and selected subagents.

The orchestration side draws on Cognition (see Sources). In their measurements the lead model that
cost less took fewer turns, carried less context, handed work off early with briefs that state
constraints rather than code, and made few edits itself; short tasks barely delegated, and forcing
delegation lowered quality. Their review step was a cheap diff check, not a second expensive pass.

When this helps

The kit pays off when a session would otherwise fill its context: large files, many files, long
sessions, smaller context windows. On short tasks it should cost about the same as a plain session,
and it does nothing extra. An independent benchmark
(clone45/claude-agent-kit-benchmark)
measured version 1.0.0, which loaded the full rules into every session, at 21 to 26 percent more
per task than plain Opus 5.5 on short tasks, with the same quality. A rerun of its click phase on
1.1.0 (102 runs) measured 7 percent more ($0.264 against $0.246 per task, inside the run-to-run
spread), 50 of 51 runs passing in each condition. Neither run reached the conditions above, so
the savings side is still unmeasured.

Install for a team

Commit this to the repo's .claude/settings.json. Teammates get the plugin once they trust the
folder:

{
  "extraKnownMarketplaces": {
    "agent-kit": {
      "source": { "source": "github", "repo": "FlaviusBurghila/claude-agent-kit" }
    }
  },
  "enabledPlugins": {
    "agent-kit@agent-kit": true
  }
}

Run /agent-kit:init once and commit the CLAUDE.md it writes.

Install script (alternative)

Use the script when you want the agents copied into .claude/ and committed with the repo, or
can't use plugins. Don't combine it with the plugin: you would get both builder and
agent-kit:builder.

# global: every project on this machine
curl -fsSL https://raw.githubusercontent.com/FlaviusBurghila/claude-agent-kit/main/install.sh | bash -s -- --global

# project: the current repo (or pass a directory: --project DIR)
curl -fsSL https://raw.githubusercontent.com/FlaviusBurghila/claude-agent-kit/main/install.sh | bash -s -- --project

Or clone and run it:

git clone https://github.com/FlaviusBurghila/claude-agent-kit.git
cd claude-agent-kit
./install.sh --global                          # or:
./install.sh --project /path/to/your/repo

To pin a release, set KIT_REF to its tag: ... | KIT_REF=v1.0.0 bash -s -- --global.

• Global writes under ~/.claude and applies to every project on this machine; teammates do not
  get it.
• Project writes under <repo>/.claude; commit it and the team gets the same agents. A project
  agent overrides a global one of the same name.
• Project also adds a ## Agent contract scaffold to CLAUDE.md and .claude/tmp/ to
  .gitignore (in a git work tree).

After --no-claude-md or --agents-only the orchestration rules don't load until you add the
import line the installer printed.

The installer's CLAUDE.md block is delimited by <!-- claude-agent-kit:begin --> and
<!-- claude-agent-kit:end -->; re-running replaces what is between them and nothing else. Every
file it changes is first backed up to ${CLAUDE_CONFIG_DIR:-~/.claude}/backups/claude-agent-kit/<timestamp>/.
Re-running is idempotent, which is also how you update. settings.json must be plain JSON:
comments or trailing commas make the installer stop before changing anything.

After a script install:

1. Fill in ## Agent contract in the project's CLAUDE.md. Starter lines are in
   agent-kit/agent-contract.template.md.
2. Restart Claude Code if the agents directory did not exist before.
3. If Claude Code asks you to approve the CLAUDE.md import, approve it.
4. Make sure .claude/tmp/ is gitignored: agents write scratch files and long reports there.

Configuration

• SHUNT_MIN_LINES: the read threshold (default 350). Set it in the env of settings.json
  and keep the Agent contract's "Read threshold" line in step; the hook reads only this variable.
• SHUNT_OFF=1: disables the hook.
• The built-in Explore agent runs on the main session's model, so cheap I/O can drift to Opus.
  To remove it, add "permissions": { "deny": ["Agent(Explore)"] } to settings.json.
• The agent files name models by alias (haiku, sonnet, opus), never by version, so the kit
  follows new releases. To pin a version, set ANTHROPIC_DEFAULT_HAIKU_MODEL,
  ANTHROPIC_DEFAULT_SONNET_MODEL or ANTHROPIC_DEFAULT_OPUS_MODEL in the env of
  settings.json; that changes the alias for the whole session. See the
  model configuration docs.

Updating

Third-party marketplaces don't auto-update by default. Run
claude plugin marketplace update agent-kit && claude plugin update agent-kit@agent-kit, or turn
on auto-update for the marketplace in /plugin → Marketplaces. A running session keeps the
version it loaded; start a new session to apply the update.

Troubleshooting

• Agents not listed: after a plugin install, run /reload-plugins; after a script install into a
  new agents directory, restart Claude Code. claude plugin details agent-kit lists what the
  plugin loaded.
• Orchestration rules don't load (plugin): check that Node.js 18+ is on the PATH Claude Code
  runs hooks with, and run with --debug to see the SessionStart hook's output.
• Import not applied (script): approve it if Claude Code asked; until then the rules are not
  loaded. After --no-claude-md or --agents-only, add the line the installer printed to a
  CLAUDE.md, or re-run without the flag.
• A project agent shadows a global one: remove or rename the project copy.
• The hook blocks a read you need: Read a range with offset/limit, ask the Bulk-reader, or
  set SHUNT_OFF=1.

Uninstall

claude plugin uninstall agent-kit@agent-kit     # plugin
./install.sh --uninstall --global               # script, global
./install.sh --uninstall --project              # script, project

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.

Sources

• Spotify, "Portal by Spotify cut my Claude Code token usage by 90%" (3 Sep 2026) —
  https://engineering.atspotify.com/2026/9/portal-by-spotify-cut-my-claude-code-token-usage-by-90;
  the shunt plugin (Apache-2.0): https://github.com/spotify/portal-ai-plugins
• Cognition, "Making Fable cheaper than Opus" (13 Jul 2026) —
  https://cognition.com/blog/making-fable-cheaper-than-opus
• Claude Code docs: "Create custom subagents" (https://code.claude.com/docs/en/sub-agents),
  model configuration (https://code.claude.com/docs/en/model-config),
  hooks (https://code.claude.com/docs/en/hooks), plugin manifest and marketplace references
  (https://code.claude.com/docs/en/plugins/manifest-reference,
  https://code.claude.com/docs/en/plugins/marketplace-reference)