Skip to content

Latest commit

 

History

History

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

coding-agent-adapters

CLI adapters for AI coding agents. Works with pty-manager to spawn and manage coding agents like Claude Code, Gemini CLI, OpenAI Codex, Aider, and Hermes Agent.

Each adapter provides source-derived detection patterns for the full session lifecycle: login/auth, blocking prompts, ready state, exit conditions, and auto-response rules — all based on deep analysis of each CLI's open-source codebase.

Installation

npm install coding-agent-adapters pty-manager

Quick Start

import { PTYManager, AdapterRegistry } from 'pty-manager';
import { ClaudeAdapter, GeminiAdapter, AiderAdapter, HermesAdapter } from 'coding-agent-adapters';

// Create adapter registry and register the adapters you need
const registry = new AdapterRegistry();
registry.register(new ClaudeAdapter());
registry.register(new GeminiAdapter());
registry.register(new AiderAdapter());
registry.register(new HermesAdapter());

// Create PTY manager with the registry
const manager = new PTYManager({ adapters: registry });

// Spawn a Claude Code session
const session = await manager.spawn({
  name: 'code-assistant',
  type: 'claude',
  workdir: '/path/to/project',
  adapterConfig: {
    anthropicKey: process.env.ANTHROPIC_API_KEY,
  },
});

// Listen for output
session.on('output', (data) => console.log(data));

// Send a task
session.send('Help me refactor this function to use async/await');

Available Adapters

Adapter CLI Type Input Style Auto-Response Rules Ready Settle
ClaudeAdapter Claude Code claude TUI menus 5 rules 500ms
GeminiAdapter Gemini CLI gemini TUI menus 3 rules 300ms
CodexAdapter OpenAI Codex codex TUI menus 6 rules 300ms
AiderAdapter Aider aider Text (Y)es/(N)o 17 rules 200ms
HermesAdapter Hermes Agent hermes TUI prompts 0 rules 400ms

Session Lifecycle Detection

Each adapter implements detection for every stage of a CLI session.

All detection methods use stripAnsi() which strips ANSI escape sequences, cursor positioning codes, bare control characters, TUI spinner/box-drawing characters, and collapses whitespace — ensuring regex patterns match through raw terminal output. Prompt indicators (, , ) are preserved.

Login / Auth Detection

Adapters detect various auth states and methods:

const adapter = new GeminiAdapter();
const login = adapter.detectLogin(output);
// { required: true, type: 'browser', url: 'https://...', instructions: '...' }
Adapter Auth Types Source Files
Claude API key, OAuth browser CLI runtime
Gemini Google OAuth, API key entry, auth in-progress (ignores "Both keys set" success messages) AuthDialog.tsx, ApiAuthDialog.tsx, AuthInProgress.tsx
Codex Device code flow, onboarding auth menu auth.rs, headless_chatgpt_login.rs
Aider API key missing/invalid, OpenRouter OAuth onboarding.py, models.py
Hermes First-run setup gate (no API keys/providers found, Run setup now?) hermes_cli/setup.py, hermes_cli/main.py

Ready State Detection

Each adapter knows exactly what "ready for input" looks like:

Adapter Ready Indicators Source
Claude $ prompt CLI runtime
Gemini Prompt glyphs (>, !, *, (r:)), composer placeholder InputPrompt.tsx, Composer.tsx
Codex > glyph, placeholder suggestions chat_composer.rs
Aider ask>, code>, architect>, help>, multi>, startup banner io.py, base_coder.py
Hermes Idle prompt when not working; completion response box cli.py, agent/display.py

Ready Settle Delay

Each adapter sets readySettleMs to control how long pty-manager waits after detectReady() matches before emitting session_ready. This prevents the orchestrator from sending input while the TUI is still rendering (status bar, shortcuts, update notices). The base default is 300ms; adapters override based on their rendering weight.

Adapter readySettleMs Rationale
Claude Code 500ms Heaviest TUI — status bar, shortcuts, update notices, /ide suggestions
Gemini CLI 300ms Moderate Ink TUI (inherits base default)
Codex 300ms Moderate Rust TUI (inherits base default)
Aider 200ms Minimal TUI, mostly text output
Hermes Agent 400ms Prompt-toolkit UI with spinner + activity feed that settles after render

Blocking Prompt Detection

Adapters detect prompts that block the session and require user action:

