Cloister: AI Lifecycle Manager

Cloister is Panopticon’s intelligent agent lifecycle manager. It monitors all running agents and automatically handles:

Model Routing - Routes tasks to appropriate models based on complexity, across multiple providers
Stuck Detection - Identifies agents that have stopped making progress
Automatic Handoffs - Escalates to specialists when needed
Specialist Coordination - Manages review-agent, test-agent, inspect-agent, uat-agent, and merge-agent

How Cloister Works

┌─────────────────────────────────────────────────────────────┐
│                     CLOISTER SERVICE                         │
│                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │  Heartbeat  │───▶│   Trigger   │───▶│   Handoff   │     │
│  │   Monitor   │    │   Detector  │    │   Manager   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│         │                  │                  │             │
│         ▼                  ▼                  ▼             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   Agent     │    │  Complexity │    │ Specialists │     │
│  │   Health    │    │   Analysis  │    │  (5 types)  │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
└─────────────────────────────────────────────────────────────┘

Starting Cloister

# Via dashboard - click "Start" in the Cloister status bar
# Or via CLI:
pan cloister start

# Check status
pan cloister status

# Stop monitoring
pan cloister stop

Specialists

Cloister manages five specialized agents that handle specific phases of the development lifecycle:

Specialist	Purpose	Trigger
review-agent	Code review before merge	Human clicks “Review”
test-agent	Runs test suite after review	After review passes
inspect-agent	Per-step verification during implementation	After each bead completion
uat-agent	Browser-based requirement verification	After tests pass
merge-agent	Handles git merge and conflict resolution	”Approve & Merge” button

See the Specialists feature guide for detailed information on specialist agents.

Review Pipeline Flow

The review pipeline is a sequential handoff between specialists:

Human clicks "Review"
        │
        ▼
┌───────────────────┐
│   review-agent    │ Reviews code, checks for issues
└─────────┬─────────┘
          │ If PASSED: queues test-agent
          │ If BLOCKED: sends feedback to work-agent
          ▼
┌───────────────────┐
│    test-agent     │ Runs test suite, analyzes failures
└─────────┬─────────┘
          │ If PASSED: queues uat-agent
          │ If FAILED: sends feedback to work-agent
          ▼
┌───────────────────┐
│    uat-agent      │ Browser-based requirement verification
└─────────┬─────────┘
          │ If PASSED: marks ready for merge
          │ If FAILED: sends feedback to work-agent
          ▼
