# THE GRID

<p align="center">
  <strong>From install to shipping features: 5 minutes.</strong>
  <br>
  Multi-agent orchestration for Claude Code that keeps your context clean
</p>

<p align="center">
  <a href="#your-first-session">First Session</a> •
  <a href="#three-modes">Three Modes</a> •
  <a href="#commands">Commands</a> •
  <a href="#faq">FAQ</a>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/the-grid-cc">
    <img src="https://img.shields.io/npm/v/the-grid-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837" alt="npm version"/>
  </a>
  <a href="https://github.com/JamesWeatherhead/grid/stargazers">
    <img src="https://img.shields.io/github/stars/JamesWeatherhead/grid?style=for-the-badge" alt="GitHub stars"/>
  </a>
  <a href="https://www.npmjs.com/package/the-grid-cc">
    <img src="https://img.shields.io/npm/dm/the-grid-cc?style=for-the-badge" alt="npm downloads"/>
  </a>
  <a href="https://github.com/JamesWeatherhead/grid/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/License-MIT-cyan.svg?style=for-the-badge" alt="MIT License"/>
  </a>
</p>

---

## The Problem

You're building something complex in Claude Code. Your context window fills up. Claude starts forgetting your original goals. You lose the forest for the trees.

**Sound familiar?**

## The Solution

The Grid spawns fresh subagents for heavy work while keeping your main conversation focused on goals.

```
YOU ←→ Coordinator ←→ Worker Agents
            ↓
     Your context stays clean (~15%)
     Workers get fresh 200k windows
     Coordinator remembers your goals
```

**Without Grid**: One exhausted conversation doing everything
**With Grid**: Focused coordinator delegating to specialized workers

---

## Quick Start

```bash
# Install (30 seconds, works on macOS/Linux/Windows+WSL)
npx the-grid-cc
```

Then in Claude Code:

```
/grid
```

That's it. Describe what you want to build.

---

## Your First Session

Here's exactly what happens when you use The Grid for the first time:

```
YOU: /grid

GRID: THE GRID
      ════════

      Master Control online.

      What would you like to build?

YOU: A REST API with user authentication

GRID: How involved do you want to be?

        AUTOPILOT  - I handle everything. Zero questions.
        GUIDED     - I drive, ask only when essential.
        HANDS ON   - We decide together.

YOU: autopilot

GRID: Building...
      ├─ Analyzing requirements
      ├─ Spawning Planner → creating execution plan
      ├─ Spawning Executors → implementing code (parallel)
      │   ├─ executor-1: Setting up Express + TypeScript
      │   ├─ executor-2: Creating auth routes + JWT
      │   └─ executor-3: Writing tests
      ├─ Spawning Recognizer → verifying quality
      └─ Running Refinement Swarm
          ├─ Visual: checked all routes
          ├─ E2E: tested login/logout flows
          └─ Personas: simulated "new user" experience

      BUILD COMPLETE
      ══════════════

      Project: auth-api
      Stack: Express + TypeScript + JWT + Prisma
      Files: 14 created
      Tests: 12 passing

      Ready to use. End of Line.
```

**Time from `/grid` to working code: ~10-15 minutes** (depending on complexity)

**Your context usage: ~15%** (workers did the heavy lifting)

---

## Three Modes

| Mode | You Do | Grid Does | Best For |
|------|--------|-----------|----------|
| **AUTOPILOT** | Describe goal | Everything else | "Just build it" |
| **GUIDED** | Answer rare questions | Drive + decide | Most projects |
| **HANDS ON** | Make key decisions | Present options | Learning / control |

### AUTOPILOT
Zero questions. You describe what you want, Grid figures out users, tech stack, architecture. You see finished code.

### GUIDED
Grid drives but asks when genuinely ambiguous: "This could be a blog or a docs site - which?" Then builds.

### HANDS ON
Collaborative. Grid proposes, you approve. More control, more questions.

---

## How It Works

```
┌─────────────────────────────────────────────────────────────┐
│  MASTER CONTROL (Coordinator)                               │
│  Your single interface. Stays lean. Remembers goals.        │
└─────────────────────────────────────────────────────────────┘
                              ↓
              Spawns specialized workers:
                              ↓
    ┌─────────────┬─────────────┬─────────────┬─────────────┐
    ↓             ↓             ↓             ↓             ↓
 PLANNER      EXECUTOR     RECOGNIZER    VISUAL       PERSONA
 Breaks down  Writes code  Verifies      Checks UI    Simulates
 the work     + commits    quality       visually     real users
```

