Configuration

The daemon reads ~/.refract/config.toml. Set REFRACT_HOME to use another state directory. config.v3.toml is a complete example covering every key.

The file must set schema_version = 1 at the top level. A missing schema_version or an unknown key stops the daemon with config_invalid, a loc, and a fix hint. An unknown retry.codes value fails at its loc.

The daemon reloads targets and profiles on the next tool call after the file changes. A [daemon] host or port change needs a restart.

[daemon]

Key Default Meaning
default_profile required Profile used when submit names none
host "127.0.0.1" Bind address
port 8765 Bind port
max_jobs 4 Jobs running at once across all projects
breaker_failure_threshold 3 Consecutive failures before a target’s circuit opens
breaker_base_cooldown_s 60 First cooldown for an open circuit
breaker_max_cooldown_s 900 Cooldown ceiling
ask_timeout_s 300 How long refract ask waits for an answer

[logging] and [notifications]

[logging] accepts level, file, max_bytes, and backup_count. file defaults to refract.log under the state directory; set it to false to log to stderr. [notifications].enabled = true sends a desktop notification when a job finishes.

[[targets]]

A target is one worker CLI with fixed settings. id and backend are required. backend is one of codex, claude, pi, or agy.

Key Meaning
model Model passed to the CLI
reasoning Reasoning level, translated per backend
backend_profile Codex configuration profile
system_prompt System prompt for pi and claude
args Extra CLI options, one token per array item
max_concurrency Jobs this target runs at once; default 1
retry { attempts, codes, patterns }: retry a matching failure on the same target. A policy without codes or patterns retries nothing.
env Environment variables for the worker process

Important: Put credentials in each CLI’s own login or in env. Every target setting except env is copied into job records.

The Backends page lists the flags each backend accepts and which ones the coding_agent_cli library or Refract owns.

Retry Codes

retry.codes matches the error_code of a retryable failure. The codes come from the coding_agent_cli library. The outcome column shows how Refract treats each code.

Code Outcome Meaning
timeout Retryable The run hit its time limit.
service_error Retryable The provider reported a service error.
execution_error Retryable The CLI failed without a more specific code, such as a nonzero exit.
stdin_failed Retryable Writing the prompt to the CLI standard input failed.
no_output Retryable The CLI produced no assistant text.
context_overflow Retryable, never retried on the same target The prompt exceeded the context window.
bad_cwd Request fatal The working directory is not a directory.
invalid_prompt Request fatal The prompt is not valid UTF-8 or contains a NUL byte.
invalid_args Target fatal args conflicts with a flag the driver owns.
unsupported_option Target fatal The backend does not support a target field.
invalid_model Target fatal The CLI rejected the model.
missing_cli Target fatal The CLI is not on PATH.
spawn_failed Target fatal The CLI could not start.
auth Target fatal The CLI is not logged in or the credential failed.

A request fatal failure is not retried and does not count toward the circuit breaker. A target fatal failure is not retried and opens the target circuit at once.

retry.patterns match the error text. The library changed some error messages, so re-check any pattern that matched the old text, for example backend command exited with status or The <backend> CLI was not found on PATH.

[profiles.*]

A profile maps the workflows implement, review, consult, and other to targets. A value can be one target id, an ordered list where later ids are fallbacks, or a table with targets and timeout_s. timeout_s limits each attempt in seconds; 0 means no limit.

[profiles.base]
implement = "codex-high-code"
review = ["pi-high-review", "claude-opus-code"]
consult = { targets = ["agy-gemini-consult"], timeout_s = 1800 }

[profiles.claude_impl]
extends = "base"
implement = "claude-opus-code"

extends inherits one parent profile. other never falls back and needs an explicit mapping.

Project overrides

A repository can add .refract/config.toml with its own [profiles.*]. Its [[targets]] entries may only add env to global targets, matched by id.

A task_guide.json in .refract/ or the state directory is returned as guidance from list. See task_guide.json.example.

Environment variables

Variable Effect
REFRACT_HOME State directory; default ~/.refract
REFRACT_URL MCP endpoint the plugin connects to
REFRACT_LOG_LEVEL, REFRACT_LOG_FILE Override logging level and path
REFRACT_LOG_MAX_BYTES, REFRACT_LOG_BACKUP_COUNT Override log rotation
REFRACT_DISABLE Plugin ignores Refract for the session
REFRACT_NO_UPDATE_CHECK Plugin skips the update notice and background check

Source: server/README.md