# Headless Mode & Agent SDK Analysis for The Grid

**Analyst**: Grid Enhancement Analyst
**Source**: `/Users/jacweath/grid/docs/claude-code-reference/07-headless-sdk.md`
**Date**: 2026-01-23
**Grid Version**: 1.7.x

---

## Executive Summary

The Claude Code Agent SDK (formerly "headless mode") represents a **transformational opportunity** for The Grid. Currently, Grid operates exclusively through interactive Claude Code sessions. The Agent SDK enables programmatic invocation of Claude Code via CLI, Python, or TypeScript, opening pathways for:

1. **CI/CD Integration** - Grid-powered automated code review, testing, and deployment
2. **Background Daemon Evolution** - Native daemon mode using `claude -p` instead of nohup workarounds
3. **External Orchestration** - Grid as a callable service from external systems
4. **Batch Operations** - Processing multiple tasks without interactive sessions
5. **API-First Grid** - Exposing Grid capabilities programmatically

**Opportunity Level**: HIGH
**Implementation Complexity**: MEDIUM
**Impact on Grid Architecture**: SIGNIFICANT

---

## Detailed Opportunities

### 1. CI/CD Pipeline Integration

**Current State**: Grid is interactive-only. Cannot be invoked from GitHub Actions, GitLab CI, or Jenkins.

**SDK Capability**:
```bash
claude -p "Review the changes in this PR and suggest improvements" \
  --allowedTools "Read,Grep,Glob" \
  --output-format json > review.json
```

**Grid Opportunity**: Create `grid-ci` - a headless Grid variant for CI/CD pipelines.

```yaml
# GitHub Actions example
- name: Grid Code Review
  run: |
    claude -p "You are a Grid Recognizer. Review this PR for:
      1. Code quality
      2. Test coverage
      3. Architecture alignment
      Return structured JSON with findings." \
      --allowedTools "Read,Grep,Glob" \
      --output-format json \
      --json-schema '{"type":"object","properties":{"issues":{"type":"array"},"approved":{"type":"boolean"}}}'
```

**Specific Applications**:
- PR quality gates (Grid Recognizer as CI step)
- Automated code documentation generation
- Security scanning with Grid's systematic approach
- Pre-merge refinement swarm (visual/E2E checks)

**Implementation Path**:
1. Create `grid-ci.sh` wrapper script
2. Define JSON schemas for each CI operation
3. Package as GitHub Action / GitLab template
4. Document integration patterns

---

### 2. Native Daemon Mode Enhancement

**Current State**: Grid's daemon mode (`/grid:daemon`) uses workarounds:
```bash
# Current approach (from daemon.md)
nohup claude --print -p "..." > .grid/daemon/{id}/output.log 2>&1 &
echo $! > .grid/daemon/{id}/pid
```

**SDK Capability**: The `-p` flag with `--continue` enables session persistence:
```bash
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"
```

**Grid Opportunity**: Replace nohup-based daemon with native SDK invocation.

**Improved Daemon Architecture**:
```bash
#!/bin/bash
# grid-daemon-native.sh

DAEMON_ID="$1"
TASK="$2"
DAEMON_DIR=".grid/daemon/$DAEMON_ID"

# Start daemon with session tracking
SESSION=$(claude -p "You are a Grid Daemon Orchestrator. Execute: $TASK" \
  --allowedTools "Read,Write,Edit,Bash,Glob,Grep,Task" \
  --output-format json \
  --append-system-prompt "$(cat ~/.claude/agents/grid-daemon-orchestrator.md)" \
  | jq -r '.session_id')

echo "$SESSION" > "$DAEMON_DIR/session_id"

# Daemon can be resumed with:
# claude -p "Continue execution" --resume "$SESSION"
```

**Benefits**:
- Native session management (no PID tracking)
- Built-in continuation support
- Cleaner checkpoint/resume flow
- Better error handling

---

### 3. Python/TypeScript SDK Integration

**Current State**: Grid is invoked only via `/grid` skill in Claude Code.

**SDK Capability**:
```python
from claude_code_sdk import Agent

agent = Agent()
result = agent.run("Explain what this code does", files=["main.py"])
print(result.text)
```

**Grid Opportunity**: Create `grid-sdk` package for programmatic Grid access.

**Concept: grid-sdk (Python)**:
```python
from grid_sdk import Grid, Mode

# Initialize Grid instance
grid = Grid(
    working_dir="/path/to/project",
    mode=Mode.AUTOPILOT,
    model_tier="quality"  # quality, balanced, budget
)

# Build something
result = grid.build("REST API with authentication")
print(f"Files created: {result.files_created}")
print(f"Status: {result.status}")

# Run refinement swarm
refinement = grid.refine()
print(f"Issues found: {len(refinement.issues)}")

# Debug a problem
debug_result = grid.debug("Login fails on mobile")
print(f"Root cause: {debug_result.root_cause}")
```

