Agent Configuration

autospec supports multiple CLI-based AI coding agents through a unified agent abstraction layer. This allows you to use your preferred agent while maintaining compatibility with the same workflow commands.

Supported Agents

Currently Supported

Agent	Binary	Description	Status
`claude`	`claude`	Anthropic’s Claude Code CLI (default)	✅ Supported; smoke-tested with 2.1.281
`codex`	`codex`	OpenAI Codex CLI	✅ Supported; smoke-tested with 0.155.1
`opencode`	`opencode`	OpenCode AI coding CLI	✅ Supported; smoke-tested with 1.18.31
`jcode`	`jcode`	Official Jcode CLI	✅ Supported; SDK integration remains an explicit opt-in

Experimental Agents (Untested)

Agent	Binary	Description	Status
`cline`	`cline`	Cline VSCode extension CLI	⚠️ Untested
`gemini`	`gemini`	Google Gemini CLI	⚠️ Untested
`goose`	`goose`	Goose AI CLI	⚠️ Untested

These agents have code-level support (agent abstraction, command building, doctor checks) but have not been tested with real binaries. They may require adjustments. Please report issues if you try them.

Custom Agents

You can configure any CLI tool as an agent using a command template with `` placeholder.

Configuration

jcode runner selection

The production default uses the installed CLI:

jcode --quiet --no-update --no-selfdev --model <model> run "<rendered prompt>"

Autospec follows the wrapper contract published by the official 1jehuang/jcode project. Global flags are placed before run, and one rendered prompt is passed positionally. Reasoning effort and arbitrary workflow extra arguments are not forwarded by exec mode.

Set jcode.runner: custom with jcode.binary for a custom executable. The default exec runner always resolves the official jcode command from PATH. Set jcode.runner: sdk explicitly to use the native SDK and its lifecycle policy. An omitted runner always resolves to the CLI-compatible exec runner, even when SDK lifecycle fields are present.

Native jcode SDK

Select jcode with agent_preset: jcode. The native SDK integration is a custom compatibility path and is disabled unless jcode.runner: sdk is set. It uses owned SDK turns so event subscription begins before the prompt is sent, and it does not reconnect in the middle of an active turn.

agent_preset: jcode
jcode:
  runner: sdk
  mode: connect                 # connect, private, or auto
  socket_path: ""               # optional existing runtime socket
  binary: ""                    # private mode: jcode executable
  home: ""                      # private mode: persistent home, or temporary
  session_profile: bounded       # experimental SDK session profile
  max_turns: 8                   # positive whole number; 0 or omitted = unset
  token_budget: 16000            # positive whole number; 0 or omitted = unset
  deadline: "2026-08-23T10:00:00+02:00" # RFC3339 with explicit offset
  inherit_logins: false
  startup_timeout: 30s
  cleanup_timeout: 30s
  startup_command: ""          # private/auto only
  reconnect_attempts: 2
  restart_attempts: 1
  retry_delay: 250ms

Exec mode also supports stable upstream wrapper settings:

agent_preset: jcode
model: gpt-6-sol
jcode:
  runner: exec
  provider: openai
  provider_profile: ""
  socket_path: ""
  trace: false
  tool_profile: minimal
  tools: bash,read
  disabled_tools: write
  disable_base_tools: false
  mcp_tools: auto          # auto, eager, or deferred
  mcp_tools_token_threshold: 4096

connect attaches to a runtime started separately with jcode api-bridge. private starts an isolated runtime owned by autospec and cleans up SDK-owned temporary state when the execution ends. Keep login inheritance disabled for untrusted or multi-tenant work. auto tries the shared bridge first and falls back to an SDK-owned private runtime when the shared bridge is absent.

The four session controls above are experimental and are transferred only when jcode.runner: sdk is selected explicitly. session_profile maps to CreateSessionOptions.Profile; max_turns, token_budget, and deadline map to the corresponding typed SendOptions fields. Each control may be used by itself, or all four may be combined as shown. Omitting a control preserves the SDK zero value and introduces no implicit profile or limit.

