# grid-viz

Terminal visualization tool for The Grid state.

## What it does

Displays colorful, formatted terminal output showing:
- Current cluster status (name, status, energy)
- Phase and block progress with visual progress bars
- Recent scratchpad entries
- Active blockers and pending decisions
- Warmth/learnings count

## Installation

From the grid-viz directory:

```bash
npm install
chmod +x grid-viz.js
```

## Usage

Run from anywhere within a Grid-initialized project:

```bash
node /Users/jacweath/grid/tools/grid-viz/grid-viz.js
```

Or if installed globally:

```bash
npm install -g .
grid-viz
```

The tool automatically searches for the `.grid` directory in the current path or parent directories.

## Requirements

- Node.js (v12 or higher)
- chalk ^4.1.2 (installed via npm)

## Output Format

```
═══════════════════════════════════════════════════════════════════════
  THE GRID - State Visualization
═══════════════════════════════════════════════════════════════════════

Grid directory: /path/to/.grid

CLUSTER STATUS
  Name:     React Todo App
  Status:   COMPLETE
  Energy:   9000
  Progress: ████████████████████████████████████████ 100%
  Last:     2026-01-23 - Completed 01-PLAN.md

RECENT SCRATCHPAD ENTRIES
  [1] executor-01 (2026-01-23 19:00)
      Found: React hooks require functional components...

WARMTH
  Learnings: 12 patterns captured

═══════════════════════════════════════════════════════════════════════
  End of Line.
```

## Files Parsed

- `.grid/STATE.md` - Cluster status and progress
- `.grid/SCRATCHPAD.md` - Recent discoveries (last 5)
- `.grid/LEARNINGS.md` - Captured patterns count
- `.grid/BLOCKERS.md` - Active blockers (top 5)
- `.grid/DECISIONS.md` - Pending decisions (top 3)

## Error Handling

- Gracefully handles missing files
- Shows warning if .grid directory not found
- Displays available information even if some files are missing