📖Installation Guide · ~2 min read

Install BroziCode
in Claude Code

BroziCode is a free, open-source MCP plugin — a Claude token optimizer and cost reducer that swaps Claude Code's micro-tool loops for two high-leverage Macro-tools. This guide walks you from zero to 85% fewer tokens in under 2 minutes.

85%fewer tokens

6×fewer API calls

2 minto install

MITfree forever

Prerequisites

Make sure you have these before starting.

⚡Claude Code CLI

Anthropic's official terminal agent. Install via npm.

npm install -g @anthropic-ai/claude-code

🟢Node.js 18+

Required to run the BroziCode MCP server process.

node --version # must be ≥ 18

Install in 4 steps

Plugin install recommended — it ships with hooks, agents, and skills. MCP-only is available if you just want the two tools.

Install the plugin

Choose the method that works best for you. The plugin install is recommended — it includes session-tracking hooks, built-in agents, and skills on top of the two Macro-tools.

Method A — Claude Plugin (recommended — hooks, agents & skills included)

These are slash commands run inside a Claude Code session. Start Claude Code first, then run:

inside a claude session

# Step 1: register the BroziCode marketplace
/plugin marketplace add BroziCode/brozicodes-claude

# Step 2: install the plugin from that marketplace
/plugin install brozicode@brozicode-marketplace

Method B — MCP only (tools only, no hooks or savings tracking)

terminal

claude mcp add brozicode -- npx -y @brozicodes/mcp

Use this if you only want the two Macro-tools and don't need session tracking hooks, built-in agents, or skills.

Reload & verify

After install, reload within your Claude Code session. Then run the info skill to confirm everything is wired up:

inside a claude session

# Plugin install (Method A):
/reload-plugins

# Verify — should show v0.3.0, both tools, and all hooks:
/brozicode:info

# MCP only (Method B): restart Claude Code, then:
/mcp   # brozicode should appear with brozi_smart_search + brozi_batch_edit

Configure your CLAUDE.md

The plugin's built-in agent already enforces macro-tool usage when you invoke the brozicode sub-agent. To enforce it for the default Claude agent too, add this to your CLAUDE.md:

CLAUDE.md

## File operations
- NEVER use Read, Edit, Write, Grep, Glob for file work
- ALWAYS use `brozi_smart_search` to find / read files
- ALWAYS use `brozi_batch_edit` for all file writes and edits
- Batch as many edits as possible into a single `brozi_batch_edit` call

Without this, the default Claude agent may still fall back to native tools outside of the brozicode sub-agent and you'll miss the savings.

Understand the agent model

After install, the default Claude Code session still runs the standard Claude agent — not brozicode. The plugin registers brozicode:brozicode as a sub-agent that can be invoked explicitly or auto-delegated to.

Option 1 — CLI flag (per-session)

Launch Claude Code with brozicode as the active agent for that session:

terminal

claude --agent brozicode:brozicode

Option 2 — global default (all sessions)

Set brozicode as the default agent for every claude session on your machine:

~/.claude/settings.json

{
  "defaultAgent": "brozicode:brozicode"
}

Option 3 — CLAUDE.md (per-project)

The rules from Step 3 make the default agent enforce brozi tool usage on every session in that project — without a flag or global config change.

Option 4 — explicit per-task

Ask Claude in any session to delegate a task directly:

inside a claude session

Use the brozicode agent to refactor this module.

Claude spins up brozicode:brozicode as a sub-agent for that task, no config needed.

The two Macro-tools

BroziCode exposes exactly two tools. Each one replaces a whole category of Claude's micro-tool loops.

🔬

brozi_smart_search

Replaces: grep, cat, head, tail, find, Glob, Read

Multi-file search, read, and AST-summary in a single call. Instead of Claude issuing 20 sequential Read() calls, BroziCode fetches everything in one round-trip — with optional regex filtering, line ranges, and TypeScript/JavaScript AST skeletons that collapse 2,000-line files into 150-line signatures.

Parameters

file_glob_patterns

string[]

Glob patterns to match files. Append #N-M to a path to read only those line numbers. e.g. ['src/**/*.ts', 'utils.ts#10-60']

content_regex

string

Only return files whose content matches this regex. Works like grep -r.

output_mode

enum

file_paths_with_content (default) | file_paths_only | file_paths_with_match_count. Use file_paths_only for cheapest discovery.

summary

boolean

When true, returns a JS/TS AST skeleton — function signatures and exports — instead of raw source. Reduces token usage by ~10×.

if_modified_since

ISO string

Skip files not modified after this timestamp. Useful for caching repeated reads in long sessions.

type

string

Extension filter without dot: 'ts', 'js', 'tsx', 'sql', etc.

lines_before / lines_after

number

Context lines around regex matches — like grep -B and grep -A.

Usage examples

Find all TypeScript files and get their API surface

brozi_smart_search({
  file_glob_patterns: ["src/**/*.ts"],
  summary: true
  // Returns function signatures only — not 40k lines of code
})