┌───────────────────┐
│  (Human clicks    │ Human approval required
│  "Approve & Merge"│ before merge
└─────────┬─────────┘
          ▼
┌───────────────────┐
│   merge-agent     │ Performs merge, resolves conflicts
└───────────────────┘

Additionally, inspect-agent runs during implementation (between beads), not as part of this post-implementation pipeline. Key Points:

Human-initiated start - A human must click “Review” to start the pipeline
Automatic handoffs - review-agent → test-agent → uat-agent happens automatically
Human approval for merge - Merge is NOT automatic; human clicks “Approve & Merge”
Feedback loops - Failed reviews/tests/UAT send feedback back to the work-agent

Queue Processing

Each specialist has a task queue (~/.panopticon/specialists/{name}/hook.json) managed via the FPP (Fixed Point Principle):

1. Task arrives (via API or handoff)
        │
        ▼
2. wakeSpecialistOrQueue() checks if specialist is busy
        │
        ├── If IDLE: Wake specialist immediately with task
        │
        └── If BUSY: Add task to queue (hook.json)
                │
                ▼
3. When specialist completes current task:
        │
        ├── Updates status via API (passed/failed/skipped)
        │
        └── Dashboard automatically wakes specialist for next queued task

Queue priority order: urgent > high > normal > low Completion triggers: When a specialist reports status (passed, failed, or skipped), the dashboard:

Sets the specialist state to idle
Checks the specialist’s queue for pending work
If work exists, immediately wakes the specialist with the next task

Agent Self-Requeue (Circuit Breaker)

After a human initiates the first review, work-agents can request re-review up to 3 times automatically:

# Work-agent requests re-review after fixing issues
pan work request-review MIN-123 -m "Fixed: added tests for edge cases"

Circuit breaker behavior:

First human click resets the counter to 0
Each pan work request-review increments the counter
After 3 automatic re-requests, returns HTTP 429
Human must click “Review” in dashboard to continue

This prevents infinite loops where an agent repeatedly fails review. API endpoint: POST /api/workspaces/:issueId/request-review

Specialist Auto-Initialization

When Cloister starts, it automatically initializes specialists that don’t exist yet. This ensures all five specialists are ready to receive wake signals without manual setup.

Automatic Handoffs

Cloister detects situations that require intervention:

Trigger	Condition	Action
stuck_escalation	No activity for 30+ minutes	Escalate to more capable model
complexity_upgrade	Task complexity exceeds model capability	Route to Opus
implementation_complete	Agent signals work is done	Wake review-agent
test_failure	Tests fail repeatedly	Escalate model or request help
planning_complete	Planning session finishes	Transition to implementation
merge_requested	User clicks “Approve & Merge”	Wake merge-agent

Handoff Methods

Cloister supports two handoff methods, automatically selected based on agent type:

Method	When Used	How It Works
Kill & Spawn	General agents (agent-min-123, etc.)	1. Captures full context (STATE.md, beads, git state) 2. Kills tmux session 3. Spawns new agent with handoff prompt 4. New agent continues work with preserved context
Specialist Wake	Permanent specialists (merge-agent, test-agent, etc.)	1. Captures handoff context 2. Sends wake message to existing session 3. Specialist resumes with context injection

Kill & Spawn is used for temporary agents that work on specific issues. It creates a clean handoff by:

Capturing the agent’s current understanding (from STATE.md)
Preserving beads task progress and open items
Including relevant git diff and file context
Building a comprehensive handoff prompt for the new model

Specialist Wake is used for permanent specialists that persist across multiple issues. It avoids the overhead of killing/respawning by injecting context into the existing session.

Handoff Context Capture

When a handoff occurs, Cloister captures:

{
  "agentId": "agent-min-123",
  "issueId": "MIN-123",
  "currentModel": "kimi-k2.5",
  "targetModel": "opus",
  "reason": "stuck_escalation",
  "handoffCount": 1,
  "state": {
    "phase": "implementation",
    "complexity": "complex",
    "lastActivity": "2024-01-22T10:30:00-08:00"
  },
  "beadsTasks": [...],
  "gitContext": {
    "branch": "feature/min-123",
    "uncommittedChanges": ["src/auth.ts", "src/tests/auth.test.ts"],
    "recentCommits": [...]
  }
}

Handoff prompts are saved to ~/.panopticon/agents/{agent-id}/handoffs/ for debugging.

Heartbeat Monitoring

Agents send heartbeats via Claude Code hooks. Cloister tracks:

Last tool use and timestamp
Current task being worked on
Git branch and workspace
Process health

Heartbeat files are stored in ~/.panopticon/heartbeats/:

{
  "timestamp": "2024-01-22T10:30:00-08:00",
  "agent_id": "agent-min-123",
  "tool_name": "Edit",
  "last_action": "{\"file_path\":\"/path/to/file.ts\"...}",
  "git_branch": "feature/min-123",
  "workspace": "/home/user/projects/myapp/workspaces/feature-min-123"
}

Heartbeat Hook Installation

The heartbeat hook is automatically synced to ~/.panopticon/bin/heartbeat-hook via pan sync. It’s also installed automatically when you install or upgrade Panopticon via npm. Manual installation:

pan sync  # Syncs all skills, agents, AND hooks

Hook configuration in ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.panopticon/bin/heartbeat-hook"
          }
        ]
      }
    ]
  }
}

Hook resilience: The heartbeat hook is designed to fail silently if:

The heartbeats directory doesn’t exist
Write permissions are missing
The hook script has errors

This prevents hook failures from interrupting agent work.

Configuration

Cloister configuration lives in ~/.panopticon/cloister/config.json:

