# Grid Status Line

Display real-time Grid mission status in your terminal.

## Overview

The Grid status line provides at-a-glance visibility into:
- Current mission/cluster name
- Phase and block progress
- Active agent count
- Session cost tracking
- Claude Code model and context usage

## Quick Setup

### Shell Prompt Integration

Add to your shell configuration to show Grid status in your prompt.

#### Bash (~/.bashrc or ~/.bash_profile)

```bash
# Source the Grid status line functions
source ~/.claude/commands/grid/lib/statusline.sh

# Add compact status to prompt
PS1='$(grid_status_compact) \w $ '

# Or with git branch
PS1='$(grid_status_compact) \w $(git branch --show-current 2>/dev/null | sed "s/^/ /") $ '
```

#### Zsh (~/.zshrc)

```zsh
# Source the Grid status line functions
source ~/.claude/commands/grid/lib/statusline.sh

# Add compact status to prompt
PROMPT='$(grid_status_compact) %~ %# '

# Or in RPROMPT for right-side display
RPROMPT='$(grid_status_compact)'
```

### Claude Code Status Line

Configure Claude Code to show Grid status at the bottom of the interface.

Add to `.claude/settings.json`:

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/commands/grid/lib/statusline.sh",
    "padding": 0
  }
}
```

Or run `/statusline` in Claude Code to configure interactively.

## Functions

| Function | Description | Output Example |
|----------|-------------|----------------|
| `grid_statusline` | Full status with all details | `GRID \| Build auth \| Phase: 02 \| Block: 03 \| Agents: 2 \| Cost: $1.47` |
| `grid_status_compact` | Minimal for shell prompts | `hexagon 02/03` |
| `grid_statusline_claude` | For Claude Code (reads stdin JSON) | `[Opus] $0.0234 \| 42% ctx \| GRID 02/03 \| main` |

## Output Examples

### Full Status Line

```
GRID | Build user authentication | Phase: 02 | Block: 03 | Agents: 2 | Cost: $1.47
```

### Compact (Shell Prompt)

```
hexagon 02/03 ~/project $
```

When idle (no `.grid/STATE.md`):
```
hexagon idle ~/project $
```

### Claude Code Mode

```
[Opus] $0.0234 | 42% ctx | GRID 02/03 | main
```

## Data Sources

The status line reads from these Grid state files:

| File | Data Extracted |
|------|----------------|
| `.grid/STATE.md` | Mission name, phase, block, status |
| `.grid/budget.json` | Total cost spent |

### STATE.md Format Expected

```markdown
## Current Position
Phase: 2 of 4 (Implementation)
Block: 3 of 8
Status: In progress
cluster: Build user authentication
```

### budget.json Format Expected

```json
{
  "total_spent": 1.47,
  "limit": 50.00
}
```

## Colors

The status line uses ANSI colors for visual clarity:

| Element | Color | ANSI Code |
|---------|-------|-----------|
| GRID label | Cyan | `\033[38;5;39m` |
| Mission name | Green | `\033[32m` |
| In progress | Yellow | `\033[33m` |
| Errors/blocked | Red | `\033[31m` |
| Separators | Dim | `\033[2m` |

## Customization

### Change the Icon

Edit `statusline.sh` and modify the `GRID_ICON` variable:

```bash
# Default hexagon
GRID_ICON='\342\254\241'

# Alternative: lightning bolt
GRID_ICON='\342\232\241'

# Alternative: gear
GRID_ICON='\342\232\231'
```

### Custom Status Line

Create your own by combining functions:

```bash
my_status() {
    local grid=$(grid_status_compact)
    local time=$(date +%H:%M)
    echo "$grid | $time"
}
```

## Troubleshooting

### Status shows "idle" when mission is active

Ensure you're in the correct directory. The status line looks for `.grid/STATE.md` in the current working directory.

```bash
# Check if STATE.md exists
ls -la .grid/STATE.md
```

### Colors not displaying

Your terminal may not support ANSI colors. Try:

```bash
# Test color support
echo -e "\033[32mGreen\033[0m"
```

### jq not found

The Claude Code mode requires `jq` for JSON parsing:

```bash
# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq
```

## Integration with Grid Commands

The status line automatically updates when:
- `/grid:init` creates a new mission
- `/grid:mc` starts Master Control
- Programs complete blocks
- `/grid:status` updates state

No manual refresh needed - just re-evaluate your prompt.

---

*End of Line.*