**Concept: @the-grid/sdk (TypeScript)**:
```typescript
import { Grid, Mode } from '@the-grid/sdk';

const grid = new Grid({
  workingDir: '/path/to/project',
  mode: Mode.AUTOPILOT
});

const result = await grid.build('REST API with authentication');
console.log(`Files created: ${result.filesCreated}`);
```

**Implementation Path**:
1. Wrap `claude -p` calls with Grid-specific prompts
2. Inject Grid agent instructions via `--append-system-prompt`
3. Parse JSON outputs into structured results
4. Expose Grid commands as SDK methods

---

### 4. Batch Processing Operations

**Current State**: Grid processes one task per interactive session.

**SDK Capability**:
```bash
for file in src/*.py; do
  claude -p "Review $file for security issues" \
    --allowedTools "Read" \
    --output-format json >> reviews.jsonl
done
```

**Grid Opportunity**: Enable batch Grid operations.

**Applications**:
- Review all files in a directory systematically
- Generate documentation for multiple modules
- Run refinement across multiple projects
- Bulk codebase migrations

**Example: grid-batch**:
```bash
#!/bin/bash
# grid-batch.sh - Batch Grid operations

OPERATION=$1
shift
FILES=$@

case $OPERATION in
  review)
    for file in $FILES; do
      claude -p "You are a Grid Recognizer. Review $file for quality issues." \
        --allowedTools "Read" \
        --output-format json \
        --append-system-prompt "$(cat ~/.claude/agents/grid-recognizer.md)" \
        >> .grid/batch/reviews.jsonl
    done
    ;;
  document)
    for file in $FILES; do
      claude -p "Generate comprehensive documentation for $file" \
        --allowedTools "Read,Write" \
        --output-format text \
        > "${file%.py}_docs.md"
    done
    ;;
esac
```

---

### 5. Structured Output Integration

**Current State**: Grid relies on markdown-based state files (STATE.md, PLAN.md).

**SDK Capability**:
```bash
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}}}'
```

**Grid Opportunity**: Use JSON schemas for structured Grid outputs.

**Structured Plan Schema**:
```json
{
  "type": "object",
  "properties": {
    "mission": {"type": "string"},
    "blocks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "description": {"type": "string"},
          "wave": {"type": "integer"},
          "files": {"type": "array", "items": {"type": "string"}},
          "dependencies": {"type": "array", "items": {"type": "string"}}
        }
      }
    },
    "checkpoints": {"type": "array"},
    "estimated_duration": {"type": "string"}
  }
}
```

**Benefits**:
- Reliable parsing (no markdown parsing errors)
- Validation against schema
- Better inter-agent communication
- Cleaner API responses

---

### 6. Custom System Prompt Injection

**Current State**: Grid agents read their instructions from markdown files.

**SDK Capability**:
```bash
claude -p "Your task here" \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities."
```

**Grid Opportunity**: Inject Grid agent personas via system prompts.

**Headless Grid Invocation**:
```bash
# Spawn a Grid Executor headlessly
claude -p "Execute this plan: $PLAN_CONTENT" \
  --allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
  --append-system-prompt "$(cat ~/.claude/agents/grid-executor.md)" \
  --output-format json
```

This enables:
- External systems invoking specific Grid agents
- Mixing Grid agents with custom prompts
- Dynamic agent configuration

---

### 7. Piping and Stream Processing

**Current State**: Grid uses file-based communication (scratchpad, state files).

**SDK Capability**:
```bash
cat error.log | claude -p "Analyze this error log and suggest fixes"
```

**Grid Opportunity**: Stream-based Grid operations.

**Examples**:
```bash
# Pipe test failures to Grid Debugger
npm test 2>&1 | claude -p "You are a Grid Debugger. Analyze these test failures." \
  --append-system-prompt "$(cat ~/.claude/agents/grid-debugger.md)"

# Pipe PR diff for review
gh pr diff 123 | claude -p "You are a Grid Recognizer. Review this diff." \
  --output-format json

# Stream logs to Grid for analysis
tail -f /var/log/app.log | claude -p "Monitor for errors and alert on issues" \
  --output-format stream-json
```

---

## Quick Wins (Implementable in 1.7.x)

### Win 1: `grid-review` CLI Command
**Effort**: 2-4 hours
**Impact**: HIGH

Create a simple wrapper for headless PR review:

```bash
#!/bin/bash
# ~/.claude/commands/grid-review.sh

PR_NUMBER=$1
gh pr diff "$PR_NUMBER" | claude -p "You are a Grid Recognizer. Review this PR for:
1. Code quality issues
2. Potential bugs
3. Security concerns
4. Test coverage gaps

Provide actionable feedback." \
  --allowedTools "Read,Grep,Glob" \
  --output-format json \
  --append-system-prompt "$(cat ~/.claude/agents/grid-recognizer.md)"
```

