## Install
```bash
npx the-grid-cc
```
Then in Claude Code:
```
/grid
```
Works on Mac, Windows (WSL), and Linux.
---
## The Problem
You're building something in Claude Code. Sessions get long. Context fills up. Claude forgets what you're building. Quality degrades. Frustration builds.
**Sound familiar?**
---
## The Solution
The Grid spawns fresh subagents for heavy work while keeping your main conversation focused.
```
YOU ←→ Master Control ←→ Worker Agents
│
Your context stays clean (~15%)
Workers get fresh 200k windows
Master Control remembers your goals
```
**Without Grid:** One exhausted conversation doing everything.
**With Grid:** Focused orchestrator delegating to specialized workers.
---
## The CUDA Parallel
> **CUDA:** "Write your code. We figure out how to parallelize across 10,000 cores."
>
> **Grid:** "Describe your goal. We figure out how to orchestrate across agents."
Users shouldn't think about agents at all. They're an implementation detail—like GPU threads.
---
## Quick Start
```
> /grid
THE GRID
========
Master Control online.
What would you like to build?
> build a mass rename cli tool
[MC spawns Planner → analyzes → spawns Executor → builds]
✓ mass-rename-cli/ created
✓ 847 files renamed in test run
✓ Published to npm
Total tokens: 12,847 (across 3 agents)
Your context: stayed at 15%
```
---
## 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 |
---
## How It Works
```
┌─────────────────────────────────────────────────────────────┐
│ MASTER CONTROL │
│ 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 are subagents with fresh context. They do heavy lifting, report back, terminate. Your main conversation stays focused.
---
## Prompt Upscaling
Every request passes through the Upscaler:
```
You say: "build me a login page"
Grid builds:
✓ OWASP-compliant input validation
✓ Rate limiting (5 attempts/15 min)
✓ Argon2 password hashing
✓ CSRF protection
✓ Accessible (WCAG 2.1 AA)
```
Research best practices. Inject industry standards. Get expert-level specs from casual requests.
---
## Beyond Code Generation
Other tools stop at code. The Grid goes further:
| Agent | Purpose |
|:------|:--------|
| **Visual Inspector** | Screenshots your app, catches visual bugs |
| **E2E Exerciser** | Clicks everything like a real user |
| **Persona Simulator** | Reviews from your target users' POV |
Run `/grid:refine` after building. Catch issues before users do.
---
## 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 |
---
## Speak Grid
| Grid Term | Meaning |
|:----------|:--------|
| Program | Agent with a specific role |
| Identity Disc | System prompt defining behavior |
| Master Control | Orchestrator (only one who talks to you) |
| Spawning | Creating fresh agent instances |
| Derezzed | Agent completed and returned |
| Warmth | Context passed between agents |
| I/O Tower | Checkpoint requiring user input |
*The Tron metaphor maps perfectly to multi-agent AI architecture.*
---
## FAQ
How is this different from opening multiple Claude tabs?
Tabs share nothing. Grid agents share warmth—learnings, patterns, gotchas flow between them. Plus they run in parallel with fresh 200k context windows each.
Does this cost more tokens?
Yes, but you get more done. Parallel agents = parallel progress. Your main context stays lean while workers do heavy lifting. Complex builds often use fewer total tokens because there's no context bloat.
What if something goes wrong?
State saves to .grid/. Run /grid again to resume. Delete .grid/ to start fresh.
Does it work on Windows?
Yes, via WSL. Confirmed: macOS (Intel + Apple Silicon), Linux, Windows + WSL2.
What's the learning curve?
Install: 30 seconds. Start: /grid. Pick AUTOPILOT if unsure. Most users are productive in their first session.
---
## 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.
Add `.grid/` to your `.gitignore`—it's local working state, not project code.
---
## No Ceremony
No sprint planning. No story points. No stakeholder syncs. No Jira.
Just you, Claude, and code that ships.
---
## 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).
---
## Citation
```bibtex
@software{weatherhead2026grid,
author = {Weatherhead, James},
title = {{The Grid}: Multi-Agent Orchestration for Claude Code},
year = {2026},
publisher = {GitHub},
url = {https://github.com/JamesWeatherhead/grid},
note = {npm package: the-grid-cc}
}
```
---
## License
MIT License. See [LICENSE](LICENSE) for details.
---
