Configuration
Use /settings to change your preferences in fx, or fx config set from a terminal or script:
fx config set fast_mode onfx config set saves a preference in ~/.fx/settings.json for every workspace and prints where it went; fx config unset removes it. Both also remove an older copy of the key from workspace entries, so the change takes effect everywhere. Switches take true or false (on and off work too). Permission, model, provider, and account settings keep their own commands, such as /permissions, /model, fx provider, and fx login. Edit ~/.fx/settings.json for the rest, such as review_model, first_call_tool_choice, provider_order, and context_limits, and .fx.json for shared project defaults. When fx config refuses a key, it says what to use instead.
Files and precedence
| File | Purpose |
|---|---|
~/.fx/settings.json | Personal settings and workspace overrides. |
<workspace>/.fx.json | Shared project defaults. |
MCP servers use separate files: ~/.fx/mcp.json and <workspace>/.mcp.json.
To keep a separate profile, set FX_HOME to an absolute path. fx then uses that folder in place of ~/.fx for settings, sessions, and everything else it stores there, and messages name it $FX_HOME. For example, FX_HOME=/tmp/fx-test fx reads /tmp/fx-test/settings.json. fx status shows the folder in use. fx creates the folder, and any missing folders above it, on first use, and FX_HOME works even when HOME isn't set. It must be a folder, not a file. It can't be / or your home folder itself, because fx keeps its folder private to your user. The OS keychain is shared between profiles.
For each setting, the highest available source wins:
- command-line flag, where supported
- environment variable
fx ask --config key=value, for one request- matching workspace entry in
~/.fx/settings.json - global entry in
~/.fx/settings.json <workspace>/.fx.json- built-in default
Settings files have a 64 KiB limit. fx ignores unknown keys. A value fx can't use, such as text where a setting takes a number, can make fx skip the rest of that file or workspace entry, keeping only its provider and model choices. fx reports the problem at startup. Run fx doctor to list unknown keys, such as a misspelled setting, with the closest known key. It also lists older names, such as statusLine and a saved permission_mode of yolo, which fx still reads until 0.0.18.
If other users can write to ~/.fx or ~/.fx/settings.json, fx removes their write access at startup and loads the settings, with a note asking you to check settings.json if you didn't write it yourself. fx ask and other commands print the same note on stderr. If fx can't change the permissions, such as on a folder you don't own, it skips those settings.
Check settings in your editor
Editors that read JSON Schema, such as VS Code, can complete and check settings files. Add a $schema key to the top of the file:
{
"$schema": "https://fx.sh/schemas/settings.json"
}
Use https://fx.sh/schemas/fx.json in a project .fx.json. The editor then flags unknown keys, wrong types, and values fx doesn't accept, and marks older names as deprecated. fx ignores $schema when it reads the file. fx config schema prints the schema for the installed version, and fx config schema --project prints the one for .fx.json.
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
}
| Field | Description | Type and values | Default |
|---|---|---|---|
max_agent_steps | Maximum agent steps per turn; 0 means unlimited. | Non-negative integer | 0 |
max_tool_result_bytes | Tool output budget in model context; saved results can be larger. | Integer of at least 1024 | 65536 |
context | Load project instructions. | Boolean | true |
provider_order | Preferred AI Gateway providers, in order. | Array of up to 8 provider slugs | No preference |
provider_strict | Restrict Gateway requests to provider_order. | Boolean | false |
Only the fields above apply in .fx.json; fx ignores any other setting there and warns about it. 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
| Field | Description | Values and default |
|---|---|---|
provider | Service used for model requests. | "gateway", "codex", "grok", or a configured connection name. Default: "gateway". |
providers | Named custom model connections. | Object stored only at the top level of the private profile. |
models | Saved model ID for each provider or connection. | Object keyed by provider, such as {"gateway": "moonshotai/kimi-k3"}. |
permission_mode | How fx handles tool calls that need permission. | "ask", "auto", or "full-access"; legacy "yolo" is also accepted. Default: "auto". |
first_call_tool_choice | Tool choice for the first model request of each turn; required vision fallback takes precedence. | "auto" or "none". Default: "auto". |
review_model | AI Gateway reviewer used by Auto mode. | An AI Gateway model ID or "typesafeai/jev". See review models. |
fast_mode | Use faster inference when supported. | Boolean. Default: false. |
ultrafast_mode | Request the higher-priced OpenAI Ultrafast tier for an eligible AI Gateway model. Cannot be set by project .fx.json. | Boolean. Default: false. |
effort | Reasoning effort for the selected model. | "auto" or an effort name supported by the model; null resets to auto. Default: "auto". |
auto_compact_percent | Start automatic compaction at this percentage of usable input capacity. | Integer from 10 to 80. Default: 80. |
tool_placement | Which built-in tools fx sends directly and which it lists in toolbox. Cannot be set by project .fx.json. | Object mapping a tool name to "toolbox" or "direct". Default: install_skill in toolbox, the rest direct. |
cache_warming | Keep a waiting Claude conversation's prompt cache alive through AI Gateway for up to 30 minutes after its last request. | Boolean. Default: true. |
For context_limits, see Context limits. For permission rules, see Permissions. For skill_symlink_authorities, see Skills.
Interface and update settings
| Field | Description | Values and default |
|---|---|---|
slash_menu_categories | Show command categories and skill sources in search results. | Boolean. Default: true. |
auto_upgrade | Download and install updates in the background; press ctrl+g to reload. | Boolean. Default: true. |
update_channel | Release channel used for updates. | "stable" or "dev". Default: "stable". |
startup_scrollback | Restore terminal output at startup. | Boolean. Default: true. |
collapse_tool_calls | Show a summary for each tool-call group. | Boolean. Default: false. |
session_titles | Generate a title from the first prompt. | Boolean. Default: true. |
theme | Built-in or custom terminal theme. | "light", "dark", or the name of a file in ~/.fx/themes/, without .json. Default: follows the terminal. |
prompt_history.enabled | Save prompts and slash commands for input history. | Boolean. Default: true. |
status_line.context | Show context usage in the footer. | Boolean. Default: false. |
status_line.session | Show the session title in the footer. | Boolean. Default: false. |
status_line.workspace | Show the workspace path and Git branch. | Boolean. Default: false. |
sound.turn_end | Play a sound when a turn finishes. | Boolean. Default: true on macOS, false elsewhere. |
sound.attention_required | Play a sound when fx needs your attention. | Boolean. Default: true on macOS, false elsewhere. |
sound.max | Enable extra interaction sounds when sound is on. | Boolean. Default: false. |
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/. See Themes for the file format, VS Code themes, and troubleshooting.
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 here, along with keys it reads only inside a workspace entry: additional_directories, which fx workspace manages for additional directories, and the project MCP server approvals enabledMcpjsonServers, disabledMcpjsonServers, and enableAllProjectMcpServers, which fx mcp approve and fx mcp reject manage. Custom connection definitions (providers) and $schema 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:
FX_MAX_AGENT_STEPS=20 fx| Variable | Description |
|---|---|
AI_GATEWAY_API_KEY | Authenticate with a Vercel AI Gateway API key. |
VERCEL_OIDC_TOKEN | Authenticate in a Vercel-managed environment. |
FX_PROVIDER | Select a built-in provider or custom connection for this process. |
FX_MODEL | Override the model for this process. |
FX_ULTRAFAST | Request Ultrafast with 1, true, on, or yes; disable with 0, false, off, or no. Values are trimmed and case-insensitive; invalid values fail startup. CLI flags take precedence. |
FX_REVIEW_MODEL | Override the AI Gateway permission reviewer for this process. |
TYPESAFE_API_KEY | Call TypeSafe directly when the review model is typesafeai/jev. |
FX_PROVIDER_ORDER | Set comma-separated AI Gateway provider slugs in preference order. |
FX_PROVIDER_STRICT | Restrict Gateway routing to the configured provider order with 1, true, on, or yes; lift the restriction with 0, false, off, or no. |
FX_PERMISSION_MODE | Override with ask, auto, or full-access; legacy yolo is also accepted. |
FX_MAX_AGENT_STEPS | Override the agent step limit. |
FX_AUTO_COMPACT_PERCENT | Override auto_compact_percent with a whole number from 10 to 80; other values are ignored. |
FX_THEME | Select light, dark, or a custom theme for this process. |
FX_SOUND | Override all three sound settings: off, 0, or false turns every sound off, max turns every sound on, and another value, such as on, turns on the turn-end and attention sounds. |
FX_AUTO_UPGRADE=0 | Disable automatic upgrades for the process; false works too. |
FX_NO_OPEN_BROWSER=1 | Print authentication URLs instead of opening a browser. |
FX_HOME | Use this absolute folder in place of ~/.fx for settings, sessions, and other state. |
NO_COLOR | Set to any non-empty value to turn color off in help, fx ask, and the interactive session. The interactive session keeps bold, dim, and reverse text; help prints no styling at all. |
TERM=dumb | Turn color off in help and fx ask. The interactive session needs cursor movement, so fx exits and suggests fx ask instead. |
Diagnostics
Use these controls when investigating a problem:
| Variable | Description |
|---|---|
FX_DEBUG_RECORD=1 | Write an automatic private terminal recording under ~/.fx/recordings/. |
FX_DEBUG_RECORD_SILENT_BANNER=1 | Hide the recording notice from the inline transcript while keeping it in Ctrl-O. |
FX_RECORD | Write a terminal recording to an explicit path. |
FX_RECORD_INPUT=1 | Include raw terminal input events in a recording. |
FX_TRACE=1 | Write a trace to the default private trace path. |
FX_TRACE_LOG | Write a trace to an explicit path; relative paths resolve from the primary workspace. |
FX_TRACE_SCOPES | Limit traces to an exact comma-separated list of scopes. |
FX_TRACE_STDERR=1 | Write trace lines to stderr, alone or alongside a trace file. |
FX_SYNC_UPDATES | Set on or off to troubleshoot terminal synchronized updates. |
FX_DISABLE_KEYCHAIN=1 | Disable the native macOS API-key store; fx login vercel --api-key cannot save a key while set. |
FX_HERDR=0 | Disable automatic Herdr lifecycle reporting. |
Environment and command-line overrides affect only the current process and are not written back to settings.
Herdr integration
When launched inside Herdr, fx names its pane fx and reports whether it is idle, working, or waiting for input. A waiting report says why: a permission request, a question, or a request only you can continue, such as one that ran out of credits. With several instances open, it reports the busiest one: waiting for input over working, and working over idle. Herdr supplies the local socket and pane ID through HERDR_SOCKET_PATH and HERDR_PANE_ID. Reports include the session state and session ID, but no prompts or tool output. If Herdr doesn't answer, fx keeps running without the reports. Set FX_HERDR=0 or FX_HERDR=false to disable reporting.
Check which settings fx is using
Show the settings in effect for this run:
fx statusfx status --jsonUse fx permissions --json for the resolved permission rules and fx workspace --json for active additional directories.
To see what each settings file sets, list the values in order from lowest to highest precedence:
fx config list --show-originEach line starts with where the value comes from, then key=value, with nested keys in dotted form such as status_line.context. Values from a settings file or workspace entry come first. A set environment variable that overrides a setting comes last, as env:FX_MAX_AGENT_STEPS, because it overrides the files; a value fx ignores isn't listed. When a key appears more than once, the last line is the one fx uses. fx config get <key> prints the value a run uses, including the default when nothing sets it; with --show-origin, it names where that value comes from, or default. If fx rejects or ignores what a file sets, get shows the value fx uses instead and prints the same warning fx status does. Command-line flags can still override it for one run.
Add --global to list or get to read only the global settings in ~/.fx/settings.json, or --workspace to read only this workspace's entry. set and unset don't take --workspace, because they change a preference for every workspace.
Compatibility
fx still reads the older model, codex_model, and grok_model keys. Saving a model moves it under models.
fx saves full access as "permission_mode": "full-access" and still reads the older "yolo" until fx 0.0.18. fx manages yolo_acknowledged, credential_source, and fast_mode_model_bound when you change permissions, sign in, or turn Fast mode on or off.
fx still reads the older statusLine and notifications keys until fx 0.0.18. Saving a status line or sound setting moves them to status_line and sound. If a file sets both spellings, the newer key wins, and fx doctor names the older one to remove. fx config accepts either spelling.
fx no longer supports skill_match_fuzzy. A ~/.fx/settings.json that still sets it is ignored, and fx prints remove skill_match_fuzzy until you delete the key. Skills load only when you invoke them or the agent opens them with toolbox.
fx ignores the retired input_appearance, maxxing_mode, sandbox, and web_fetch_worker_model keys without a warning, and editors mark them as deprecated. You can delete them.
Local state
See Data and privacy for saved conversations, credentials, and other local state.