Content
# Brutalist MCP
Multi-perspective code analysis using Claude Code, Codex, and Gemini CLI agents.
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, Gemini), 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.
## Quick Start
### Step 1: Install a CLI Agent
You need at least one of these installed:
```bash
# Option 1: Claude Code (recommended)
npm install -g claude
# Option 2: Codex
# Install from https://github.com/openai/codex-cli
# Option 3: Gemini
npm install -g @google/gemini-cli
```
### Step 2: Install the MCP Server
Choose your IDE:
**Claude Code:**
```bash
claude mcp add brutalist --scope user -- npx -y @brutalist/mcp@latest
```
**Codex:**
```bash
# 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:**
The `tool_timeout_sec` parameter (defaulting to 60 seconds) for your Brutalist MCP server needs to be configured directly in your Codex configuration file at `~/.codex/config.toml`. It cannot be passed via the `codex mcp add` command directly.
To set a custom timeout (e.g., 5 minutes or 300 seconds), add or modify the `[mcp_servers.brutalist]` section in `~/.codex/config.toml` as follows:
```toml
[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 = 300 # Set your desired timeout in seconds
```
**Cursor:**
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"brutalist": {
"command": "npx",
"args": ["-y", "@brutalist/mcp@latest"]
}
}
}
```
**VS Code / Cline:**
```bash
code --add-mcp '{"name":"brutalist","command":"npx","args":["-y","@brutalist/mcp@latest"]}'
```
**Windsurf:**
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"brutalist": {
"command": "npx",
"args": ["-y", "@brutalist/mcp@latest"]
}
}
}
```
### Step 3: Verify Installation
```bash
# Check which CLI agents are available
cli_agent_roster()
```
## Usage Examples
### Analyze Your Codebase
```bash
# Analyze entire project
roast_codebase "/path/to/your/project"
# Analyze specific modules
roast_codebase "/src/auth"
roast_codebase "/src/api/handlers"
```
### Validate Ideas
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
- **Gemini CLI** - System design and scalability analysis
Each agent runs locally with direct file-system access, providing independent perspectives on your code and design decisions.
**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:
```bash
# Set chunk size for large codebases
roast_codebase({targetPath: "/monorepo", limit: 20000})
# Continue from where you left off
roast_codebase({targetPath: "/monorepo", offset: 20000, limit: 20000})
# Use cursor-based navigation
roast_codebase({targetPath: "/complex-system", 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)
## Tools
### Code & Architecture
| Tool | Analyzes |
|------|----------|
| `roast_codebase` | Security vulnerabilities, performance issues, code quality |
| `roast_file_structure` | Directory organization, naming conventions, structure |
| `roast_dependencies` | Version conflicts, security vulnerabilities, compatibility |
| `roast_git_history` | Commit quality, branching strategy, collaboration patterns |
| `roast_test_coverage` | Test coverage, quality gaps, testing strategy |
### Design & Planning
| Tool | Analyzes |
|------|----------|
| `roast_idea` | Feasibility, market fit, implementation challenges |
| `roast_architecture` | Scalability, cost, operational complexity |
| `roast_research` | Methodology, reproducibility, statistical validity |
| `roast_security` | Attack vectors, authentication, authorization |
| `roast_product` | UX, adoption barriers, user needs |
| `roast_infrastructure` | Reliability, scaling, operational overhead |
### Utilities
| Tool | Purpose |
|------|---------|
| `roast` | **Unified tool** - use `domain` parameter to select analysis type |
| `brutalist_discover` | Find the best tool for your intent using natural language |
| `roast_cli_debate` | Multi-agent discussion from different perspectives |
| `cli_agent_roster` | Show available CLI agents on your system |
> **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](docs/pagination.md) for detailed pagination documentation.
## Advanced Usage
### Choose Specific CLI Agents
```bash
# Use specific agents (subset selection)
roast(domain="codebase", target="/src", clis=["claude", "gemini"])
# Use a single agent
roast(domain="codebase", target="/src", clis=["claude"])
# Multi-agent analysis (default - all available)
roast(domain="idea", target="...") # All available agents provide perspectives
```
### Agent Strengths
Different agents have different strengths:
- **Code review**: Claude, Codex, Gemini
- **Architecture**: Gemini, Claude, Codex
- **Security**: Codex, Claude, Gemini
- **Research**: Claude, Gemini, Codex
## 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
