managing-agent-lifecycles

majiayu000's avatarfrom majiayu000

Implements persistent agent lifecycle management with 6 lifespans (ephemeral, turn, context, session, workflow, project). Use when creating agents that survive across turns, managing workflow-scoped execution, or needing automatic cleanup at lifecycle boundaries.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026⬇️1downloads
[Tool Routing and Orchestration]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for persistent agent lifecycle management, enabling the creation of agents with six distinct lifespans ranging from ephemeral tasks to long-term project services. It streamlines multi-agent orchestration by automating agent disposal and ensuring state persistence across various execution boundaries, significantly improving resource efficiency and developer productivity in complex AI workflows.

Use Cases

  • Session-Persistent Advisors: Create agents that maintain knowledge and context throughout a full user session to provide consistent architectural or technical guidance.
  • Workflow-Scoped Execution: Orchestrate multiple specialized agents (e.g., backend-dev, executor) for specific units of work like feature development, with automatic cleanup once the workflow is marked complete.
  • Resource-Efficient Helpers: Deploy 'turn-scoped' agents for immediate tasks like code analysis that are automatically disposed of after a single response to prevent context clutter.
  • Project-Level Services: Maintain long-running singleton agents that persist across multiple sessions to handle global configurations or continuous monitoring tasks.
namemanaging-agent-lifecycles
descriptionImplements persistent agent lifecycle management with 6 lifespans (ephemeral, turn, context, session, workflow, project). Use when creating agents that survive across turns, managing workflow-scoped execution, or needing automatic cleanup at lifecycle boundaries.

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

Lifespan Auto-Disposal Use Case
ephemeral Immediately Fire-and-forget tasks
turn Stop event Per-response helpers
context Context reset Multi-turn conversations
session SessionEnd Knowledge advisors
workflow Manual/complete Story/feature execution
project Manual only Singleton services

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

Method Purpose
create(config) Create or resume agent
resume(name) Resume by name
dispose(id) Dispose specific agent
startWorkflow(config) Start workflow agent
completeWorkflow(id) Complete and dispose workflow

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
  • api-reference.md - Complete API documentation
  • patterns.md - Detailed pattern implementations
  • examples.md - Real-world usage examples