Stand-alone examples are session_profile: bounded, max_turns: 8, token_budget: 16000, and deadline: "2026-08-23T08:00:00Z", each under a jcode block that explicitly sets runner: sdk.

Limits must be positive whole numbers when nonzero. Deadlines must be RFC3339 timestamps ending in Z or a signed numeric offset such as +02:00 or -07:00. For example, this sets only a UTC deadline:

jcode:
  runner: sdk
  deadline: "2026-08-23T08:00:00Z"

Blank profiles, negative limits, malformed timestamps, and offset-free values such as 2026-08-23T08:00:00 are rejected. A syntactically valid deadline in the past, such as 2020-01-01T00:00:00Z, remains configuration-valid; the SDK owns its execution-time behavior and Autospec preserves the SDK error with operation context.

These controls never change the default runner. The exec and custom runners do not interpret or emit them, and official exec argv remains unchanged. Autospec does not add credentials, authentication settings, max-tool-steps, or arbitrary extra arguments through this experimental contract.

Recovery is bounded. reconnect_attempts applies only to a shared bridge and restart_attempts applies only to a private runtime started by this run. The optional startup_command is private/auto-only and is never used to manage a pre-existing shared daemon. Connect mode never starts, restarts, stops, or cleans up the shared runtime. If recovery is exhausted, diagnostics include the policy, observed state, attempt counts, and a next action.

Using a Preset Agent

Set the agent_preset field in your configuration file:

# .autospec/config.yml
agent_preset: claude

Or in user-level config:

# ~/.config/autospec/config.yml
agent_preset: gemini

Using a Custom Agent Command

For agents not built-in, or for custom configurations:

# .autospec/config.yml
custom_agent_cmd: "my-agent run --prompt  --mode headless"

The `` placeholder is replaced with the actual prompt at execution time. The placeholder can appear anywhere in the command template.

CLI Flag Override

Override the configured agent for a single command execution:

# Use gemini for this run only
autospec run -a "Add user auth" --agent gemini

# Use codex for a full run
autospec run -a --agent codex "Add user auth"

# Use cline for implementation
autospec implement --agent cline

Available for all workflow commands: run, prep, specify, plan, tasks, implement.

Preflight checks follow the effective agent. Claude projects retain the .claude/skills/ requirement, while Codex, jcode, OpenCode, and other agents do not need Claude-specific directories.

Named Configuration Profiles

Use --profile to load a named YAML overlay without replacing the project’s normal .autospec/config.yml:

autospec run --profile cheap -a "Add a feature"
autospec config show --profile cheap

Profiles are searched in this order and both files may be layered:

~/.config/autospec/profiles/<name>.yml
.autospec/profiles/<name>.yml

The project profile is applied after the user profile. Environment variables are applied after profiles, so AUTOSPEC_* values remain the highest-priority configuration source. Profile names may contain 1-64 letters, numbers, hyphens, and underscores. --profile NAME selects a profile for one command. --config remains available for selecting one explicit config file, but cannot be combined with --profile.

Manage profiles with autospec config profiles and autospec config create NAME [--force].

Each profile is a partial config file: set only the keys it changes. Example profiles, saved as ~/.config/autospec/profiles/<name>.yml:

codex-gpt6.yml: Codex CLI with GPT-6 Astra for specification and planning, Sol for everything else:

agent_preset: codex
model: gpt-6-sol
reasoning_effort: medium
models:
  specify: gpt-6-astra
  plan: gpt-6-astra
reasoning_efforts:
  specify: high
  plan: high

claude-opus.yml: Claude Code with Opus 5.5, and Sonnet 5 for the checklist stage. Claude Code receives the model only; reasoning effort is not passed.

agent_preset: claude
model: claude-opus-5-5
models:
  checklist: claude-sonnet-5

jcode-opus.yml: Opus 5.5 through jcode’s Claude login, medium effort for every stage except planning:

agent_preset: jcode
model: claude:claude-opus-5-5
reasoning_effort: medium
reasoning_efforts:
  plan: high