{
  "monitoring": {
    "heartbeat_interval_ms": 5000,
    "stuck_threshold_minutes": 30,
    "health_check_interval_ms": 30000
  },
  "specialists": {
    "review_agent": { "enabled": true, "auto_wake": false },
    "test_agent": { "enabled": true, "auto_wake": true },
    "inspect_agent": { "enabled": true },
    "uat_agent": { "enabled": true },
    "merge_agent": { "enabled": true, "auto_wake": false }
  },
  "triggers": {
    "stuck_escalation": { "enabled": true },
    "complexity_upgrade": { "enabled": true }
  }
}

Model Routing & Complexity Detection

Cloister automatically routes tasks to the appropriate model based on detected complexity, optimizing for cost while ensuring quality. Model routing supports multiple providers: Anthropic, OpenAI, Google, Kimi, and Zhipu.

Complexity Levels

Level	Default Model	Use Case
trivial	Haiku	Typos, comments, documentation updates
simple	Haiku	Small fixes, test additions, minor changes
medium	Kimi	Features, components, integrations
complex	Kimi	Refactors, migrations, redesigns
expert	Opus	Architecture, security, performance optimization

The default implementation model is configurable per-project. Kimi is the current default for medium/complex tasks, providing a cost-effective alternative to Sonnet with strong coding performance.

Complexity Detection Signals

Complexity is detected from multiple signals (in priority order):

Explicit field - Task has a complexity field set (e.g., in beads)
Labels/tags - Issue labels like architecture, security, refactor
Keywords - Title/description contains keywords like “migration”, “overhaul”
File count - Number of files changed (>20 files = complex)
Time estimate - If estimate exceeds thresholds

Keyword patterns:

{
  trivial: ['typo', 'rename', 'comment', 'documentation', 'readme'],
  simple: ['add comment', 'update docs', 'fix typo', 'small fix'],
  medium: ['feature', 'endpoint', 'component', 'service'],
  complex: ['refactor', 'migration', 'redesign', 'overhaul'],
  expert: ['architecture', 'security', 'performance optimization']
}

Configuring Model Routing

Model routing is configured via the dashboard Settings page or ~/.panopticon/cloister/config.json:

{
  "model_selection": {
    "default_model": "kimi-k2.5",
    "complexity_routing": {
      "trivial": "haiku",
      "simple": "haiku",
      "medium": "kimi-k2.5",
      "complex": "kimi-k2.5",
      "expert": "opus"
    }
  }
}

Supported Providers

Provider	Models	Use Case
Anthropic	Opus, Sonnet, Haiku	Planning (Opus), review, general
OpenAI	GPT-4o, o1	Alternative implementation
Google	Gemini	Alternative implementation
Kimi	Kimi K2.5	Cost-effective implementation (default)
Zhipu	GLM-4	Alternative implementation

Cost Optimization

Model routing helps optimize costs:

Model	Relative Cost	Best For
Haiku	1x (cheapest)	Simple tasks, bulk operations
Kimi	~2x	Most implementation work (default)
Sonnet	3x	Review, complex implementation
Opus	15x	Planning, architecture, critical fixes

A typical agent run might:

Plan with Opus (high-quality strategic decisions)
Implement with Kimi (cost-effective coding)
Escalate to Opus only if stuck or complexity detected

Specialists - Detailed specialist agent documentation
Convoys - Multi-agent orchestration
Core Commands - Cloister CLI commands

Features

Documentation Index

​Cloister: AI Lifecycle Manager

​How Cloister Works

​Starting Cloister

​Specialists

​Review Pipeline Flow

​Queue Processing

​Agent Self-Requeue (Circuit Breaker)

​Specialist Auto-Initialization

​Automatic Handoffs

​Handoff Methods

​Handoff Context Capture

​Heartbeat Monitoring

​Heartbeat Hook Installation

​Configuration

​Model Routing & Complexity Detection

​Complexity Levels

​Complexity Detection Signals

​Configuring Model Routing

​Supported Providers

​Cost Optimization

​Related Guides