Terminal Manager

Adapter Selection

The manager auto-detects the environment for adapter selection:

Terminal Operations

Spawn Terminal

const terminalId = await manager.spawnTerminal({
  id: 'agent-1',
  type: 'worker',
  metadata: {
    workingDirectory: '/project',
    initCommands: ['nvm use 20', 'export NODE_ENV=development'],
    cleanupCommands: ['rm -f /tmp/agent-1-*'],
  },
});

Execute Command

const output = await manager.executeCommand(terminalId, 'npm test');
// Executes with configured timeout
// Returns stdout output
// Throws TerminalCommandError on failure or timeout

Terminate Terminal

await manager.terminateTerminal(terminalId);
// Runs cleanup commands
// Returns terminal to pool
// Removes session

Stream Output

const unsubscribe = await manager.streamOutput(terminalId, (output) => {
  console.log('Terminal output:', output);
});
// Returns unsubscribe function to stop streaming

Health Status

const health = await manager.getHealthStatus();
// {
//   healthy: boolean,
//   error?: string,
//   metrics: {
//     activeSessions: number,
//     healthySessions: number,
//     poolSize: number,
//     availableTerminals: number,
//     recycledTerminals: number,
//   },
// }

Maintenance

await manager.performMaintenance();
// Cleans up dead sessions
// Performs pool maintenance
// Emits 'terminal:maintenance' event

List Active Sessions

const sessions = manager.getActiveSessions();
// Returns AgentSession[] with: id, agentId, terminalId, startTime, status, lastActivity

Terminal Session

Each spawned terminal is wrapped in a TerminalSession:

class TerminalSession {
  readonly id: string;              // Unique session ID (session-*)
  readonly startTime: Date;
  readonly terminal: Terminal;
  readonly profile: AgentProfile;

  // Execute command with timeout protection
  async executeCommand(command: string): Promise<string>;

  // Check if session is healthy
  isHealthy(): boolean;

  // Get command history
  getCommandHistory(): string[];

  // Stream output
  streamOutput(callback: (output: string) => void): () => void;

  // Cleanup
  async cleanup(): Promise<void>;
}

Session Initialization

When a session initializes, it:

1. Sets environment variables:
   • CLAUDE_FLOW_SESSION — Session ID
   • CLAUDE_FLOW_AGENT — Agent ID
   • CLAUDE_FLOW_AGENT_TYPE — Agent type
2. Changes to the agent's working directory (if specified)
3. Runs profile-specific initialization commands
4. Sets command prompt to [claude-flow]$

Health Checking

Sessions are considered unhealthy if:

• Terminal process is not alive
• Last command was > 5 minutes ago (triggers async health check)

Health check sends echo "HEALTH_CHECK_OK" with a 5-second timeout.

Terminal Pool

The TerminalPool manages terminal lifecycle and reuse:

class TerminalPool {
  async initialize(): Promise<void>;
  async acquire(): Promise<Terminal>;       // Get terminal from pool
  async release(terminal: Terminal): void;  // Return terminal to pool
  async shutdown(): Promise<void>;
  async getHealthStatus(): Promise<PoolHealthStatus>;
  async performMaintenance(): Promise<void>;
}

Pool Behavior

• Maintains a pool of pre-created terminals up to maxSize
• Tracks use count per terminal for recycling
• Recycles terminals after recycleAfter uses
• Available terminals queued for reuse

VSCode Bridge

The VSCode bridge integrates with the VSCode extension API for terminal management:

import { initializeTerminalBridge } from './terminal/vscode-bridge';

// Initialize in VSCode extension context
initializeTerminalBridge(context);

VSCode Terminal Features

• Output Capture — Intercepts terminal.sendText for command capture
• Write Emulators — EventEmitter<string> for output streaming
• Terminal Registry — Tracks active terminals by ID pattern Claude-Flow Terminal {id}
• Lifecycle Management — Cleanup on terminal close via onDidCloseTerminal

Create Captured Terminal

import { createCapturedTerminal } from './terminal/vscode-bridge';

const { terminal, onData } = await createCapturedTerminal(
  'Claude-Flow Terminal worker-1',
  '/bin/bash',
  ['--login']
);

onData((data) => {
  console.log('Output:', data);
});

Execute with Output Capture

import { executeTerminalCommand } from './terminal/vscode-bridge';

const output = await executeTerminalCommand(terminal, 'npm test', 30000);
// Uses completion markers for output boundary detection
// Times out after specified duration

Terminal Adapters

Base Adapter Interface

interface ITerminalAdapter {
  initialize(): Promise<void>;
  shutdown(): Promise<void>;
  createTerminal(): Promise<Terminal>;
  destroyTerminal(terminal: Terminal): Promise<void>;
}

interface Terminal {
  id: string;
  isAlive(): boolean;
  executeCommand(command: string): Promise<string>;
  addOutputListener?(callback: (data: string) => void): void;
  removeOutputListener?(callback: (data: string) => void): void;
}

Native Adapter

Uses child processes for terminal management. Works in all environments.

VSCode Adapter

Uses the VSCode extension API (vscode.window.createTerminal) with output capture hooks.

Error Types

• TerminalError — General terminal errors
• TerminalSpawnError — Failed to create terminal
• TerminalCommandError — Command execution failed or timed out

Events

• terminal:maintenance — Maintenance cycle completed (includes dead session count, pool status)