opencode-opus.yml: OpenCode’s build agent with Opus 5.5:

agent_preset: opencode
opencode_agent: build
model: anthropic/claude-opus-5-5

cheap.yml: GPT-6 Luna through jcode’s OpenRouter provider, with maximum effort for specification and planning:

agent_preset: jcode
model: openrouter:openai/gpt-6-luna
reasoning_effort: xhigh
reasoning_efforts:
  specify: max
  plan: max

Check the merged result before a run with autospec config show --profile NAME.

Credentials are not stored in profiles. Each agent keeps its own login: Claude Code, Codex, and OpenCode use their own authentication, and jcode owns provider selection and credentials, including OpenRouter’s OPENROUTER_API_KEY and the Claude subscription login. Autospec only selects the agent, model, and reasoning effort for each workflow stage.

Configuration Priority

When determining which agent to use, autospec follows this priority order:

CLI flag (--agent): Highest priority, single-command override
custom_agent: Project or user-level custom command configuration
agent_preset: Project or user-level preset name
Default: Falls back to the configured supported default agent

Note: This repository configures agent_preset: jcode as its effective default. In an otherwise empty configuration, autospec retains its historical Claude fallback for compatibility.

Workflow Model Selection

Set a default workflow model with top-level model, or select a different model for any supported stage with models.<stage>:

model: provider/default-model
models:
  constitution: provider/constitution-model
  specify: provider/specify-model
  clarify: provider/clarify-model
  plan: provider/plan-model
  tasks: provider/tasks-model
  checklist: provider/checklist-model
  analyze: provider/analyze-model
  implement: provider/implement-model

For each invocation, model precedence is:

CLI --model override
The current stage’s models.<stage> value
Top-level model
The selected agent’s default

Empty or absent stage values continue to the next level. CLI overrides apply only to that invocation and do not modify persistent configuration.

Model identifiers are opaque: autospec does not validate them against a provider catalog. The effective model is transported through the existing model-selection contract for CLI agents and through native jcode session settings for agent_preset: jcode. Reasoning values follow the same stage precedence and are sent to jcode without Autospec handling provider credentials.

`agent_preset` vs `default_agents`

These two config fields serve different purposes:

Field	Purpose	Used When
`agent_preset`	Selects which agent runs commands	Runtime (every command)
`default_agents`	Pre-selects checkboxes in `autospec init` prompt	Initialization prompt defaults

Example config:

# This agent runs your commands:
agent_preset: opencode

# These are remembered selections for next `autospec init`:
default_agents:
  - claude
  - opencode

If agent_preset is empty, claude is used regardless of what’s in default_agents. Interactive autospec init sets agent_preset automatically when one agent is selected, or asks which selected agent should be the execution default when multiple agents are selected. Non-interactive autospec init --ai claude,codex,opencode uses the first selected agent as the execution default.

Environment Configuration

Override agent settings via environment variables:

# Set agent preset
export AUTOSPEC_AGENT_PRESET=gemini

# Set custom agent command
export AUTOSPEC_CUSTOM_AGENT_CMD="my-agent --prompt "

Environment variables take precedence over config file values.

Auto-Commit Configuration

When enabled, autospec instructs the agent to update .gitignore, stage appropriate files, and create a conventional commit message after workflow completion.

Configuration

# ~/.config/autospec/config.yml or .autospec/config.yml

# Enable auto-commit
auto_commit: true

# Default: auto-commit disabled
auto_commit: false

Environment Variable

Override via environment:

export AUTOSPEC_AUTO_COMMIT=true   # Enable
export AUTOSPEC_AUTO_COMMIT=false  # Disable

CLI Flags

Override for a single command:

# Enable auto-commit for this run
autospec implement --auto-commit

# Disable auto-commit for this run (overrides config)
autospec implement --no-auto-commit

The flags are mutually exclusive and available on all workflow commands: run, prep, specify, plan, tasks, implement.

What the Agent Does

When auto-commit is enabled, the agent is instructed to:

