Agent Continuity

Enable Claude Code agents to persist and resume across session boundaries

A comprehensive feature design for persistent agents in Claude Code. When your session ends unexpectedly, your agents continue their work. When you return, pick up exactly where you left off with full context restoration.

The Problem

When developing with parallel agents in Claude Code:

• Agents exist only in session memory
• Session loss = agents become orphaned
• All context is lost
• Manual reconstruction of work is required

The Solution

Agent Continuity provides:

✅ Automatic State Persistence - Agents save context snapshots (~10 KB) while working ✅ Session Recovery - Full context restoration when resuming ✅ Orphaned Agent Detection - Automatic notification of agents from previous sessions ✅ Intelligent Auto-Resume - Claude automatically detects and resumes previous work ✅ Agent Lifecycle Management - Automatic archival and cleanup of completed agents

Why This Matters

From a real-world scenario with 3 parallel agents:

BEFORE (Current):
- 3 agents spawned in parallel
- Session runs out of context
- Compaction fails
- Agents unreachable
- ~1800 lines of work lost

AFTER (With Agent Continuity):
- 3 agents spawn and save state to disk
- Session loss triggers orphaned agent detection
- User resumes: /resume-agents agent_001 agent_002 agent_003
- Full context injected into new session
- All agents continue seamlessly

Key Innovation

Instead of saving massive transcripts (1-10 MB), we save minimal context snapshots (< 10 KB):

• Current objective
• What's been completed
• Known blockers
• Next steps
• Key file references

This enables fast context injection without massive file I/O.

Documentation

For Different Audiences

👤 End Users → Start with User Guide

🏗️ Architects → Read Technical Design

💻 Core Developers → See Core Infrastructure

📊 Project Leads → Check Executive Summary

Complete Documentation Index

• 00_START_HERE.md - Quick orientation
• USER_GUIDE.md - Installation and usage
• TECHNICAL_DESIGN.md - Complete technical specification (45 min read)
• CORE_INFRASTRUCTURE.md - Claude Code core changes needed (40 min read)
• IMPLEMENTATION_GUIDE.md - Developer manual
• EXECUTIVE_SUMMARY.md - High-level overview (15 min read)
• QUICK_REFERENCE.md - Quick lookup guide
• plugin.json - Plugin manifest
• EXAMPLE_SCENARIO.md - Real-world example

Architecture Overview

┌─────────────────────────────────────────────────┐
│ User Session (Claude Code CLI)                  │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
    ┌──────────────────────────────────┐
    │ Agent Continuity Plugin          │
    │ ├─ /resume-agents command        │
    │ ├─ Auto-detect-resume agent      │
    │ ├─ SessionStart hook             │
    │ └─ SubagentStop hook             │
    └──────────────────┬────────────────┘
                       │
                       ▼
    ┌──────────────────────────────────────────────┐
    │ .claude/ Directory (Persistent State)        │
    │ ├─ agents.json (registry)                    │
    │ ├─ agent-{id}.local.md (state files)        │
    │ └─ agents-archive.json (completed agents)   │
    └──────────────────────────────────────────────┘

Features

1. Automatic State Persistence

Agents continuously save:

• Objective and current task
• Progress percentage
• Known blockers
• Next steps
• Key file references
• Timestamps and metadata

2. Orphaned Agent Detection

SessionStart hook automatically:

• Loads .claude/agents.json
• Finds agents with status="running"
• Displays to user with progress info
• Suggests resumption command

3. Context Injection

/resume-agents command:

• Loads agent state from registry
• Builds comprehensive context prompt
• Injects into Claude's system context
• Claude continues work seamlessly

4. Auto-Detect Resume

Intelligent agent that:

• Recognizes agent registry formats
• Detects resumption intent keywords
• Extracts agent IDs from pasted data
• Auto-invokes /resume-agents

5. Agent Lifecycle Management

Automatic handling of:

• Agent archival on completion
• Stale entry cleanup
• State file synchronization
• Registry consistency

Implementation Status

What's Included ✅

• Complete technical design specifications
• All command and agent definitions
• State file format specifications
• Real-world scenario examples
• Data flow diagrams
• Core infrastructure requirements documented
• 30+ code examples
• Implementation checklists

What Requires Claude Code Core ⏳

• Agent identity system (CLAUDE_AGENT_ID environment variable)
• Registry management API with file locking
• State writing API for agents
• Context injection mechanism
• New hook events (PreAgentResume, PostAgentResume, etc.)
• CLI commands for agent management
• File access control/scoping

Estimated Core Effort: 23 days Estimated Plugin Effort: 17 days Total: 40 days to production

Quick Start

For Claude Code Team

1. Review TECHNICAL_DESIGN.md (45 min)
2. Review CORE_INFRASTRUCTURE.md (40 min)
3. Assess feasibility and effort
4. Plan Phase 1: Agent Identity System
5. Coordinate with plugin team

For Plugin Developers

1. Review TECHNICAL_DESIGN.md
2. Begin script implementations
3. Prepare command and agent definitions
4. Wait for core API exposure
5. Integrate when core ready

Key Design Decisions

1. File-based Registry Lock - Works across processes, no external dependencies
2. Atomic Writes with Temp Files - Prevents corruption from crashes
3. Minimal Context Snapshots - Keep under 10 KB for fast loading
4. Environment Variables - Simple mechanism for agent context
5. Hook System Integration - Extensible, natural fit with Claude Code

Success Criteria

Phase 1: Design ✅

• Complete technical specifications
• Real-world examples
• Core infrastructure documented
• Code examples provided

Phase 2: Core Implementation ⏳

• Agent identity system
• Registry management
• State writing API
• Context injection
• Hook events
• CLI commands

Phase 3: Plugin Implementation ⏳

• /resume-agents command
• Auto-detect agent
• SessionStart hook
• State management scripts
• Cleanup and archival

Phase 4: Integration & Testing ⏳

• Full flow testing
• Concurrent agent handling
• Edge case handling
• Performance verification

Phase 5: Release ⏳

• Documentation complete
• Production testing
• Plugin publishing
• User announcement

Example Scenario

Your previous session with 3 parallel agents crashed:

$ claude code

🔄 ORPHANED AGENTS DETECTED

Found 3 agents from previous session:
  • agent_001 (PROJECT-001: Feature A)      45% progress
  • agent_002 (PROJECT-002: Feature B)      100% progress ✓
  • agent_003 (PROJECT-003: Feature C)      75% progress

To resume: /resume-agents agent_001 agent_002 agent_003

> /resume-agents agent_001 agent_002 agent_003

✓ Loaded context for agent_001 (45% progress)
✓ Loaded context for agent_002 (100% complete)
✓ Loaded context for agent_003 (75% progress)

Agent context injected. Which agent should we focus on next?

Why "Agent Continuity"?

• Continuity represents the persistence of work across session boundaries
• Emphasizes the goal: uninterrupted agent execution
• Reflects the philosophical approach: continuation over interruption
• Clean, professional, memorable name

Contributing

This is a design specification repository. Contributions welcome for:

• Documentation improvements
• Real-world use case examples
• Feedback on implementation approach
• Architecture discussions

License

This design specification is provided as-is for the Claude Code team and community.

Status

Design Status: ✅ Complete and Production-Ready Implementation Status: ⏳ Awaiting Claude Code Core Integration Quality Metrics: 100% design completeness, 30+ code examples, 4 data flow diagrams

---

Questions? Review the QUICK_REFERENCE.md for quick answers or dive into the full documentation.

Ready to implement? Start with CORE_INFRASTRUCTURE.md for the core team or TECHNICAL_DESIGN.md for the plugin team.