# Grid Environment Variables

Configure The Grid via environment variables. These override `.grid/config.json` settings.

## Available Variables

| Variable | Values | Default | Description |
|----------|--------|---------|-------------|
| `GRID_MODEL_TIER` | `quality`, `balanced`, `budget` | `quality` | Model selection tier |
| `GRID_BUDGET_LIMIT` | Number (dollars) | `0` (unlimited) | Maximum spend limit |
| `GRID_AUTO_VERIFY` | `true`, `false` | `true` | Auto-run Recognizer |
| `GRID_AUTO_REFINE` | `true`, `false` | `false` | Auto-run refinement swarm |
| `GRID_DAEMON_MODE` | `true`, `false` | `false` | Background execution |

## Claude Code Native Variables

The Grid also respects Claude Code's native environment variables:

| Variable | Description |
|----------|-------------|
| `CLAUDE_CODE_SUBAGENT_MODEL` | Override model for all subagents |
| `ANTHROPIC_MODEL` | Model alias or name to use |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Model for `opus` alias |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model for `sonnet` alias |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Model for `haiku` alias |

## Usage

### Temporary (single session)

```bash
# Set for a single Claude Code session
GRID_MODEL_TIER=budget claude

# Or export first
export GRID_MODEL_TIER=balanced
export GRID_BUDGET_LIMIT=10
claude
```

### Permanent (shell profile)

Add to `~/.bashrc`, `~/.zshrc`, or `~/.profile`:

```bash
# Grid Configuration
export GRID_MODEL_TIER=balanced
export GRID_BUDGET_LIMIT=10
export GRID_AUTO_VERIFY=true
export GRID_AUTO_REFINE=false
```

Then reload your shell:
```bash
source ~/.zshrc  # or ~/.bashrc
```

### CI/CD Pipeline

#### GitHub Actions

```yaml
name: Grid Build
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      GRID_MODEL_TIER: budget
      GRID_BUDGET_LIMIT: 5
      GRID_AUTO_VERIFY: true
    steps:
      - uses: actions/checkout@v4
      - name: Run Grid
        run: claude -p "Build the feature"
```

#### GitLab CI

```yaml
variables:
  GRID_MODEL_TIER: budget
  GRID_BUDGET_LIMIT: "5"
  GRID_AUTO_VERIFY: "true"

build:
  script:
    - claude -p "Build the feature"
```

#### CircleCI

```yaml
version: 2.1
jobs:
  build:
    docker:
      - image: cimg/base:stable
    environment:
      GRID_MODEL_TIER: budget
      GRID_BUDGET_LIMIT: 5
      GRID_AUTO_VERIFY: true
    steps:
      - checkout
      - run: claude -p "Build the feature"
```

### Docker

```dockerfile
FROM node:20
ENV GRID_MODEL_TIER=balanced
ENV GRID_BUDGET_LIMIT=10
ENV GRID_AUTO_VERIFY=true
# ... rest of Dockerfile
```

Or in docker-compose:

```yaml
services:
  claude:
    image: your-claude-image
    environment:
      - GRID_MODEL_TIER=balanced
      - GRID_BUDGET_LIMIT=10
      - GRID_AUTO_VERIFY=true
```

## Precedence

Configuration values are resolved in this order (highest priority first):

1. **Environment variables** (`GRID_*`)
2. **Claude Code subagent model** (`CLAUDE_CODE_SUBAGENT_MODEL`)
3. **Local project settings** (`.claude/settings.local.json`)
4. **Project settings** (`.claude/settings.json`)
5. **User settings** (`~/.claude/settings.json`)
6. **Legacy config** (`.grid/config.json`)
7. **Default value** (hardcoded in lib/env.sh)

### Example

```bash
# config.json has model_tier: "quality"
# Environment has GRID_MODEL_TIER=budget

# Result: budget tier is used (env overrides config)
```

## Model Tier Details

### Quality (Default)
All agents use **Opus** - best reasoning, highest quality output.

| Agent | Model |
|-------|-------|
| Planner | opus |
| Executor | opus |
| Recognizer | opus |
| Visual Inspector | opus |
| E2E Exerciser | opus |
| Persona Simulator | opus |

**Best for:** Complex projects, production code, when quality matters most.
**Cost:** ~3-5x more than Balanced.

### Balanced
Most agents use **Sonnet** - good reasoning, moderate cost.

| Agent | Model |
|-------|-------|
| Planner | sonnet |
| Executor | sonnet |
| Recognizer | sonnet |
| Visual Inspector | sonnet |
| E2E Exerciser | sonnet |
| Persona Simulator | sonnet |

**Best for:** Most projects, good quality/cost tradeoff.
**Cost:** Baseline.

### Budget
Use **Haiku** where possible, Sonnet for complex reasoning.

| Agent | Model |
|-------|-------|
| Planner | sonnet (needs reasoning) |
| Executor | sonnet (needs reasoning) |
| Recognizer | haiku |
| Visual Inspector | haiku |
| E2E Exerciser | haiku |
| Persona Simulator | sonnet (needs reasoning) |

**Best for:** Prototypes, learning, cost-sensitive projects.
**Cost:** ~50-70% less than Balanced.

## Troubleshooting

### Check Current Configuration

From within Claude Code:
```
/grid:model
```

Or from shell:
```bash
source ~/.claude/commands/grid/lib/env.sh
grid_show_config
```

### Environment Variable Not Taking Effect

1. Ensure the variable is exported:
   ```bash
   export GRID_MODEL_TIER=budget  # Correct
   GRID_MODEL_TIER=budget         # Won't work for child processes
   ```

2. Check for typos in variable name (case-sensitive)

3. Verify no conflicting settings in `.grid/config.json`:
   ```bash
   cat .grid/config.json
   ```

### Override Not Working in CI

Make sure variables are set at the job/step level, not just in scripts:

```yaml
# Correct - set at job level
env:
  GRID_MODEL_TIER: budget

# May not work - set in script
steps:
  - run: |
      export GRID_MODEL_TIER=budget
      claude  # May not see the variable
```

---

*End of Line.*