Adapter Detected Prompts
Claude Permission requests, update notices
Gemini Folder trust, tool execution, validation dialogs, privacy consent
Codex Directory trust, tool approval, update available, model migration, CWD selection
Aider File operations, shell commands, git init, pip install, destructive operations
Hermes Clarify prompts, sudo password prompts, dangerous command approval choices

Loading / Active-Work Detection

Each adapter implements detectLoading(output) to detect when the CLI is actively processing — thinking spinners, file reading, model streaming. When loading is detected, pty-manager suppresses stall detection entirely, avoiding unnecessary LLM classifier calls during normal operation.

Adapter Loading Indicators Source Patterns
Claude esc to interrupt, Reading N files claude_active_reading_files
Gemini esc to cancel, Waiting for user confirmation gemini_active_loading_line
Codex esc to interrupt, Booting MCP server, Searching the web codex_active_status_row, codex_active_booting_mcp
Aider Waiting for LLM/<model>, Generating commit message with aider_active_waiting_model, aider_active_waiting_llm_default
Hermes Thinking spinner verb + elapsed time (deliberating... (2.4s)), working prompt (⚕ ❯) HermesAdapter.detectLoading()
const claude = new ClaudeAdapter();
claude.detectLoading('• Working (5s • esc to interrupt)');  // true
claude.detectLoading('Reading 42 files…');                   // true
claude.detectLoading('❯ ');                                  // false

const aider = new AiderAdapter();
aider.detectLoading('Waiting for claude-sonnet-4-20250514'); // true
aider.detectLoading('code> ');                                // false

Task Completion Detection

Each adapter implements detectTaskComplete(output) to recognize when the CLI has finished a task and returned to its idle prompt. This is more specific than detectReady() — it matches high-confidence completion indicators (duration summaries, explicit done messages) that short-circuit the LLM stall classifier in pty-manager. Patterns match through raw ANSI-laden TUI output including spinner characters and cursor positioning codes.

Adapter Completion Indicators Source Patterns
Claude Turn duration (Cooked for 3m 12s, custom verb) + prompt (tolerates trailing status bar) claude_completed_turn_duration
Gemini ◇ Ready window title, Type your message composer gemini_ready_title
Codex Worked for 1m 05s separator + prompt codex_completed_worked_for_separator, codex_ready_prompt
Aider Aider is waiting for your input, mode prompts (including plain >) with edit/cost markers aider_completed_llm_response_ready
Hermes Final response box (╭─ ⚕ Hermes ... ╰), or tool-feed line + idle prompt HermesAdapter.detectTaskComplete()
const claude = new ClaudeAdapter();
claude.detectTaskComplete('Cooked for 3m 12s\n❯ ');  // true
claude.detectTaskComplete('Reading 5 files…');         // false

const aider = new AiderAdapter();
aider.detectTaskComplete('Applied edit to main.ts\nTokens: 1234\ncode> ');  // true
aider.detectTaskComplete('Waiting for claude-sonnet-4-20250514');            // false

Exit Detection

Adapters detect when a CLI session has ended:

Adapter Exit Conditions
Claude Base exit detection
Gemini Folder trust rejection, logout confirmation
Codex Session end, update completion
Aider Ctrl+C / KeyboardInterrupt, version update requiring restart
Hermes Goodbye! ⚕

Auto-Response Rules

Adapters include pre-configured rules to automatically handle known prompts. Rules use two response modes depending on the CLI's input style.

TUI Menu CLIs (Gemini, Codex, Claude, Hermes)

These CLIs use arrow-key menus rendered with Ink/Ratatui. Rules send key sequences:

const codex = new CodexAdapter();
codex.autoResponseRules;
// [
//   { pattern: /update.?available/i, responseType: 'keys', keys: ['down', 'enter'], once: true, ... },
//   { pattern: /trust.?this.?directory/i, responseType: 'keys', keys: ['enter'], once: true, ... },
//   { pattern: /model.?migration/i, responseType: 'keys', keys: ['enter'], once: true, ... },
//   ...
// ]

Text Prompt CLIs (Aider)

Aider uses plain text (Y)es/(N)o prompts via io.py. Rules send typed text:

const aider = new AiderAdapter();
aider.autoResponseRules;
// [
//   { pattern: /allow collection of anonymous analytics/i, response: 'n', responseType: 'text', once: true, ... },
//   { pattern: /add .+ to the chat\?/i, response: 'y', responseType: 'text', ... },
//   { pattern: /create new file\?/i, response: 'y', responseType: 'text', ... },
//   { pattern: /run shell commands?\?/i, response: 'y', responseType: 'text', ... },
//   ...17 rules total
// ]

