Brutalist MCP

Multi-perspective code analysis using Claude Code, Codex, and Antigravity (agy) CLI agents.

Gemini → Antigravity transition (May 2026). Google sunsets gemini-cli for Pro/Ultra/free users on 2026-06-18. The successor agy (Antigravity v1.0.2) is now wired in as the third critic; it's slower per call (~30-60s vs 5-25s for claude/codex) and hard-pinned to Gemini 3.5 Flash (Medium) until Google ships agy #35 (per-call --model), but auth + subprocess capture both work today.

Get direct, honest technical feedback on your code, architecture, and ideas before they reach production.

What It Does

The Brutalist MCP connects your AI coding assistant to three different CLI agents (Claude, Codex, Antigravity), each providing independent analysis. This gives you multiple perspectives on:

• Code quality and security vulnerabilities

• Architecture decisions and scalability

• Product ideas and technical feasibility

• Research methodology and design flaws

Real file-system access. Straightforward analysis. No sugar-coating.

Related MCP server: multi-ai-collab

Quick Start

Step 1: Install a CLI Agent

You need at least one of these installed:

# Option 1: Claude Code (recommended)
npm install -g claude

# Option 2: Codex
# Install from https://github.com/openai/codex-cli

# Option 3: Antigravity (agy) — the gemini-cli successor
curl -fsSL https://antigravity.google/cli/install.sh | bash
# Then ONE-TIME interactive auth (browser OAuth flow):
agy "hi"
# On macOS, the agent binary lives at ~/.local/bin/agy; the desktop IDE
# at ~/.antigravity/antigravity/bin/agy can shadow it on PATH. If both
# are installed, set AGY_BIN=$HOME/.local/bin/agy in your environment.

Step 2: Install the MCP Server

Choose your IDE:

Claude Code:

claude mcp add brutalist --scope user -- npx -y @brutalist/mcp@latest

Codex:

# Install globally once to avoid npx startup chatter
npm i -g @brutalist/mcp
# Add MCP using the installed binary (clean stdio)
codex mcp add brutalist -- brutalist-mcp

Configuring tool_timeout_sec for Codex: Codex's MCP client defaults tool_timeout_sec to 60 seconds, so configure the Brutalist server entry directly in ~/.codex/config.toml; it cannot be passed via codex mcp add.

Set it to at least 9000 seconds for a normal parallel roast. That leaves 30 minutes of transport and synthesis headroom beyond Brutalist's two-hour per-agent default; raise it further for multi-round debates:

[mcp_servers.brutalist]
command = "brutalist-mcp" # Ensure this matches your installation command
args = [] # Depending on your setup, this might be empty or contain arguments
tool_timeout_sec = 9000 # 2h critic budget + 30m client/synthesis headroom

Cursor: Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "brutalist": {
      "command": "npx",
      "args": ["-y", "@brutalist/mcp@latest"]
    }
  }
}

VS Code / Cline:

code --add-mcp '{"name":"brutalist","command":"npx","args":["-y","@brutalist/mcp@latest"]}'

Windsurf: Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "brutalist": {
      "command": "npx",
      "args": ["-y", "@brutalist/mcp@latest"]
    }
  }
}

Step 3: Verify Installation

# Check which CLI agents are available
cli_agent_roster()

Usage Examples

Analyze Your Codebase

# Analyze entire project
roast_codebase "/path/to/your/project"

# Analyze specific modules
roast_codebase "/src/auth"
roast_codebase "/src/api/handlers"

Validate Ideas

# Evaluate a product concept
roast_idea "A social network for developers to share code snippets"

# Review technical decisions
roast_idea "Migrating our monolith to microservices with Kubernetes"

Review Architecture

# System architecture analysis
roast_architecture "Microservices with event sourcing and CQRS"

# Infrastructure design review
roast_architecture """
API Gateway → Load Balancer → 3 Node.js services → PostgreSQL
Redis for caching, Docker containers on AWS ECS
"""

Security Analysis

# Authentication review
roast_security "JWT tokens with user roles in localStorage"

# API security check
roast_security "GraphQL API with dynamic queries and no rate limiting"

Compare Perspectives

# Get multiple viewpoints on technical decisions
roast_cli_debate "Should we use TypeScript or Go for this API?"

# Compare architecture approaches
roast_cli_debate "Microservices vs Monolith for our e-commerce platform"

How It Works

This MCP server coordinates analysis from locally installed CLI agents:

• Claude Code CLI - Code review and architectural analysis

• Codex CLI - Security and technical implementation review

• Antigravity (agy) CLI - Gemini 3.5 Flash-tier rapid pattern-scan critique

Each agent runs locally with direct file-system access, providing independent perspectives on your code and design decisions. Agy is structurally an agent (not a completion API) — it's slower per call and produces side effects under ~/.gemini/antigravity-cli/scratch/ (the adapter passes --sandbox to keep those out of the user's workspace).