### Win 2: Daemon Session Persistence
**Effort**: 4-6 hours
**Impact**: HIGH

Update `/grid:daemon` to use `--resume` for session continuation:

```python
# In daemon checkpoint handling
if checkpoint_exists:
    session_id = read_session_id()
    claude -p "Resume daemon execution" --resume "$session_id"
else:
    result = claude -p "..." --output-format json
    save_session_id(result.session_id)
```

### Win 3: Structured JSON Plans
**Effort**: 6-8 hours
**Impact**: MEDIUM

Update Planner to output JSON via `--json-schema`:

```bash
claude -p "Create an execution plan for: $TASK" \
  --output-format json \
  --json-schema "$(cat ~/.claude/schemas/grid-plan.json)" \
  --append-system-prompt "$(cat ~/.claude/agents/grid-planner.md)"
```

### Win 4: GitHub Action for Grid
**Effort**: 8-12 hours
**Impact**: HIGH

Create `@the-grid/action` for GitHub marketplace:

```yaml
# action.yml
name: 'Grid Code Review'
description: 'Run Grid Recognizer on PR changes'
inputs:
  mode:
    description: 'Review mode (quick, thorough, security)'
    default: 'quick'
runs:
  using: 'composite'
  steps:
    - run: |
        claude -p "Review PR changes..." \
          --allowedTools "Read,Grep,Glob" \
          --output-format json
```

---

## Architecture Changes Required

### 1. Agent Prompt Externalization

**Current**: Agents read from `~/.claude/agents/*.md`
**Required**: Agent prompts must be injectable via `--append-system-prompt`

**Change**: Create condensed, single-file versions of each agent prompt suitable for injection.

### 2. State Communication Protocol

**Current**: File-based (STATE.md, SCRATCHPAD.md)
**Required**: Support both file-based AND JSON-based state

**Change**: Add serialization layer that can output to files OR JSON.

### 3. Task() Wrapper for Headless

**Current**: `Task()` tool spawns subagents interactively
**Required**: Equivalent for headless mode

**Change**: Create `grid_spawn()` function that wraps `claude -p` with Grid context.

### 4. Configuration for Headless Mode

**Current**: `.grid/config.json` for interactive settings
**Required**: Environment variable and CLI arg support

**Change**: Add ENV vars for headless: `GRID_MODE`, `GRID_MODEL_TIER`, `GRID_WORKING_DIR`

---

## Specific Recommendations

### Immediate (1.7.2 - 1.7.5)

1. **Add `grid-review` command** - Quick PR review via headless mode
2. **Document headless invocation patterns** - How to use Grid agents headlessly
3. **Create JSON schemas** - For plans, state, and results
4. **Update daemon to use --resume** - Native session persistence

### Short-term (1.7.6 - 1.7.15)

5. **Build grid-ci package** - CI/CD integration toolkit
6. **Create GitHub Action** - Marketplace-ready Grid action
7. **Implement batch operations** - `grid-batch` command
8. **Add streaming support** - For log analysis and monitoring

### Medium-term (1.7.16 - 1.7.30)

9. **Python SDK alpha** - Programmatic Grid access
10. **TypeScript SDK alpha** - For Node.js environments
11. **Webhook integration** - Grid results to external systems
12. **Scheduled Grid operations** - Cron-triggered builds/reviews

### Long-term (1.7.30+)

13. **Grid as a service** - HTTP API wrapper around Grid
14. **Multi-project orchestration** - Grid managing multiple repos
15. **Enterprise integration** - SSO, audit logs, compliance hooks

---

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| API rate limits in batch operations | HIGH | MEDIUM | Implement backoff, chunk batches |
| Context loss in headless (no warmth) | MEDIUM | HIGH | Explicit warmth injection via prompts |
| JSON schema validation failures | MEDIUM | LOW | Graceful fallback to text parsing |
| Session ID management complexity | MEDIUM | MEDIUM | Clear session lifecycle docs |
| Cost explosion in CI pipelines | HIGH | HIGH | Budget limits, dry-run mode |

---

## Conclusion

The Agent SDK fundamentally changes what Grid can be. Today, Grid is a powerful interactive assistant. With SDK integration, Grid becomes:

- **A CI/CD platform component** - Automated quality gates
- **A programmable API** - Callable from any system
- **A batch processor** - Handling repetitive tasks at scale
- **A monitoring tool** - Analyzing logs and metrics in real-time

The key insight: **Grid's agent architecture is already designed for delegation**. The SDK simply provides a new invocation mechanism. The same agents (Planner, Executor, Recognizer) that work interactively can work headlessly with minimal changes.

**Recommended Priority**: Start with Quick Wins 1 and 2 (grid-review and daemon sessions) to prove the pattern, then expand systematically.

---

**End of Line.**