The usesTuiMenus Flag

Adapters declare their input style via usesTuiMenus. This affects how auto-response rules with no explicit responseType are delivered:

  • usesTuiMenus: true (Gemini, Codex, Claude, Hermes) — defaults to sendKeys('enter')
  • usesTuiMenus: false (Aider) — defaults to writeRaw(response + '\r')

Model Recommendations

Each adapter provides model recommendations based on available credentials:

const aider = new AiderAdapter();

aider.getRecommendedModels({ anthropicKey: 'sk-ant-...' });
// { powerful: 'anthropic/claude-sonnet-4-20250514', fast: 'anthropic/claude-haiku-4-5-20251001' }

aider.getRecommendedModels({ googleKey: 'AIza...' });
// { powerful: 'gemini/gemini-3-pro', fast: 'gemini/gemini-3-flash' }

Workspace Files & Memory

Each coding agent CLI has its own convention for project-level memory files (instructions the agent reads on startup) and config files. Adapters expose this knowledge so orchestration systems can write context to the correct files before spawning an agent.

Discovering Workspace Files

import { ClaudeAdapter, AiderAdapter } from 'coding-agent-adapters';

const claude = new ClaudeAdapter();
claude.getWorkspaceFiles();
// [
//   { relativePath: 'CLAUDE.md', type: 'memory', autoLoaded: true, format: 'markdown', ... },
//   { relativePath: '.claude/settings.json', type: 'config', autoLoaded: true, format: 'json', ... },
//   { relativePath: '.claude/commands', type: 'config', autoLoaded: false, format: 'markdown', ... },
// ]

claude.memoryFilePath; // 'CLAUDE.md'

const aider = new AiderAdapter();
aider.memoryFilePath; // '.aider.conventions.md'

Per-Adapter File Mappings

Adapter Memory File Config Other
Claude CLAUDE.md .claude/settings.json .claude/commands
Gemini GEMINI.md .gemini/settings.json .gemini/styles
Codex AGENTS.md .codex/config.json codex.md
Aider .aider.conventions.md .aider.conf.yml .aiderignore
Hermes AGENTS.md cli-config.yaml SOUL.md

Writing Memory Files

Use writeMemoryFile() to write instructions into a workspace before spawning an agent. Parent directories are created automatically.

const adapter = new ClaudeAdapter();

// Write to the adapter's default memory file (CLAUDE.md)
await adapter.writeMemoryFile('/path/to/workspace', `# Project Context
This is a TypeScript monorepo using pnpm workspaces.
Always run tests before committing.
`);

// Append to an existing memory file
await adapter.writeMemoryFile('/path/to/workspace', '\n## Additional Rules\nUse snake_case.\n', {
  append: true,
});

// Write to a custom file (e.g., template-specific context for sub-agents)
await adapter.writeMemoryFile('/path/to/workspace', '# Task-Specific Context\n...', {
  fileName: 'TASK_CONTEXT.md',
});

Approval Presets

Each coding agent CLI has its own config format for controlling tool permissions. The approval preset system provides 4 named levels that translate to the correct per-CLI config files and CLI flags.

Preset Levels

Preset Description Auto-approve Require approval Blocked
readonly Read-only. Safe for auditing. file_read, planning, user_interaction file_write, shell, web, agent
standard Standard dev. Reads + web auto, writes/shell prompt. file_read, planning, user_interaction, web file_write, shell, agent
permissive File ops auto-approved, shell still prompts. file_read, file_write, planning, user_interaction, web, agent shell
autonomous Everything auto-approved. Use with sandbox. all categories

Generating Configs

import { generateApprovalConfig, listPresets, getPresetDefinition } from 'coding-agent-adapters';

// List all available presets
const presets = listPresets();

// Generate CLI-specific config for a preset
const config = generateApprovalConfig('claude', 'permissive');
// {
//   preset: 'permissive',
//   cliFlags: [],
//   workspaceFiles: [{ relativePath: '.claude/settings.json', content: '...', format: 'json' }],
//   envVars: {},
//   summary: 'Claude Code: File ops auto-approved, shell still prompts.',
// }