Analysis time: Up to 25 minutes for complex projects. Thorough analysis requires time to examine code patterns, dependencies, and architectural decisions.

Pagination for Large Results

For analyses that exceed your IDE's token limit:

# Set chunk size for large codebases
roast_codebase({targetPath: "/monorepo", limit: 20000})

# Continue from cached output; omit resume
roast_codebase({targetPath: "/monorepo", context_id: "abc123", offset: 20000, limit: 20000})

# Use cursor-based navigation
roast_codebase({targetPath: "/complex-system", context_id: "abc123", cursor: "offset:25000"})

Features:

• Smart boundary detection (preserves paragraphs and sentences)

• Token estimation (~4 chars = 1 token)

• Progress indicators

• Configurable chunk size (1K to 100K characters)

• resume: true is only for new follow-up prompts and starts another agent run

Tools

Code & Architecture

Design & Planning

Utilities

Tip: Use the unified roast tool with a domain parameter for a leaner schema, or use brutalist_discover to find the right tool based on your intent.

See docs/pagination.md for detailed pagination documentation.

Advanced Usage

Choose Specific CLI Agents

# Default: run all available critics in parallel (recommended)
roast(domain="codebase", target="/src")

# Restrict to a subset only when the user explicitly names which critics
roast(domain="codebase", target="/src", clis=["codex", "agy"])

Agent Strengths

Different agents have different strengths:

• Code review: Claude, Codex, Agy

• Architecture: Claude, Codex, Agy

• Security: Codex, Claude, Agy

• Research: Claude, Codex, Agy

When auto-selecting (no clis parameter), agy is always tried LAST since it's the slowest per call. Explicit clis=["agy"] honors the request regardless.

Antigravity (Agy) Auth Setup

Local dev (one-time):

agy "hi"   # browser OAuth flow seeds the macOS keychain (or Linux file)

CI / GitHub Actions: capture the token from your local macOS keychain and store as a GH secret named AGY_OAUTH_TOKEN:

security find-generic-password -s gemini -a antigravity -w \
  | sed 's/^go-keyring-base64://' | base64 -d \
  | gh secret set AGY_OAUTH_TOKEN

The Brutalist GitHub Action writes the secret to ~/.gemini/antigravity-cli/antigravity-oauth-token (mode 0600) before invoking the orchestrator; agy auto-detects the container environment and reads tokens from there. Agy issue #78 (env-var auth) is still open — until it closes, the file-provisioning path is the only way agy authenticates in CI.

If you have BOTH the Antigravity desktop IDE and the CLI agent installed on macOS, the IDE wrapper at ~/.antigravity/antigravity/bin/agy may shadow the CLI agent at ~/.local/bin/agy on PATH. Brutalist auto-prefers ~/.local/bin/agy when it exists, so no manual override is usually needed. If your install is in a non-standard location, set AGY_BIN=$HOME/.local/bin/agy (or wherever) to override.

Per-Call Model Pinning (Agy)

agy --print has no --model flag, but its settings.json accepts a human-readable label. Brutalist exploits this transparently: pass models.agy and brutalist writes the requested label under flock(2) for the duration of the call, then restores.

roast(
  domain="codebase",
  target="/src",
  clis=["agy"],
  models={"agy": "Gemini 3.1 Pro (High)"}
)

Supported labels (Pro / Claude / GPT-OSS tiers require Antigravity entitlement; Flash is always available):

• Gemini 3.5 Flash (High) / Gemini 3.5 Flash (Medium)

• Gemini 3.1 Pro (High) / Gemini 3.1 Pro (Low)

• Claude Sonnet 4.6 (Thinking)

• Claude Opus 4.6 (Thinking)

• GPT-OSS 120B (Medium)