Update .gitignore: Identify ignorable files (node_modules, pycache, .tmp, build artifacts, IDE files) and add them to .gitignore
Stage files: Stage appropriate files for version control, excluding temporary files and dependencies
Create commit: Create a commit message in conventional commit format: type(scope): description where scope is determined by the files/components changed

Failure Handling

If the auto-commit process fails (e.g., git add fails, .gitignore write fails), the workflow still succeeds (exit 0)
A warning is logged to stderr describing the failure
This ensures that implementation work is never lost due to commit failures

Migration Notice

On the first workflow run after upgrading to a version with auto-commit enabled by default, a one-time notice is displayed explaining the new behavior. This notice is persisted to state and will not be shown again.

Claude Subscription Mode

By default, autospec forces Claude to use your subscription (Pro/Max) instead of API credits. This protects users from accidentally burning API credits when they have ANTHROPIC_API_KEY set in their shell for other purposes.

How It Works

Setting	Behavior
`use_subscription: true` (default)	Forces `ANTHROPIC_API_KEY=""` at execution → uses subscription
`use_subscription: false`	Uses shell’s `ANTHROPIC_API_KEY` → uses API credits

Configuration

# ~/.config/autospec/config.yml or .autospec/config.yml

# Default: use subscription (recommended - no API charges)
use_subscription: true

# Override: use API credits instead
use_subscription: false

Cost Display Note

When using subscription mode (use_subscription: true), Claude Code still displays cost information in its output:

Cost: $0.5014
Tokens: in=2 out=4558 cache_read=284417

This cost is informational only — it shows what the tokens would cost at API rates, but you are not actually charged this amount. With a subscription (Pro/Max), you pay a flat monthly fee and token usage counts against rate limits, not billing.

Using API Mode

If you specifically want to use API billing:

Set use_subscription: false in your config
Ensure ANTHROPIC_API_KEY is set in your shell environment

# Enable API mode
use_subscription: false

Or with a custom agent:

custom_agent:
  command: claude
  args: ["-p", ""]
  env:
    ANTHROPIC_API_KEY: "sk-ant-..."  # Explicit API key

Agent Requirements

Each agent has specific requirements:

Agent	Binary in PATH	Environment Variables	Status
`claude`	`claude`	- (uses subscription by default)	✅ Supported
`codex`	`codex`	- (ChatGPT login or API auth via Codex CLI)	✅ Supported
`opencode`	`opencode`	-	✅ Supported
`cline`	`cline`	-	⚠️ Untested
`gemini`	`gemini`	`GEMINI_API_KEY`	⚠️ Untested
`goose`	`goose`	-	⚠️ Untested

Use autospec doctor to verify agent availability and configuration.

Checking Agent Status

The autospec doctor command checks the configured agent (agent_preset, Claude when unset), then lists installed agents. Claude projects also check Claude settings; other agents check only their own CLI. A missing configured agent CLI exits 1.

Production builds check supported agents (claude, codex, opencode):

$ autospec doctor

✓ Claude CLI: Claude CLI found
✓ Claude settings: Bash(autospec:*) permission configured

CLI Agents:
  ✓ claude: installed (2.1.281 (Claude Code); tested 2.1.281)
  ✓ codex: installed (codex-cli 0.155.1; tested 0.155.1)
  ✓ opencode: installed (v1.18.31; tested 1.18.31)

Dev builds check all registered agents:

$ autospec doctor

CLI Agents:
  ✓ claude: installed (2.1.281 (Claude Code); tested 2.1.281)
  ○ cline: not found in PATH
  ✓ codex: installed (codex-cli 0.155.1; tested 0.155.1)
  ○ gemini: not found in PATH
  ○ goose: not found in PATH
  ✓ opencode: installed (v1.18.31; tested 1.18.31)

Agent Configuration

There are two ways to configure which agent to use:

Using a Preset

Use agent_preset to select a built-in agent:

# Use the claude agent preset
agent_preset: claude

Using a Custom Agent

Use custom_agent for full control over the command:

# Custom agent configuration
custom_agent:
  command: claude
  args:
    - -p
    - --verbose
    - --output-format
    - stream-json
    - ""

