Module agents 

Agent Abstraction Module

Provides a pluggable agent system for different AI coding assistants (Claude, Codex, OpenCode, Goose, Cline, CCS, etc.)

Module Structure

• ccs - CCS (Claude Code Switch) alias resolution
• config - Agent configuration types and TOML parsing
• error - Error classification for fault-tolerant execution
• fallback - Fallback chain configuration for agent switching
• parser - JSON parser type definitions
• providers - OpenCode provider types and authentication
• registry - Agent registry for agent lookup and management

Configuration

Agents can be configured via (in order of increasing priority):

1. Built-in defaults (claude, codex, opencode, ccs, aider, goose, cline, continue, amazon-q, gemini)
2. Unified config file (~/.config/ralph-workflow.toml)
3. Environment variables (RALPH_DEVELOPER_CMD, RALPH_REVIEWER_CMD)
4. Programmatic registration via AgentRegistry::register()

CCS (Claude Code Switch) Support

CCS aliases can be defined in the unified config and used with ccs/alias syntax:

[ccs_aliases]
work = "ccs work"
personal = "ccs personal"
gemini = "ccs gemini"

[agent_chain]
developer = ["ccs/work", "claude"]

Agent Switching / Fallback

Configure fallback agents for automatic switching when primary agent fails:

[agent_chain]
developer = ["claude", "codex", "goose"]
reviewer = ["codex", "claude"]
max_retries = 3
retry_delay_ms = 1000

Example TOML Configuration

[agents.myagent]
cmd = "my-ai-tool run"
output_flag = "--json-stream"
yolo_flag = "--auto-fix"
verbose_flag = "--verbose"
can_commit = true
json_parser = "claude"  # Use Claude's JSON parser

Re-exports

pub use fallback::AgentRole;

Modules

fallback

Fallback chain configuration for agent fault tolerance.

opencode_api

OpenCode API catalog module.

validation

Startup validation for OpenCode agent references.

Structs

AgentConfig

Agent capabilities.

AgentRegistry

Agent registry with CCS alias and OpenCode dynamic provider/model support.

AgentsConfigFile

Root TOML configuration structure.

ConfigSource

Config source for tracking where config was loaded from.

Enums

AgentErrorKind

Error classification for agent failures.

ConfigInitResult

Result of checking/initializing the agents config file.

JsonParserType

JSON parser type for agent output.

OpenCodeProviderType

OpenCode provider type extracted from model flag.

Traits

RetryTimerProvider

Provider for sleep operations in retry logic.

Functions

auth_failure_advice

Get provider-specific authentication failure advice based on model flag.

contains_glm_model

Check if a string contains a GLM-like model name.

global_agents_config_path

Get the global agents.toml path.

is_ccs_ref

Check if an agent name is a CCS reference.

is_glm_like_agent

Check if an agent is a CCS/Claude-based agent using a GLM-like model.

strip_model_flag_prefix

Strip a leading model-flag prefix and return the raw provider/model string.

validate_model_flag

Validate a model flag and return provider-specific warnings if any issues detected.