# Grid Settings Integration

> How Grid configuration integrates with Claude Code's native settings hierarchy.

## Overview

The Grid integrates with Claude Code's settings system, allowing configuration at multiple levels with proper precedence. This enables teams to share Grid configuration via version control while allowing individual developers to override settings locally.

## Settings Hierarchy

Claude Code uses a layered settings system. The Grid respects this hierarchy:

| Priority | Level | Location | Shared? | Use Case |
|:---------|:------|:---------|:--------|:---------|
| 1 (highest) | **Environment** | `GRID_*` variables | No | CI/CD, temporary overrides |
| 2 | **Managed** | System-level `managed-settings.json` | Yes (IT) | Enterprise policy enforcement |
| 3 | **Local** | `.claude/settings.local.json` | No (gitignored) | Personal preferences |
| 4 | **Project** | `.claude/settings.json` | Yes (committed) | Team shared configuration |
| 5 | **User** | `~/.claude/settings.json` | No | Global user defaults |
| 6 (lowest) | **Legacy** | `.grid/config.json` | Yes | Backward compatibility |

### How Precedence Works

Settings are resolved from highest to lowest priority. The first source that provides a value wins.

```
GRID_MODEL_TIER=budget            # Wins if set
       ↓
managed-settings.json → grid.modelTier    # Enterprise override
       ↓
.claude/settings.local.json → grid.modelTier    # Local override
       ↓
.claude/settings.json → grid.modelTier    # Project team setting
       ↓
~/.claude/settings.json → grid.modelTier    # User global default
       ↓
.grid/config.json → modelTier    # Legacy fallback
       ↓
Built-in default ("quality")    # Ultimate fallback
```

## Configuration Locations

### Environment Variables (Priority 1)

Set environment variables for temporary overrides or CI/CD:

```bash
# Model selection
export GRID_MODEL_TIER=balanced    # quality | balanced | budget

# Budget control
export GRID_BUDGET_LIMIT=50.00     # Maximum spend in USD (0 = unlimited)

# Behavior flags
export GRID_AUTO_VERIFY=true       # Run Recognizer after execution
export GRID_AUTO_REFINE=false      # Run refinement swarm
export GRID_DAEMON_MODE=false      # Background execution mode

# Quick mode threshold
export GRID_QUICK_MODE_THRESHOLD=5  # Max files for quick mode detection
```

Claude Code also provides:
```bash
export CLAUDE_CODE_SUBAGENT_MODEL=sonnet  # Override all subagent models
```

### Managed Settings (Priority 2)

For enterprise deployments, IT can deploy managed settings:

**macOS:** `/Library/Application Support/ClaudeCode/managed-settings.json`
**Linux:** `/etc/claude-code/managed-settings.json`

```json
{
  "grid": {
    "modelTier": "balanced",
    "budgetLimit": 100.00,
    "autoVerify": true,
    "daemonMode": false
  }
}
```

Managed settings cannot be overridden by project or user settings.

### Local Settings (Priority 3)

Personal overrides that aren't committed to git:

**Location:** `.claude/settings.local.json`

```json
{
  "grid": {
    "modelTier": "quality",
    "budgetLimit": 0,
    "autoVerify": false
  }
}
```

This file should be in `.gitignore` (Claude Code adds it automatically).

### Project Settings (Priority 4)

Team-shared configuration committed to the repository:

**Location:** `.claude/settings.json`

```json
{
  "grid": {
    "modelTier": "balanced",
    "budgetLimit": 25.00,
    "autoVerify": true,
    "autoRefine": false,
    "quickModeThreshold": 3
  }
}
```

This enables teams to:
- Share consistent Grid configuration
- Enforce budget limits on shared projects
- Set project-appropriate model tiers

### User Settings (Priority 5)

Global defaults across all projects:

**Location:** `~/.claude/settings.json`

```json
{
  "grid": {
    "modelTier": "quality",
    "budgetLimit": 0,
    "autoVerify": true,
    "autoRefine": false,
    "daemonMode": false,
    "quickModeThreshold": 5
  }
}
```

### Legacy Configuration (Priority 6)

For backward compatibility, Grid still reads from:

**Location:** `.grid/config.json`

```json
{
  "modelTier": "balanced",
  "budgetLimit": 50.00,
  "autoVerify": true
}
```

Note: Legacy config uses flat structure (no `grid:` namespace).

## Grid Settings Schema

Grid configuration lives under the `grid` key in settings files:

```json
{
  "grid": {
    "modelTier": "quality",
    "budgetLimit": 0,
    "autoVerify": true,
    "autoRefine": false,
    "daemonMode": false,
    "quickModeThreshold": 5
  }
}
```

### Available Settings