You can also use shell commands for pipelines:

custom_agent:
  command: sh
  args:
    - -c
    - "claude -p  | tee output.log"

Custom Agent Examples

Using a Custom Model with Claude

custom_agent_cmd: "claude --model claude-opus-5-5 "

Piping Output Through a Filter

custom_agent_cmd: "claude -p  | grep -v DEBUG"

Using SSH to Run on Remote Machine

custom_agent_cmd: "ssh build-server 'claude -p '"

Using Docker Container

custom_agent_cmd: "docker run --rm ai-agent run "

Codex Configuration

Codex is a supported agent for autospec’s non-interactive workflows.

Invocation Pattern

autospec sends rendered prompt text to Codex using:

codex exec --json "<rendered autospec prompt>"

Use Codex for one command with:

autospec run -a --agent codex "Add user auth"
autospec implement --agent codex

Authentication

Codex authentication is handled by the Codex CLI itself. autospec does not require OPENAI_API_KEY; Codex can use ChatGPT login or API credentials configured through Codex.

Useful environment variables:

Variable	Purpose
`OPENAI_API_KEY`	Optional API authentication for Codex
`OPENAI_BASE_URL`	Optional API-compatible base URL override
`CODEX_HOME`	Optional Codex home/config directory override

Settings

Codex reads user config from ~/.codex/config.toml. Project-level initialization with autospec init --project --ai codex creates .codex/config.toml as safe project metadata and registers project-local shared skills under .agents/skills/autospec-*/SKILL.md.

Codex supports --sandbox, --ask-for-approval, and --dangerously-bypass-approvals-and-sandbox in codex exec. autospec maps skip_permissions: true to --dangerously-bypass-approvals-and-sandbox.

autospec uses compact Codex output by default. It runs codex exec --json, parses Codex JSONL events, and shows color-coded concise summaries for agent messages, command executions, file changes, and useful reasoning/tool events. Set codex_output.color: false to disable ANSI color, or codex_output.mode: full to restore Codex’s native terminal transcript. Codex can also write the final assistant message with codex exec -o <file>. autospec validates generated autospec artifacts after Codex exits.

Codex and OpenCode do not use autospec command-template directories. Instead, autospec generates shared Agent Skills from each embedded autospec.* prompt. In interactive sessions, use $autospec-specify "Add user auth", $autospec-plan, $autospec-tasks, $autospec-implement, $autospec-constitution, $autospec-clarify, $autospec-checklist, or $autospec-analyze.

See Codex Settings for details.

OpenCode Configuration

OpenCode is a fully supported agent with its own configuration patterns that differ from Claude Code.

Skill Directory Structure

Agent	Directory	Note
Claude	`.claude/skills/autospec.*/SKILL.md`	Claude skills preserve `/autospec.specify`-style invocation
OpenCode	`.agents/skills/autospec-*/SKILL.md`	Shared skills for skill-aware sessions

When you run autospec init --ai opencode, shared skills are installed to .agents/skills/autospec-*/SKILL.md. OpenCode command files under .opencode/command/ are no longer generated.

When you run autospec init --ai claude, skills are installed to .claude/skills/autospec.*/SKILL.md. Legacy .claude/commands/ files still work in Claude Code, but autospec init no longer creates them for Claude.

Invocation Pattern

OpenCode uses a different command invocation pattern than Claude:

Agent	Invocation Pattern
Claude	`claude -p "<rendered autospec prompt>"`
Codex	`codex exec "<rendered autospec prompt>"`
OpenCode	`opencode run "<rendered autospec prompt>"`

Key differences:

OpenCode uses run subcommand (not -p flag)
Non-interactive execution is the default with run

OpenCode Sub-Agent Selection

OpenCode supports specialized agents for different tasks — see the OpenCode Agents documentation for the full list of built-in agents and how to create custom ones. The --opencode-agent flag passes through to OpenCode’s --agent flag.

# Use a specific sub-agent for a workflow
autospec run -a "add login" --opencode-agent build --agent opencode