**Workers = subagents with fresh context.** They do heavy lifting, report back, terminate. Your main conversation stays focused.

---

## Commands

| Command | What It Does |
|---------|-------------|
| `/grid` | Start The Grid |
| `/grid:refine` | Test your app (visual + E2E + personas) |
| `/grid:debug` | Systematic bug investigation |
| `/grid:status` | See current progress |
| `/grid:update` | Pull latest version |
| `/grid:help` | Full command reference |

---

## State Persistence

Grid saves state locally in `.grid/`:

```
.grid/
├── STATE.md           # Current progress
├── LEARNINGS.md       # Patterns from past projects
├── REFINEMENT_PLAN.md # Issues found during testing
└── phases/            # Execution plans
```

**Close your terminal. Come back tomorrow. Grid picks up where you left off.**

> **Tip:** Add `.grid/` to your `.gitignore` - it's local working state, not project code.

---

## FAQ

<details>
<summary><strong>How much does this cost in API tokens?</strong></summary>

Grid uses more API calls (multiple workers), but each call is *smaller* because contexts stay clean. In practice:

- **Simple feature**: ~same tokens as manual Claude session
- **Complex build**: Often *fewer* total tokens (no context bloat, no "remind me what we're building")
- **Refinement Swarm**: Adds ~20-30% more tokens for visual/E2E/persona testing

The Grid is free and open source. You pay normal Claude API costs.
</details>

<details>
<summary><strong>What if something goes wrong?</strong></summary>

**Worker fails mid-task:**
- State is saved in `.grid/`
- Run `/grid` again - it resumes from last checkpoint
- Or delete `.grid/` to start fresh

**Worker makes a mistake:**
- Recognizer catches most issues automatically
- If something slips through, describe the problem and Grid spawns a fix

**Grid gets confused:**
- `/grid:status` shows current state
- You can always override: "Stop. Let's do X instead."

**Nuclear option:**
- Delete `.grid/` folder
- Start fresh with `/grid`
</details>

<details>
<summary><strong>How is this different from just opening multiple Claude tabs?</strong></summary>

You *could* manually manage multiple conversations, copy context between them, track what each is doing, merge their outputs...

Grid does all that automatically:
- Knows what context each worker needs
- Tracks progress across workers
- Merges results coherently
- Maintains your original goals throughout

It's the difference between being a CEO who delegates vs. a CEO who runs between desks doing everything.
</details>

<details>
<summary><strong>Does it work on Windows?</strong></summary>

Yes, via WSL (Windows Subsystem for Linux). Native Windows support is untested but may work.

Confirmed working:
- macOS (Intel + Apple Silicon)
- Linux (Ubuntu, Debian, Arch)
- Windows + WSL2
</details>

<details>
<summary><strong>Can I use this with my existing Claude Code setup?</strong></summary>

Yes. Grid adds commands (`/grid`, `/grid:refine`, etc.) but doesn't modify your existing prompts or workflows. Use it when you want orchestration, use normal Claude when you don't.
</details>

<details>
<summary><strong>Why the TRON theme?</strong></summary>

The metaphor fits: Master Control orchestrates, Programs execute tasks, Recognizers verify quality. Plus it's fun. You can ignore it entirely - the tool works the same regardless of theme.
</details>

<details>
<summary><strong>What's the learning curve?</strong></summary>

Minimal:
1. Install: `npx the-grid-cc` (30 seconds)
2. Start: `/grid` (instant)
3. Describe what you want (you already know how)
4. Pick a mode (AUTOPILOT if unsure)

Most users are productive in their first session.
</details>

---

## Glossary (Optional)

Grid uses some themed terminology. Here's the plain-English translation:

| Grid Term | Plain English |
|-----------|---------------|
| Master Control | Coordinator agent (your main conversation) |
| Program | Worker agent (subagent doing a specific task) |
| Recognizer | Quality checker (verifies work meets goals) |
| Refinement Swarm | Testing suite (visual, E2E, persona simulation) |

You don't need to memorize these. Grid explains what it's doing as it works.

---

## Contributing

The Grid is a collaborative project by **James Weatherhead & Claude**.

Issues and PRs welcome at [github.com/JamesWeatherhead/grid](https://github.com/JamesWeatherhead/grid).

---

## License

MIT License. See [LICENSE](LICENSE) for details.

---

<p align="center">
  <strong>"I fight for the Users."</strong>
  <br><br>
  <sub>End of Line.</sub>
</p>