// Each CLI gets its own config format
generateApprovalConfig('gemini', 'readonly');   // → .gemini/settings.json + --approval-mode plan
generateApprovalConfig('codex', 'autonomous');  // → .codex/config.json + --full-auto
generateApprovalConfig('aider', 'permissive');  // → .aider.conf.yml + --yes-always

Using Presets with Adapters

When approvalPreset is set in adapterConfig, the adapter's getArgs() automatically appends the correct CLI flags:

const session = await manager.spawn({
  name: 'sandboxed-agent',
  type: 'claude',
  workdir: '/path/to/project',
  adapterConfig: {
    anthropicKey: process.env.ANTHROPIC_API_KEY,
    approvalPreset: 'autonomous',
  },
});

You can also write the config files to a workspace manually using writeApprovalConfig():

const adapter = new ClaudeAdapter();
const writtenFiles = await adapter.writeApprovalConfig('/path/to/workspace', {
  adapterConfig: { approvalPreset: 'permissive' },
});
// writtenFiles: ['/path/to/workspace/.claude/settings.json']

Per-CLI Output

CLI Config File Key Controls
Claude Code .claude/settings.json permissions.allow, permissions.deny, sandbox.*
Gemini CLI .gemini/settings.json general.defaultApprovalMode, tools.allowed, tools.exclude
Codex .codex/config.json approval_policy, sandbox_mode, tools.web_search
Aider .aider.conf.yml yes-always, no-auto-commits
Hermes Agent none (CLI-managed) approvals currently handled in-session by Hermes safety prompts

Preflight Check

Before spawning agents, check if the required CLIs are installed:

import { checkAdapters, checkAllAdapters, printMissingAdapters } from 'coding-agent-adapters';

// Check specific adapters
const results = await checkAdapters(['claude', 'aider']);
for (const result of results) {
  if (result.installed) {
    console.log(`${result.adapter} v${result.version}`);
  } else {
    console.log(`${result.adapter} - Install: ${result.installCommand}`);
  }
}

// Check all adapters
const allResults = await checkAllAdapters();

// Print formatted installation instructions for missing tools
await printMissingAdapters(['claude', 'gemini']);

Passing Credentials

You can pass API keys either via environment variables or through adapterConfig:

// Via environment variables (recommended for production)
process.env.ANTHROPIC_API_KEY = 'sk-ant-...';

const session = await manager.spawn({
  name: 'claude-agent',
  type: 'claude',
  workdir: '/project',
});

// Via adapterConfig (useful for multi-tenant scenarios)
const session = await manager.spawn({
  name: 'claude-agent',
  type: 'claude',
  workdir: '/project',
  adapterConfig: {
    anthropicKey: 'sk-ant-...',
    openaiKey: 'sk-...',
    googleKey: 'AIza...',
  },
});

Claude Hook Telemetry (Optional)

Claude Code hooks can emit deterministic lifecycle markers so PTY orchestration does not rely only on screen-text heuristics.

ClaudeAdapter supports this as an opt-in mode:

const session = await manager.spawn({
  name: 'claude-agent',
  type: 'claude',
  workdir: '/project',
  adapterConfig: {
    anthropicKey: process.env.ANTHROPIC_API_KEY,
    claudeHookTelemetry: true,
  },
});

When enabled, the adapter sets:

  • PARALLAX_CLAUDE_HOOK_TELEMETRY=1
  • PARALLAX_CLAUDE_HOOK_MARKER_PREFIX=PARALLAX_CLAUDE_HOOK (or your override)

Marker Protocol

Hook scripts should print single-line markers:

PARALLAX_CLAUDE_HOOK {"event":"Notification","notification_type":"permission_prompt","message":"..."}

Supported high-value events:

  • Notification (permission_prompt, elicitation_dialog, idle_prompt)
  • PreToolUse (includes tool_name)
  • TaskCompleted
  • SessionEnd

The adapter consumes these markers in:

  • detectBlockingPrompt()
  • detectLoading()
  • detectToolRunning()
  • detectTaskComplete()
  • detectReady()
  • detectExit()

Generate Hook Config Template

const claude = new ClaudeAdapter();
const protocol = claude.getHookTelemetryProtocol();

// protocol.scriptPath
// protocol.scriptContent
// protocol.settingsHooks

settingsHooks is ready to merge into .claude/settings.json under hooks.

Gemini Hook Telemetry (Optional)

