Agent settings

1. Open facade.json#

1. Open the Facade panel’s … menu and choose Open Settings. You can also find it in the Command Palette.
2. Under Facade: Home, choose Edit in facade.json. If the remote window opens Settings as JSON, the command opens facade.json directly.
3. Edit the file and save. Facade accepts JSON comments and trailing commas.

The default location is ~/.facade/facade.json. If the file does not exist, Facade creates it with comments, built-in CLI entries, and examples to adapt. Facade does not rewrite an existing file.

2. Change a default#

For example, this sets the default Codex effort to high and removes Pi from New Agent. Add these fields to your existing file, keeping the other entries you use:

{
  "clis": {
    "codex": {
      "effort": "high"
    },
    "pi": {
      "enabled": false
    }
  }
}

Save, then start a new agent. Running agents keep their launch settings; resumed and pinned agents use the current file when they next start.

3. Add another setup#

Use a built-in ID like codex to change that CLI’s defaults, or a new name to add a separate setup:

{
  "clis": {
    "Codex · review": {
      "type": "codex",
      "model": "YOUR_MODEL_ID",
      "effort": "high"
    }
  }
}

Replace YOUR_MODEL_ID with a model supported by your Codex setup. Save, then choose Codex · review in New Agent to use it. The type keeps Codex’s Facade integration, while the name identifies this setup.

The new entry does not inherit settings from codex. Add its own arguments, environment variables, or executable path as needed. To connect another API, follow the Claude Code or Codex guide. See Names and icons to change how it appears.

Use the settings for the right machine#

Local projects that use the same Facade home share its settings. SSH, WSL, and container projects read the file in their own execution environments. Open Settings from the project you want to configure.

The Facade: Home setting in VS Code Settings chooses the folder containing facade.json. An explicit value overrides FACADE_HOME, which otherwise overrides ~/.facade. After changing the home, accept Facade’s prompt to reload the window.

Use Edit in facade.json to reach the active file. For field definitions and defaults, see the configuration reference.