Facade CodeConfiguration reference
Look up the fields in facade.json, their defaults, and how Facade applies them.
Top-level fields
Open the file through Agent settings. It accepts JSON comments and trailing commas. An empty object uses the defaults.
| Field | Value | Default |
|---|---|---|
yolo | Boolean controlling CLI approvals and agent access. | true |
names | List of nonblank suggested agent names. | Built-in name list |
clis | Object containing built-in overrides and additional named entries. | {}; built-in CLIs remain available |
$schema | String for editor schema metadata. | Omitted |
CLI entry fields
| Field | Value | Default |
|---|---|---|
type | claude, codex, agy, muse, opencode, pi, or custom. | Implicit for exact built-in IDs; required for added entries. |
command | One executable name or path. | Type’s command on PATH; required for custom. |
args | Array of literal argument strings. | [] |
env | Variable names mapped to strings or null. | {} |
model | Nonblank model ID. | CLI decides. Not accepted for OpenCode or custom. |
effort | Nonblank effort supported by the CLI and model. | CLI decides. Not accepted for OpenCode or custom. |
enabled | Boolean controlling future starts and restoration. | true |
icon | Built-in CLI ID or supported robot icon. | Type’s icon; facade-pearl for custom. |
Use the exact lowercase ID to configure a built-in entry, such as codex. A new entry must have a name distinct from every built-in ID and display name, even when capitalization is ignored. For example, use Codex · work rather than Codex. Added entries do not inherit settings from the built-in of their type.
enabled: false hides a valid entry and refuses future starts or restoration. It does not stop an agent already running.
Environment values
{
"clis": {
"codex": {
"env": {
"WORK_API_KEY": "${env:WORK_API_KEY}",
"OLD_TOKEN": null
}
}
}
}- A string sets a variable.
nullremoves it. An omitted variable is inherited. ${env:NAME}reads the editor host’s environment. It does not read another key in the same object.- A missing reference makes that entry unavailable. References expand once in
envvalues, not inargs. - A literal value stays in facade.json. An environment reference keeps that value out of the file, but the CLI still receives the expanded value.
Setting a variable in an integrated terminal that is already open does not update the editor host’s environment. Make it available before starting the editor.
Precedence and launch options
Facade first uses any model and effort specified for the new agent, then the entry’s defaults. If neither provides a value, the CLI decides. OpenCode keeps both choices in its own configuration.
For built-in types, use the dedicated fields for model and effort. Facade also sets permissions, conversation IDs, working folders, and its own tools. It rejects arguments that conflict with these choices or prevent an interactive session from starting.
Facade looks for facade.json in the Facade home: the Facade: Home VS Code setting if set, then FACADE_HOME, then ~/.facade. Open Settings from the project to find its active file.
File errors and entry errors
A file-level error, such as invalid JSON, a duplicate key, or an unknown top-level field, blocks new starts and restoration. An error inside one CLI entry makes only that entry unavailable. Running agents keep running.
Follow the error’s setting path and correct that value. Facade does not silently substitute old settings. See Troubleshooting for common startup and provider errors.