Gemini CLI hooks can emit deterministic lifecycle markers so PTY orchestration does not rely only on screen-text heuristics.

GeminiAdapter supports this as an opt-in mode:

const session = await manager.spawn({
  name: 'gemini-agent',
  type: 'gemini',
  workdir: '/project',
  adapterConfig: {
    googleKey: process.env.GEMINI_API_KEY,
    geminiHookTelemetry: true,
  },
});

When enabled, the adapter sets:

  • PARALLAX_GEMINI_HOOK_TELEMETRY=1
  • PARALLAX_GEMINI_HOOK_MARKER_PREFIX=PARALLAX_GEMINI_HOOK (or your override)

Marker Protocol

Gemini hook command output must be valid JSON. The helper script emits marker lines via systemMessage:

PARALLAX_GEMINI_HOOK {"event":"BeforeTool","tool_name":"run_shell_command"}

Supported high-value events:

  • Notification (ToolPermission)
  • BeforeTool (includes tool_name)
  • AfterAgent
  • SessionEnd

The adapter consumes these markers in:

  • detectBlockingPrompt()
  • detectLoading()
  • detectToolRunning()
  • detectTaskComplete()
  • detectReady()
  • detectExit()

Generate Hook Config Template

const gemini = new GeminiAdapter();
const protocol = gemini.getHookTelemetryProtocol();

// protocol.scriptPath
// protocol.scriptContent
// protocol.settingsHooks

settingsHooks is ready to merge into .gemini/settings.json under hooks.

Creating Custom Adapters

Extend BaseCodingAdapter to create adapters for other coding CLIs:

import { BaseCodingAdapter } from 'coding-agent-adapters';
import type { AgentFileDescriptor, InstallationInfo, ModelRecommendations } from 'coding-agent-adapters';
import type { SpawnConfig, ParsedOutput, LoginDetection, AutoResponseRule } from 'pty-manager';

export class CursorAdapter extends BaseCodingAdapter {
  readonly adapterType = 'cursor';
  readonly displayName = 'Cursor';

  readonly installation: InstallationInfo = {
    command: 'npm install -g cursor-cli',
    docsUrl: 'https://cursor.sh/docs',
  };

  // Set to false if the CLI uses text prompts instead of TUI menus
  override readonly usesTuiMenus = false;

  // Tune ready settle delay for this CLI's rendering speed (base default: 300ms)
  override readonly readySettleMs = 250;

  readonly autoResponseRules: AutoResponseRule[] = [
    { pattern: /accept terms/i, type: 'tos', response: 'y', responseType: 'text', description: 'Accept TOS', safe: true, once: true },
  ];

  getWorkspaceFiles(): AgentFileDescriptor[] {
    return [
      { relativePath: '.cursor/rules', description: 'Project rules', autoLoaded: true, type: 'memory', format: 'markdown' },
    ];
  }

  getRecommendedModels(): ModelRecommendations {
    return { powerful: 'claude-sonnet-4', fast: 'gpt-4o-mini' };
  }

  getCommand(): string { return 'cursor'; }
  getArgs(config: SpawnConfig): string[] { return ['--cli']; }
  getEnv(config: SpawnConfig): Record<string, string> { return {}; }

  detectLogin(output: string): LoginDetection {
    if (/login required/i.test(output)) {
      return { required: true, type: 'browser' };
    }
    return { required: false };
  }

  detectReady(output: string): boolean {
    return /cursor>\s*$/m.test(output);
  }

  detectLoading(output: string): boolean {
    // Active loading indicator — suppresses stall detection
    return /processing|thinking/i.test(output);
  }

  detectTaskComplete(output: string): boolean {
    // High-confidence: task summary + idle prompt
    return /completed in \d+s/.test(output) && /cursor>\s*$/m.test(output);
  }

  parseOutput(output: string): ParsedOutput | null {
    return { type: 'response', content: output.trim(), isComplete: true, isQuestion: output.includes('?') };
  }

  getPromptPattern(): RegExp { return /cursor>\s*$/; }
}

Convenience Functions

import { createAllAdapters, createAdapter, ADAPTER_TYPES } from 'coding-agent-adapters';

// Create all adapters at once
const allAdapters = createAllAdapters();

// Create a specific adapter
const claude = createAdapter('claude');

// Available adapter types
console.log(Object.keys(ADAPTER_TYPES)); // ['claude', 'gemini', 'codex', 'aider', 'hermes']

License

MIT