Long-Running State Patterns

Long-Running State Patterns

Patterns for managing Claude agents across extended multi-context-window workflows. This is optional reference content for when you need to design long-running agent systems.

Core Challenge

Long-running agents work in discrete sessions. Each new session starts without memory of previous sessions. Complex projects span multiple context windows. The solution: bridge gaps through structured artifacts and explicit state management.

Context Management

Automatic Tools

Auto-Compact: Triggers at ~95% context capacity. Claude Code summarizes history, preserving architectural decisions and unresolved bugs. Manually trigger with /compact at logical breakpoints.

Token Budget Awareness: Claude 4.5+ receives updates on remaining context after tool calls. Enables better task persistence and strategy adjustment.

Compression Strategies (Karpathy Framework)

Hierarchical Summarization: Subagents return condensed summaries (1,000-2,000 tokens) rather than full exploration context.

Just-In-Time Loading: Maintain lightweight identifiers (file paths, queries). Load data at runtime using tools.

State Persistence

Git-Based State Tracking

Anthropic recommends combining git history with structured progress files:

Two-Agent Pattern:

1. Initializer Agent (first session): Sets up environment, creates init.sh and claude-progress.txt, makes initial commit
2. Coding Agent (subsequent): Reads git history + progress files, works incrementally, commits with descriptive messages

Why This Works: Fresh agents understand state quickly from git + progress file. Commits enable recovery. Progress tracking prevents premature completion.

Structured Progress Files

# Project Progress Log

## Current Status
- Session: [timestamp]
- Focus: [current task]
- Blockers: [if any]

## Completed Features
- Feature A: ✓ (commit abc123)

## In Progress
- Feature B: [current work description]

## Pending
- Feature C: [description]

## Testing Status
- Unit: ✓
- Integration: [status]
- E2E: [status]

JSON Feature Lists

{
  "features": [
    {
      "id": "auth-login",
      "status": "complete",
      "tested": true,
      "commit": "abc123"
    }
  ]
}

Explicit feature lists prevent premature completion and duplicate work.

Failure Mode Prevention

Multi-Context-Window Workflows

Session Initialization Ritual

1. pwd - establish location
2. git log --oneline -20 - review recent work
3. Read progress file and CLAUDE.md
4. source init.sh - start services
5. Run tests to verify baseline
6. Choose single feature from pending list

Context Boundary Crossing

Manual Compact (Recommended): At logical breakpoints, /compact then /clear. Start fresh on next feature.

Memory Tool Preservation: Before context limits, save state to memory files. Update CLAUDE.md and progress file.

Subagent Orchestration

Orchestrator-Worker Pattern

Orchestrator (Opus 4.5)
├── Holds plan, routes tasks
├── No implementation work
└── Context reserved for coordination

Subagents (Sonnet/Haiku 4.5)
├── Focused expertise
├── Own context window
├── Returns condensed results
└── Task-specific configuration

Why Orchestration-Only Main Agent: When main agent implements, everything competes for same context. Subagents get clean, dedicated context.

Model Selection

Haiku 4.5 makes multi-agent orchestration economically viable.

Test-Driven Long-Horizon Tasks

Why Tests Matter for Agents

• Tests provide objective verification targets
• Failing tests guide implementation
• Multiple rounds (2-3) yield better results
• Enable confident recovery via revert

Progressive Testing Across Sessions

Session 1: Unit tests + implementation
Session 2: Integration tests
Session 3: E2E tests
Session 4: Deployment verification

Failure Recovery

Git Recovery Strategies

Session Branches:

git checkout -b claude-session/$(date +%s)
# Merge on success, delete on failure

Checkpoint Stash:

git stash save "claude-checkpoint: $(date)"

Claude Code Checkpoints

• Esc+Esc or /rewind opens checkpoint menu
• Can restore conversation, code, or both
• Bash commands (rm, mv) are not tracked

Key Insights

What Works

1. Explicit state beats implicit understanding
2. Incremental commits beat large commits
3. Feature lists prevent premature completion
4. Tests drive implementation
5. Multi-agent beats single-agent for complex tasks

Common Pitfalls

These patterns consistently cause session failures:

1. Building everything in one session → Work one feature at a time
2. Assuming prior state → Verify with git log + progress file first
3. Relying on conversation history alone → Use structured artifacts
4. Vague requirements → Define explicit acceptance criteria
5. No recovery plan → Use session branches or checkpoint stashes

References

• Effective harnesses for long-running agents
• Claude Code Best practices
• Effective context engineering
• claude-flow - Multi-agent orchestration
• continuous-claude - CI/CD loop pattern