# Persistent config option
opencode_agent: build

Priority: --opencode-agent CLI flag > opencode_agent config > empty (uses OpenCode’s default).

Available on: run, prep, specify, plan, tasks, implement.

Permission Requirements by Stage

Each sub-agent has different permission defaults. Whether an agent works for a given stage depends on its permissions:

Stage	Permissions Required	Why
`specify`, `plan`, `tasks`, `implement`, `clarify`, `checklist`, `constitution`	`edit: allow`	Writes artifacts (spec.yaml, plan.yaml, tasks.yaml, source code)
All stages	`bash: allow`	Executes autospec commands, git operations, make/build
All stages	`read: allow`	Reads existing code, specs, configs
`implement`, `analyze`	`grep/glob: allow`	Searches codebase during implementation

If you find bash:allow to be too permissive, you can allow narrower bash command patterns instead.

Minimum requirement for workflow stages: edit: allow + bash: allow. OpenCode’s built-in plan agent will not work with workflows that need to create or edit files.

# .autospec/config.yml — recommended for full workflows
agent_preset: opencode
opencode_agent: build

Model Configuration

Autospec workflow commands can pass a model to supported agents when they launch stages. Use the generic --model flag for one run:

autospec plan --agent claude --model claude-opus-5-5
autospec run -a "Add billing exports" --agent codex --model gpt-6-sol --reasoning-effort high
autospec run -a "Add billing exports" --agent opencode --model anthropic/claude-opus-5-5

Persist a default workflow model in autospec config:

agent_preset: codex
model: gpt-6-sol
reasoning_effort: high
reasoning_efforts:
  specify: low
  plan: xhigh
  implement: max

Model selection is scoped to autospec workflow agent execution. It does not rewrite Claude, Codex, or OpenCode’s own global defaults for non-autospec usage.

reasoning_effort, --reasoning-effort, and its -e shorthand apply to Codex and jcode; Claude Code and OpenCode receive only the model. Autospec passes the value through, so new model IDs and effort levels can work without an autospec release.

Stage-specific reasoning_efforts values override the top-level default. A CLI effort overrides every stage for that invocation.

OpenCode also supports multiple AI providers. For the best experience with Anthropic models, use OAuth authentication with your Claude Max/Pro subscription instead of API keys.

Authentication Setup

Run opencode to start the interactive interface
Use /login or /connect command
Select Anthropic from the provider list
Complete browser-based OAuth authentication

This stores credentials in ~/.local/share/opencode/auth.json and allows you to use your Claude Max/Pro subscription without API charges.

Warning: Be careful using ANTHROPIC_API_KEY in your shell environment. API usage can become costly quickly. OAuth authentication with your Max/Pro subscription is recommended for most users.

Configuration Files

OpenCode uses two configuration locations:

Location	Scope	Priority
`~/.config/opencode/opencode.json`	User-level (all projects)	Lower
`opencode.json` (project root)	Project-level	Higher

Project-level settings override user-level settings.

Setting Opus 5.5 as Default Model

Create or update your configuration file:

Project-level (opencode.json in project root):

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-opus-5-5",
  "agent": {
    "build": {
      "model": "anthropic/claude-opus-5-5"
    },
    "plan": {
      "model": "anthropic/claude-opus-5-5"
    }
  }
}

User-level (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-opus-5-5",
  "agent": {
    "build": {
      "model": "anthropic/claude-opus-5-5"
    },
    "plan": {
      "model": "anthropic/claude-opus-5-5"
    }
  }
}

The model format is provider/model-id. For Anthropic OAuth, use anthropic/ prefix.

Available Models

Common Anthropic models:

Model	ID	Notes
Claude Opus 5.5	`anthropic/claude-opus-5-5`	Recommended for workflows
Claude Sonnet 5	`anthropic/claude-sonnet-5`	Faster, lower cost
Claude Haiku 4.5	`anthropic/claude-haiku-4-5`	Lightweight stages

Use /models in OpenCode to list all available models for your authenticated providers.

Permission Configuration

OpenCode uses opencode.json at the project root (not in .opencode/) for permission configuration:

{
  "permission": {
    "bash": {
      "autospec *": "allow"
    }
  }
}

When you run autospec init --ai opencode, this permission is automatically added to allow autospec commands to run without manual approval.

Permission levels:

allow: Command runs without prompting
ask: User is prompted for approval
deny: Command is blocked

Glob patterns: The * in autospec * matches any arguments, so autospec run, autospec update-task, etc. are all allowed.

Using OpenCode as Default Agent

Set OpenCode as your default agent in configuration:

# .autospec/config.yml or ~/.config/autospec/config.yml
agent_preset: opencode

Or via environment variable:

export AUTOSPEC_AGENT_PRESET=opencode

Multi-Agent Initialization

Initialize a project for one or more supported agents:

# Initialize for supported agents
autospec init --ai claude,codex,opencode

# Initialize for Codex only
autospec init --ai codex

# Initialize for OpenCode only
autospec init --ai opencode

# Interactive selection (shows multi-select checklist)
autospec init

Constitution File

OpenCode uses the same constitution file hierarchy as other agents:

AGENTS.md (primary) - Universal agent instructions
OPENCODE.md (fallback) - OpenCode-specific instructions if AGENTS.md is missing
CLAUDE.md (legacy fallback) - For backward compatibility

Command templates reference AGENTS.md as the constitution source. If your project only has CLAUDE.md, consider creating AGENTS.md for multi-agent support.

Agent Capabilities

All agents expose their capabilities through the agent abstraction:

Capability	Description
Automatable	Supports headless/non-interactive execution
Interactive	Supports interactive prompts (not used by autospec)
Streaming	Supports real-time output streaming

Currently, autospec requires automatable agents for all workflow commands.

Troubleshooting

Agent Not Found

If autospec doctor shows an agent as “not found in PATH”:

Verify the agent binary is installed
Ensure the binary is in your system PATH
Try running the agent directly: which claude or claude --version

Missing Environment Variables

Some agents require API keys or configuration:

# For Gemini
export GEMINI_API_KEY=your-api-key

Codex does not require OPENAI_API_KEY; it can use ChatGPT login or API auth managed by the Codex CLI. OPENAI_API_KEY remains optional for API billing.

Custom Agent Template Issues

If your custom agent command isn’t working:

Verify `` placeholder is present in the template
Test the command manually with a simple prompt
Check shell quoting and escaping

# Test custom command manually
my-agent run --prompt "test prompt"

Agent Validation Failed

If agent validation fails, check:

Binary exists and is executable
Required environment variables are set
Agent can run with --version or similar flag

Agent Configuration

Supported Agents

Currently Supported

Experimental Agents (Untested)

Custom Agents

Configuration

jcode runner selection

Native jcode SDK

Using a Preset Agent

Using a Custom Agent Command

CLI Flag Override

Named Configuration Profiles

Configuration Priority

Workflow Model Selection

agent_preset vs default_agents

Environment Configuration

Auto-Commit Configuration

Configuration

Environment Variable

CLI Flags

What the Agent Does

Failure Handling

Migration Notice

Claude Subscription Mode

How It Works

Configuration

Cost Display Note

Using API Mode

Agent Requirements

Checking Agent Status

Agent Configuration

Using a Preset

Using a Custom Agent

Custom Agent Examples

Using a Custom Model with Claude

Piping Output Through a Filter

Using SSH to Run on Remote Machine

Using Docker Container

Codex Configuration

Invocation Pattern

Authentication

Settings

OpenCode Configuration

Skill Directory Structure

Invocation Pattern

OpenCode Sub-Agent Selection

Permission Requirements by Stage

Model Configuration

Authentication Setup

Configuration Files

Setting Opus 5.5 as Default Model

Available Models

Permission Configuration

Using OpenCode as Default Agent

Multi-Agent Initialization

Constitution File

Agent Capabilities

Troubleshooting

Agent Not Found

Missing Environment Variables

Custom Agent Template Issues

Agent Validation Failed

`agent_preset` vs `default_agents`