Grep across codebase, return match counts

brozi_smart_search({
  file_glob_patterns: ["src/**/*.ts"],
  content_regex: "useAuth",
  output_mode: "file_paths_with_match_count"
  // Returns: [{file: 'auth/index.ts', count: 12}, ...]
})

Read specific line ranges from multiple files at once

brozi_smart_search({
  file_glob_patterns: [
    "src/api/routes.ts#1-80",
    "src/middleware/auth.ts#20-55"
  ]
  // One call replaces two Read() calls
})

⚡

brozi_batch_edit

Replaces: Read → Edit → Write → Verify loops

Apply multiple file edits in one operation with optional local validation. Instead of Claude reading a file, applying an edit, then re-reading to verify — all as separate API calls — BroziCode batches everything into a single round-trip. Whitespace differences in oldContent are tolerated automatically, and you can run TypeScript or ESLint validation before Claude ever sees the result.

Parameters

edits[].file

string

Absolute path to the file. Use CLAUDE_PROJECT_DIR as base for relative paths.

edits[].oldContent

string

Exact block of text to find and replace. Omit entirely to create a new file. Whitespace differences are tolerated.

edits[].newContent

string

The replacement text, or the full file content when creating a new file.

edits[].overwrite

boolean

When true and oldContent is absent, replaces the entire file content.

validate

enum

Run local validation after all edits: none (default) | tsc | eslint | both. Errors block Claude from proceeding with bad code.

stopOnFirstError

boolean

Abort all remaining edits if one fails. Default: true.

Usage examples

Edit two files in one call with TypeScript validation

brozi_batch_edit({
  edits: [
    {
      file: "/project/src/auth/index.ts",
      oldContent: "export function login(user: string) {",
      newContent: "export function login(user: string, mfa = false) {"
    },
    {
      file: "/project/src/types.ts",
      oldContent: "login: (user: string) => void",
      newContent: "login: (user: string, mfa?: boolean) => void"
    }
  ],
  validate: "tsc"
})

Create a new file (omit oldContent)

brozi_batch_edit({
  edits: [
    {
      file: "/project/src/utils/format.ts",
      newContent: "export const formatDate = (d: Date) => d.toISOString()
"
    }
  ]
})

The difference in practice

Same 3-file refactor. Radically fewer round-trips.

Without BroziCode — 12 calls

Read("auth.ts") → 1 call

Read("types.ts") → 1 call

Read("routes.ts") → 1 call

Edit("auth.ts") → 1 call

Edit("types.ts") → 1 call

Edit("routes.ts") → 1 call

Read("auth.ts") → verify

Read("types.ts") → verify

Read("routes.ts") → verify

Grep("loginFn") → check

Read("auth.ts") → fix

Edit("auth.ts") → fix

Total: ~85k tokens · $0.47

With BroziCode — 2 calls

brozi_smart_search({

["auth.ts","types.ts","routes.ts"],

summary: true

}) → 1 call

brozi_batch_edit({

edits: [3 changes],

validate: "tsc"

}) → 1 call

Total: ~12k tokens · $0.07

Frequently asked

Does BroziCode work with Claude.ai (the web app)?

No — BroziCode is a Claude Code MCP plugin, designed specifically for the Claude Code CLI and its agentic coding loop. It does not work in the browser chat interface.

Will BroziCode break my existing Claude Code setup?

No. BroziCode only adds two new tools. Claude's native tools remain fully available. The savings only kick in when Claude (or your CLAUDE.md) instructs it to use the Macro-tools instead of the micro-tools.

Is my code sent to any BroziCode server?

Never. BroziCode is a local MCP server running as a Node.js process on your machine. It reads and writes files locally, and communicates with Claude Code over stdio. No data leaves your machine.

Does it work with non-TypeScript projects?

Yes. brozi_smart_search works on any file type via glob patterns and regex. The AST summary feature (summary: true) and tsc validation are TypeScript/JavaScript specific, but everything else is language-agnostic.

How does the token saving actually work?

Each API call to Claude includes the full conversation history. A 12-call session re-sends that history 12 times — each time larger. BroziCode collapses those 12 calls into 2, so your history is sent twice, not twelve times. The savings compound as the context grows.

Ready to stop burning tokens?

Star the repo to follow along, or get notified when v1 ships.

View on GitHub →Get Early Access

Install BroziCodein Claude Code

Prerequisites

Install in 4 steps

Install the plugin

Reload & verify

Configure your CLAUDE.md

Understand the agent model

The two Macro-tools

Parameters

Usage examples

Parameters

Usage examples

The difference in practice

Frequently asked

Does BroziCode work with Claude.ai (the web app)?

Will BroziCode break my existing Claude Code setup?

Is my code sent to any BroziCode server?

Does it work with non-TypeScript projects?

How does the token saving actually work?

Ready to stop burning tokens?

Install BroziCode
in Claude Code