Managing Agent Lifecycles

Managing Agent Lifecycles

Persistent agent lifecycle management for Claude Code projects. Creates agents with defined lifespans and automatic disposal.

When to Use

• Creating agents that persist beyond a single call
• Managing workflow-scoped agents (story execution, feature development)
• Automatic agent cleanup at lifecycle boundaries (Stop, SessionEnd)
• Building systems with multiple cooperating agents

Quick Start

import { AgentRegistry } from 'claude-agent-lifecycle';

const registry = new AgentRegistry();

// Create session-scoped agent (survives until session ends)
const { agent, isNew } = await registry.create({
  lifespan: 'session',
  name: 'my-advisor',
  model: 'haiku',
});

// Resume later in same session
const advisor = await registry.resume('my-advisor');

The 6 Lifespans

Choosing a Lifespan

How long should the agent live?
├── Just this one call? → ephemeral
├── Until response completes? → turn
├── Until context resets? → context
├── Until session ends? → session
├── Until work unit completes? → workflow
└── Forever (manual disposal)? → project

Implementation Checklist

When implementing agent lifecycle management:

• Install package: bun add claude-agent-lifecycle
• Choose appropriate lifespan for each agent type
• Configure hooks for automatic disposal (Stop, SessionEnd)
• Use descriptive agent names (e.g., backend-dev not agent1)
• Store role and capabilities in metadata
• Test with debug mode enabled

Common Patterns

Pattern 1: Session-Scoped Advisor

For agents persisting throughout a Claude Code session:

const { agent, isNew } = await registry.create({
  lifespan: 'session',
  name: 'shadow-advisor',
  model: 'haiku',
  metadata: { role: 'knowledge-retrieval' },
});

Pattern 2: Workflow-Scoped Execution

For agents tied to a unit of work:

// Start executor for story
await registry.startWorkflow({
  lifespan: 'workflow',
  workflowId: 'FEAT-001',
  name: 'executor',
});

// Add specialists
await registry.startWorkflow({
  lifespan: 'workflow',
  workflowId: 'FEAT-001',
  name: 'backend-dev',
});

// Complete when done (disposes all workflow agents)
await registry.completeWorkflow('FEAT-001');

Pattern 3: Turn-Scoped Helper

For short-lived per-response agents:

const { agent } = await registry.create({
  lifespan: 'turn',
  name: 'code-analyzer',
});
// Automatically disposed when Stop hook fires

See patterns.md for detailed implementations.

Hook Integration

Hooks automatically dispose agents at lifecycle boundaries.

hooks/​hooks.json

{
  "Stop": [{
    "hooks": [{
      "type": "command",
      "command": "bun \"${CLAUDE_PLUGIN_ROOT}/​hooks/​lifecycle-manager.ts\""
    }]
  }],
  "SessionEnd": [{
    "hooks": [{
      "type": "command",
      "command": "bun \"${CLAUDE_PLUGIN_ROOT}/​hooks/​lifecycle-manager.ts\""
    }]
  }]
}

hooks/​lifecycle-manager.ts

import { AgentRegistry } from 'claude-agent-lifecycle';
import { getHookEvent } from 'claude-hooks-sdk';

const event = getHookEvent();
const registry = new AgentRegistry();

if (event.type === 'Stop') {
  await registry.disposeByLifespan('turn');
}

if (event.type === 'SessionEnd') {
  await registry.disposeByScope(event.session.sessionId);
}

Storage Structure

.agent/​agents/
├── session/​{session-id}/​{agent-name}.json
├── workflow/​{workflow-id}/​{agent-name}.json
└── project/​{agent-name}.json

Debug Mode

Enable for troubleshooting:

AGENT_LIFECYCLE_DEBUG=true claude

Output:

[agent-lifecycle] Created: shadow-advisor (session)
[agent-lifecycle] Stop: Disposed 1 turn-scoped agents

API Summary

See api-reference.md for complete API documentation.

Installation

# As plugin (recommended)
/​plugin marketplace add hgeldenhuys/​claude-agent-lifecycle
/​plugin install claude-agent-lifecycle

# As package
bun add claude-agent-lifecycle

Related Files

• api-reference.md - Complete API documentation
• patterns.md - Detailed pattern implementations
• examples.md - Real-world usage examples