# ⚡ Agent Booster: Ultra-Fast Code Transformations

**352x faster than LLM APIs • $0 cost • 100% deterministic**

---

## 📑 Quick Navigation

[← Back to Main README](https://github.com/ruvnet/agentic-flow/blob/main/README.md) | [ReasoningBank →](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/REASONINGBANK.md) | [Multi-Model Router →](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/MULTI-MODEL-ROUTER.md)

---

## 🎯 What is Agent Booster?

Agent Booster is a local code transformation engine built with Rust and WebAssembly that performs mechanical code edits without calling expensive LLM APIs. It's designed for operations where you know exactly what changes to make—no AI reasoning required.

### The Problem

Traditional AI coding agents call LLM APIs for **every single code edit**, even simple mechanical transformations like:
- Renaming variables across files
- Adding import statements
- Updating function signatures
- Reformatting code blocks
- Find-and-replace operations

**Cost**: $0.01 per edit
**Latency**: 352ms per edit (API roundtrip)
**For 1000 edits**: $10 + 5.87 minutes

### The Solution

Agent Booster performs these operations locally using Rust/WASM:

**Cost**: $0.00 per edit
**Latency**: 1ms per edit (local execution)
**For 1000 edits**: $0.00 + 1 second

**Savings: 352x faster, 100% free, zero API dependency**

---

## 🚀 How It Works

Agent Booster operates in three modes:

### 1. **Single File Edit** (Simple)
Apply precise edits to one file using marker syntax:

```bash
npx agentic-flow agent-booster edit \
  --file src/api.ts \
  --instructions "Add error handling to fetchUser" \
  --code '
export async function fetchUser(id: string) {
  // ... existing code ...

  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error("User not found");
    return await response.json();
  } catch (error) {
    console.error("Failed to fetch user:", error);
    throw error;
  }
}
  '
```

### 2. **Batch Edit** (Efficient)
Apply multiple edits in a single operation:

```bash
npx agentic-flow agent-booster batch \
  --config batch-edits.json
```

**batch-edits.json:**
```json
{
  "edits": [
    {
      "file": "src/user.ts",
      "instructions": "Add type annotation",
      "code": "const user: User = { ... }"
    },
    {
      "file": "src/api.ts",
      "instructions": "Add error handling",
      "code": "try { ... } catch { ... }"
    }
  ]
}
```

### 3. **Markdown Parse** (LLM-Compatible)
Parse LLM-generated markdown with filepath and instruction metadata:

```markdown
filepath=src/user.ts instruction="Add type annotation"
\`\`\`typescript
const user: User = {
  id: string;
  name: string;
};
\`\`\`

filepath=src/api.ts instruction="Add error handling"
\`\`\`typescript
try {
  // API call
} catch (error) {
  console.error(error);
}
\`\`\`
```

---

## 📊 Performance Benchmarks

### Single Edit Latency

| Operation | LLM API | Agent Booster | Speedup |
|-----------|---------|---------------|---------|
| **Variable rename** | 352ms | 1ms | 352x |
| **Add import** | 420ms | 1ms | 420x |
| **Function signature** | 380ms | 1ms | 380x |
| **Code formatting** | 290ms | 1ms | 290x |

### Batch Operations

| Files | LLM API | Agent Booster | Speedup |
|-------|---------|---------------|---------|
| **10 files** | 3.52s | 10ms | 352x |
| **100 files** | 35.2s | 100ms | 352x |
| **1000 files** | 5.87 min | 1s | 352x |

### Cost Comparison

| Operation | LLM API | Agent Booster | Savings |
|-----------|---------|---------------|---------|
| **Single edit** | $0.01 | $0.00 | 100% |
| **100 edits/day** | $1.00/day | $0.00/day | $365/year |
| **1000 files** | $10.00 | $0.00 | $10.00 |

---

## 🎯 Use Cases

### ✅ Perfect For (Use Agent Booster)

**Variable Renaming Across Files**
```bash
# Before: getUserData → fetchUserProfile
# 50 files, 200 occurrences
# LLM: 70 seconds, $2.00
# Agent Booster: 0.2 seconds, $0.00
```

**Adding Import Statements**
```bash
# Add "import { z } from 'zod'" to 100 TypeScript files
# LLM: 35 seconds, $1.00
# Agent Booster: 0.1 seconds, $0.00
```

**Code Formatting**
```bash
# Reformat 1000 files to match style guide
# LLM: 5.87 minutes, $10.00
# Agent Booster: 1 second, $0.00
```

**Function Signature Updates**
```bash
# Update function(a, b) → function(a: string, b: number)
# 30 functions across 10 files
# LLM: 10.5 seconds, $0.30
# Agent Booster: 0.03 seconds, $0.00
```

### ❌ Not Suitable For (Use LLM)

**Complex Refactoring** - Requires reasoning about code structure
**Bug Fixes** - Needs understanding of root cause
**Feature Implementation** - Requires creative problem-solving
**Architecture Changes** - Needs high-level decision making

---

## 🔧 Installation & Setup

### Prerequisites

- Node.js ≥18.0.0
- Rust toolchain (for building from source)
- WASM support

### Quick Start

```bash
# Install agentic-flow (includes Agent Booster)
npm install -g agentic-flow

# Verify installation
npx agentic-flow agent-booster --version

# Test with sample edit
npx agentic-flow agent-booster edit \
  --file test.ts \
  --instructions "Add console.log" \
  --code 'console.log("Hello, Agent Booster!");'
```

### MCP Tool Integration

Agent Booster is available as an MCP tool within agentic-flow:

```javascript
// Use via MCP
await query({
  mcp: {
    server: 'agentic-flow',
    tool: 'agent_booster_edit_file',
    params: {
      target_filepath: 'src/api.ts',
      instructions: 'Add error handling',
      code_edit: '// ... code with markers ...'
    }
  }
});
```

---

## 📖 Advanced Usage

### Pattern Matching with Markers

Use `// ... existing code ...` markers to preserve unchanged sections:

```typescript
// Original file: src/api.ts
export function fetchUser(id: string) {
  return fetch(`/api/users/${id}`);
}

// Edit with markers:
export async function fetchUser(id: string) {
  // ... existing code ...

  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error("User not found");
    return await response.json();
  } catch (error) {
    console.error(error);
    throw error;
  }
}
```

### Multi-File Refactoring

**Scenario**: Rename `getUserData` to `fetchUserProfile` across 50 files

```bash
npx agentic-flow agent-booster batch-rename \
  --pattern "getUserData" \
  --replacement "fetchUserProfile" \
  --glob "src/**/*.ts"
```

**Results**:
- Files processed: 50
- Occurrences replaced: 187
- Time: 150ms
- Cost: $0.00

### Integration with LLM Agents

Combine Agent Booster with LLM agents for optimal performance:

```javascript
// 1. LLM designs the edits (reasoning)
const edits = await query({
  prompt: "Design refactoring for error handling",
  agent: "system-architect"
});

// 2. Agent Booster applies the edits (fast execution)
await query({
  mcp: {
    server: 'agentic-flow',
    tool: 'agent_booster_batch_edit',
    params: { edits: edits.plan }
  }
});
```

**Result**: Reasoning time + 1ms execution vs. LLM for every edit

---

## 🛠️ Configuration

### Agent Booster Config (`agent-booster.yaml`)

```yaml
agent_booster:
  # Performance tuning
  max_concurrent_edits: 10
  batch_size: 100

  # Safety settings
  backup_files: true
  dry_run: false

  # Validation
  validate_syntax: true
  run_formatter: true

  # Logging
  log_level: "info"
  verbose: false
```

### CLI Options

```bash
npx agentic-flow agent-booster [command] [options]

Commands:
  edit          Single file edit
  batch         Batch edit multiple files
  parse-md      Parse markdown with code blocks
  rename        Rename variables/functions
  format        Format code files

Options:
  --file        Target file path
  --instructions First-person instruction
  --code        Code edit with markers
  --config      Config file path
  --dry-run     Preview changes without applying
  --backup      Create backup before editing
  --verbose     Enable verbose logging
```

---

## 📈 ROI Calculator

### Scenario 1: Code Review Agent (100 reviews/day)

**Without Agent Booster** (LLM for all edits):
- 100 reviews × 10 edits each = 1000 edits/day
- Time: 1000 × 352ms = 5.87 minutes/day
- Cost: 1000 × $0.01 = $10/day = $300/month

**With Agent Booster**:
- Time: 1000 × 1ms = 1 second/day
- Cost: $0/day = $0/month

**Savings: $300/month + 5.86 minutes/day**

### Scenario 2: Codebase Migration (1000 files)

**Without Agent Booster**:
- 1000 files × 352ms = 5.87 minutes
- Cost: 1000 × $0.01 = $10

**With Agent Booster**:
- 1000 files × 1ms = 1 second
- Cost: $0

**Savings: 5.85 minutes + $10 per migration**

### Scenario 3: Refactoring Pipeline (weekly)

**Without Agent Booster**:
- 50 files/week × 20 edits = 1000 edits/week
- Time: 5.87 minutes/week × 52 = 5.1 hours/year
- Cost: $10/week × 52 = $520/year

**With Agent Booster**:
- Time: 52 seconds/year
- Cost: $0/year

**Savings: 5.1 hours/year + $520/year**

---

## 🔗 Related Documentation

### Core Components
- [← Back to Main README](https://github.com/ruvnet/agentic-flow/blob/main/README.md)
- [ReasoningBank (Learning Memory) →](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/REASONINGBANK.md)
- [Multi-Model Router (Cost Optimization) →](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/MULTI-MODEL-ROUTER.md)

### Advanced Topics
- [MCP Tools Reference](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/MCP-TOOLS.md)
- [Deployment Options](https://github.com/ruvnet/agentic-flow/blob/main/docs/guides/DEPLOYMENT.md)
- [Performance Benchmarks](https://github.com/ruvnet/agentic-flow/blob/main/docs/agentic-flow/benchmarks/README.md)

### Integrations
- [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk)
- [Claude Flow (101 MCP tools)](https://github.com/ruvnet/claude-flow)
- [Flow Nexus (96 cloud tools)](https://github.com/ruvnet/flow-nexus)

---

## 🤝 Contributing

Agent Booster is part of the agentic-flow project. Contributions welcome!

**Areas for Contribution:**
- Additional language support (Python, Java, Go)
- Performance optimizations
- New transformation patterns
- Documentation improvements

See [CONTRIBUTING.md](https://github.com/ruvnet/agentic-flow/blob/main/CONTRIBUTING.md) for guidelines.

---

## 📄 License

MIT License - see [LICENSE](https://github.com/ruvnet/agentic-flow/blob/main/LICENSE) for details.

---

**Deploy ultra-fast code transformations. Zero API costs. 352x faster.** ⚡

[← Back to Main README](https://github.com/ruvnet/agentic-flow/blob/main/README.md)