Invalid labels silently downselect to Flash Medium (agy's behavior, not ours).

Verification-Heavy Domains

legal, research, and security ship with a mandatory verification protocol. Before citing any external authority (case, statute, study, CVE, advisory), agents must invoke their native web tools, lift a verbatim quote from the source, and tag the citation with one of:

• [VERIFIED: <url> | "<verbatim quote supporting the attribution>"]

• [SUPPLIED: <location> | "<verbatim quote from supplied materials>"]

• [UNVERIFIED: <reason>] — verification failed; no quote

Untagged citations are a protocol violation. The "state doctrine without a cite" fallback is conditional on a failed web lookup, not a parallel option. Consumers of the critique can spot-check citations by fetching the URL and grepping for the quoted string.

Codex Model Selection

Codex uses the Codex CLI's configured/default model by default. The server deliberately does not pass --model for Codex, even if models.codex is present, so stale tool-call tags cannot override a newer ~/.codex/config.toml value.

Set BRUTALIST_CODEX_ALLOW_MODEL_OVERRIDE=true only if you explicitly want Brutalist to pass models.codex through as codex exec --model .... When that opt-in is enabled, deprecated Codex model names are still resolved through the migration table discovered from the Codex CLI config.

Custom Claude Code Routes

Brutalist can run named Claude Code clients in parallel, including Anthropic-compatible endpoints such as GLM gateways. clients[] is additive — the named clients run alongside the native critics:

roast(
  domain="codebase",
  target="/src",
  clients=[
    {
      id: "glm",
      provider: "claude",
      baseUrl: "https://immersivecommons13.tail5da903.ts.net",
      authTokenEnv: "GLM_ANTHROPIC_AUTH_TOKEN",
      model: "glm-5.1"
    }
  ]
)

Set GLM_ANTHROPIC_AUTH_TOKEN in the environment before starting brutalist-mcp. The example above runs claude + codex + agy (native) and the routed glm critic. To run only the named clients, pass an explicit empty clis: [].

A client is routed as soon as it sets baseUrl (or authToken/authTokenEnv). Routed clients are hardened by default:

• Isolated credentials. A routed client never inherits the host's native ANTHROPIC_API_KEY/CLAUDE_CODE_OAUTH_TOKEN — only its own endpoint + token reach the gateway process. Set includeProcessAuth: true to opt back into inheriting native auth. (Conversely, the native critic never inherits an ambient ANTHROPIC_BASE_URL/ANTHROPIC_MODEL, so a GLM export in your shell can't silently reroute the trusted critic.)

• Isolated state. configDir maps to CLAUDE_CONFIG_DIR; if omitted, a per-client dir under ~/.brutalist/claude-clients/<id> is created (mode 0700).

• smallFastModel defaults to model so a gateway never receives Claude's built-in haiku model name.

• MCP containment (legacy label: "hardened"). Routed critics suppress caller-requested MCP servers by default. The backward-compatible "hardened" name is not a shell or network sandbox: Bash, WebFetch, and WebSearch remain available in both modes. Set containment: "standard" to restore requested MCP for a trusted endpoint.

Custom-endpoint fields (baseUrl, authToken, model, containment, …) are only valid for provider: "claude"; a codex/agy client carrying them is rejected. Up to 16 named clients may run in one roast (clients[] cap). roast_cli_debate does not support clients.

Many routes at once (GitHub Action)

The GitHub Action wires the same multi-client surface. Pass a JSON array via custom-claude-clients to route an arbitrary number of Claude critics (each through its own endpoint + secret) in one review:

- uses: ejmockler/brutalist-mcp/packages/github-action@v1
  with:
    anthropic-oauth-token: ${{ secrets.ANTHROPIC_OAUTH_TOKEN }}
    custom-claude-clients: |
      [
        { "id": "glm",   "baseUrl": "https://glm.example/v1",   "authToken": "${{ secrets.GLM_TOKEN }}",   "model": "glm-5.1",   "contextWindow": 128000 },
        { "id": "kimi",  "baseUrl": "https://kimi.example/v1",  "authToken": "${{ secrets.KIMI_TOKEN }}",  "model": "kimi-k2",   "contextWindow": 200000 }
      ]

Each entry's token is placed in a dedicated env var and referenced via authTokenEnv — raw tokens are never inlined into the forwarded BRUTALIST_CLAUDE_CLIENTS. Every client gets an isolated ~/.brutalist/claude-clients/<id> config dir (mode 0700), is isolated from native credentials, and suppresses caller-requested MCP by default exactly like the roast clients[] above. The legacy "hardened" label does not mean egress-sandboxed: Bash, WebFetch, and WebSearch remain available. Each critic reviews the whole diff chunked to its own context window (claude ~1M with [1m], codex 272k, agy ~135k, each routed client at its declared contextWindow), every stream additionally capped by the orchestrator brain's window (1M with [1m] on model, else ~200k, since the brain reads every chunk). A small client no longer forces finer chunks on the other critics — it only shrinks its own stream — so set each client's contextWindow to its model's usable window. When the whole diff already fits the smallest active window, all critics collapse into a single shared pass.

The singular custom-claude-* inputs remain supported for the one-client case and are backward-compatible — they work alongside custom-claude-clients (the singular trio, if set, appends one more client; deduped by id, keep-first on collision). Add "containment": "standard" to an entry to restore requested MCP for an endpoint you trust. The array cap matches the tool: 16 clients.

Why Multiple Perspectives

Each CLI agent brings a different approach to analysis:

• Different training data and focus areas

• Independent evaluation of the same code

• Varied perspectives on technical tradeoffs

Getting multiple viewpoints helps identify issues that a single perspective might miss.

License: MIT Issues: https://github.com/ejmockler/brutalist-mcp/issues