| Setting | Type | Default | Description |
|:--------|:-----|:--------|:------------|
| `modelTier` | string | `"quality"` | Model selection tier: `quality`, `balanced`, `budget` |
| `budgetLimit` | number | `0` | Maximum spend in USD (0 = unlimited) |
| `autoVerify` | boolean | `true` | Run Recognizer after execution |
| `autoRefine` | boolean | `false` | Automatically run refinement swarm |
| `daemonMode` | boolean | `false` | Enable background execution mode |
| `quickModeThreshold` | integer | `5` | Max files for quick mode detection (1-10) |

### Model Tiers

| Tier | Planner | Executor | Recognizer | Scout | Description |
|:-----|:--------|:---------|:-----------|:------|:------------|
| `quality` | opus | opus | sonnet | haiku | Best results, higher cost |
| `balanced` | sonnet | sonnet | sonnet | haiku | Good balance of quality and cost |
| `budget` | sonnet | haiku | haiku | haiku | Cost-optimized, simpler tasks |

## Reading Settings in Shell Scripts

Grid provides `lib/settings.sh` to read settings with proper hierarchy:

```bash
#!/bin/bash
source ~/.claude/commands/grid/lib/settings.sh

# Read individual settings
tier=$(grid_read_setting "modelTier" "quality")
budget=$(grid_read_setting "budgetLimit" "0")
verify=$(grid_read_setting "autoVerify" "true")

# Use convenience functions
tier=$(grid_model_tier)
budget=$(grid_budget_limit)

# Check boolean settings
if grid_is_enabled "autoVerify"; then
    echo "Auto-verify is enabled"
fi
```

## Reading Settings in Agents

Agents can read settings via shell commands in their prompts:

```markdown
## Configuration

Read current settings:
\`\`\`bash
source ~/.claude/commands/grid/lib/settings.sh
grid_model_tier
grid_budget_limit
\`\`\`

Or directly with jq:
\`\`\`bash
jq -r '.grid.modelTier // "quality"' .claude/settings.json 2>/dev/null
\`\`\`
```

## Migration from Legacy Config

If you have an existing `.grid/config.json`, it will continue to work. To migrate to the new system:

1. Create `.claude/settings.json` if it doesn't exist
2. Add the `grid` section with your settings
3. Optionally delete `.grid/config.json`

```bash
# Quick migration script
if [ -f ".grid/config.json" ]; then
    # Read old config
    OLD_TIER=$(jq -r '.modelTier // "quality"' .grid/config.json)
    OLD_BUDGET=$(jq -r '.budgetLimit // 0' .grid/config.json)
    OLD_VERIFY=$(jq -r '.autoVerify // true' .grid/config.json)

    # Create new settings (if file doesn't exist)
    if [ ! -f ".claude/settings.json" ]; then
        mkdir -p .claude
        echo "{}" > .claude/settings.json
    fi

    # Add grid section
    jq --arg tier "$OLD_TIER" \
       --arg budget "$OLD_BUDGET" \
       --arg verify "$OLD_VERIFY" \
       '.grid = {
           modelTier: $tier,
           budgetLimit: ($budget | tonumber),
           autoVerify: ($verify == "true")
       }' .claude/settings.json > .claude/settings.json.tmp
    mv .claude/settings.json.tmp .claude/settings.json

    echo "Migrated settings to .claude/settings.json"
fi
```

## Best Practices

### Team Projects

1. Set reasonable defaults in `.claude/settings.json`
2. Commit this file to version control
3. Let developers override locally via `.claude/settings.local.json`

```json
// .claude/settings.json (committed)
{
  "grid": {
    "modelTier": "balanced",
    "budgetLimit": 25.00,
    "autoVerify": true
  }
}
```

### Personal Workflows

1. Set your preferences in `~/.claude/settings.json`
2. Use environment variables for session-specific overrides

```bash
# One-time budget override
GRID_BUDGET_LIMIT=100 claude

# Development mode (faster, cheaper)
GRID_MODEL_TIER=budget claude
```

### CI/CD Pipelines

1. Use environment variables exclusively
2. Set strict budget limits
3. Enable auto-verify

```yaml
# GitHub Actions example
env:
  GRID_MODEL_TIER: budget
  GRID_BUDGET_LIMIT: 5.00
  GRID_AUTO_VERIFY: true
```

## Troubleshooting

### Check Effective Configuration

```bash
source ~/.claude/commands/grid/lib/settings.sh
grid_show_config
```

### Debug Settings Resolution

```bash
# Check each source
echo "Env: ${GRID_MODEL_TIER:-<not set>}"
jq -r '.grid.modelTier // "<not set>"' .claude/settings.local.json 2>/dev/null || echo "Local: <no file>"
jq -r '.grid.modelTier // "<not set>"' .claude/settings.json 2>/dev/null || echo "Project: <no file>"
jq -r '.grid.modelTier // "<not set>"' ~/.claude/settings.json 2>/dev/null || echo "User: <no file>"
jq -r '.modelTier // "<not set>"' .grid/config.json 2>/dev/null || echo "Legacy: <no file>"
```

---

*End of Line.*