Configuration

Use /settings to change your preferences in fx. You can also edit ~/.fx/settings.json for personal settings or .fx.json for shared project defaults.

Files and precedence

MCP servers use separate files: ~/.fx/mcp.json and <workspace>/.mcp.json.

For each setting, the highest available source wins:

1. command-line flag, where supported
2. environment variable
3. matching workspace entry in ~/.fx/settings.json
4. global entry in ~/.fx/settings.json
5. <workspace>/.fx.json
6. built-in default

Settings files have a 64 KiB limit. fx ignores unknown keys and reports invalid settings at startup.

Project configuration

Create .fx.json in the directory where you run fx, or add these fields to the existing file:

{
  "max_agent_steps": 40,
  "max_tool_result_bytes": 131072
}

Only the fields above apply in .fx.json. Keep personal settings, including models and permissions, in ~/.fx/settings.json. See Model routing for provider_order and provider_strict.

User profile

Add these fields to ~/.fx/settings.json to collapse tool output and turn off generated conversation titles:

{
  "collapse_tool_calls": true,
  "session_titles": false
}

Restart fx after editing a settings file by hand. The profile also accepts the project settings listed above.

Agent and model settings

For context_limits, see Context limits. For permission rules, see Permissions.

Interface and update settings

Press ctrl+o to see collapsed tool output in Full detail. Automatic titles make a separate model request.

Terminal themes

fx follows the terminal's light or dark mode by default. Set theme to "light", "dark", or the name of a JSON file in ~/.fx/themes/:

{
  "theme": "github-dark"
}

This loads ~/.fx/themes/github-dark.json. fx accepts VS Code color themes and its native theme format. For a native theme, use colors for the interface and syntax for code:

{
  "colors": { "link": "#58A6FF" },
  "syntax": {
    "function": "#D2A8FF",
    "variable": "#FFA657",
    "operator": "#FF7B72"
  }
}

Other syntax slots are keyword, string, number, and comment. Omitted colors keep their defaults. Set "syntax": false to turn syntax highlighting off.

When a named theme ends in -dark or -light, fx uses the matching sibling when the terminal changes appearance, if that file exists.

Workspace entries

To override a setting for one project, add its absolute path under workspaces in ~/.fx/settings.json:

{
  "max_agent_steps": 40,
  "workspaces": {
    "/path/to/project": {
      "max_agent_steps": 80
    }
  }
}

This allows 80 agent steps per turn in that project and 40 elsewhere. Workspace settings override global and project settings.

fx also stores local permission rules and additional directories here. Custom connection definitions (providers) belong at the top level. Model and interface changes made through fx's menus are saved globally.

Environment variables

Environment variables override saved settings for the current process. For example:

Diagnostics

Use these controls when investigating a problem:

Environment and command-line overrides affect only the current process and are not written back to settings.

Herdr integration

When launched inside Herdr, fx reports whether it is idle, working, or waiting for input. Herdr supplies the local socket and pane ID through HERDR_SOCKET_PATH and HERDR_PANE_ID. Reports include session state, but no prompts or tool output. Set FX_HERDR=0 to disable reporting.

Check which settings fx is using

Show the settings in effect for this run:

Use fx permissions --json for the resolved permission rules and fx workspace --json for active additional directories.

Compatibility

fx still reads the older model, codex_model, and grok_model keys. Saving a model moves it under models.

Use "permission_mode": "full-access" for full access. fx still writes this mode as "yolo" in saved settings and JSON output. fx manages yolo_acknowledged and credential_source when you change permissions or sign in.

Local state

See Data and privacy for saved conversations, credentials, and other local state.