Settings

A lookup-oriented list of every key Friday persists in its user preferences file. For an introduction to how settings work, see Settings.

Where settings live

  • Path: ~/.friday/.user_preferences.yaml. Note the leading dot: this is a hidden file. ls ~/.friday without -a won't show it.
  • Format: YAML. Friday loads it at startup and rewrites it whenever you change a setting through the UI.
  • Override location: set $FRIDAY_HOME to use a different parent directory. Default is ~/.friday. See Environment variables.
  • How to edit:
    • Recommended: run /settings inside Friday and pick the setting from the menu.
    • Manual: edit the YAML file directly. Quit Friday first; a running session can overwrite your edits on its next save.
  • Scope: most keys apply globally. A handful are per-project under working_directory_mappings.

Example

A minimal .user_preferences.yaml:

agent_model: claude-sonnet-4-6
working_style: COLLABORATIVE
approval_mode: FIVE_X
conversation_chime: glass
editor: vscode
prevent_sleep_enabled: true
working_directory_mappings:
  /Users/you/code/my-project:
    base_branch: develop

Top-level keys

agent_model

  • Type: string
  • Default: claude-sonnet-4-6
  • Accepted values: claude-sonnet-4-6, gpt-5.4
  • Effect: model used by Dispatch and worker threads. The code-review subagent uses the opposite provider for an independent cross-provider review.
  • Concept: Agent Model.

working_style

  • Type: string (uppercase enum name)
  • Default: COLLABORATIVE
  • Accepted values: COLLABORATIVE, SUPERVISED, AUTONOMOUS
  • Effect: shapes how the agent communicates. Collaborative asks clarifying questions; Supervised plans then executes; Autonomous keeps going on best judgment. Also controls runtime gates like the accept-thread modal.
  • Concept: Working style.

approval_mode

  • Type: string (uppercase enum name)
  • Default: FIVE_X
  • Accepted values: TWO_X, FIVE_X, TEN_X
  • Effect: how much Friday auto-approves. TWO_X asks before every command. FIVE_X auto-runs bash but asks for git commits/pushes/PRs. TEN_X auto-runs everything.
  • CLI override: friday --2x | --5x | --10x (session-only; doesn't write to the file). Autostart (--prompt) defaults to TEN_X.
  • Concept: Permissions and approval modes.

conversation_chime

  • Type: string
  • Default: off
  • Accepted values: off, glass, ping, funk
  • Effect: plays an audio notification whenever Friday is waiting for your input.
  • Concept: Conversation chime.

prevent_sleep_enabled

  • Type: boolean
  • Default: true
  • Effect: while the agent is processing, Friday calls caffeinate to keep the machine awake. macOS only.
  • Concept: Prevent sleep.

auto_update_enabled

  • Type: boolean
  • Default: false
  • Effect: when on, Friday auto-updates on launch if a new release is available. When off, you update manually with friday --update or the /update command.

post_conversation_review_enabled

  • Type: boolean
  • Default: false
  • Effect: after the agent finishes code modifications, Friday automatically reviews its own diff and removes anything that doesn't directly address the task.
  • Concept: Self review.

editor

  • Type: string
  • Default: vim
  • Effect: the external editor Friday opens for /diff and similar commands. Supplied as a command name.

theme_mode

  • Type: string
  • Default: textual-dark
  • Effect: Textual theme name. UI only.

blocklist

  • Type: dict mapping tool name to list of glob patterns
  • Default: {}
  • Effect: any invocation of the named tool whose argument matches one of these patterns triggers a confirmation prompt regardless of approval mode. Currently scoped per tool; the most common entry is Bash.
  • Example: 
    blocklist:
  Bash:
    - "rm -rf *"
    - "sudo *"
  • Concept: Permissions and approval modes.

enabled_plugins

  • Type: dict mapping plugin id to boolean
  • Default: {}
  • Effect: which plugins are enabled. Keys are <plugin_id>@<marketplace_name>. Set through /plugin-marketplace, not by hand.
  • Concept: Plugins and marketplaces.

mcp_instances

  • Type: dict
  • Default: {}
  • Effect: persisted OAuth state and configuration for each MCP server you've connected. Managed through /mcp; don't edit by hand.
  • Concept: MCP servers.

user_defined_mcp_servers

  • Type: dict
  • Default: {}
  • Effect: MCP server definitions you've added beyond the built-in marketplace entries.
  • Concept: MCP servers.

working_directory_mappings

  • Type: dict keyed by absolute project path
  • Default: {}
  • Effect: holds per-project overrides. Each value is a dict of project-scoped keys (see below).

Sub-keys (under each <absolute-path>):

  • base_branch: string. The branch Friday uses as the PR target and the reference for "what's on this branch" (git log <base>..<current>). Set with /base-branch. Default: whatever Friday detects as the project's default branch.
  • worktree_sync: list of {path, strategy} dicts. Files or directories to copy or symlink into each new worker worktree. See Worktree file sync.
  • mcp: dict mapping MCP server name to an instance label. Picks which MCP instance is active for this project.

Example:

working_directory_mappings:
  /Users/you/code/api:
    base_branch: develop
    worktree_sync:
      - path: .env
        strategy: copy
      - path: node_modules
        strategy: symlink
  /Users/you/code/web:
    base_branch: main

last_known_stable_version, last_known_beta_version

  • Type: string or null
  • Default: null
  • Effect: internal bookkeeping for the update detector. Don't edit by hand.

Settings that are not in this file

  • API keys: not stored here. Friday's proxy auth uses gh auth token, so authenticating with gh auth login is the credential path. See Installation.
  • agents.md: project rules live in the repo, not in user preferences. See agents.md and project rules.
  • CLI flags: --cowboy, --2x, --base-path, --prompt, etc. apply to one session only and don't write to the file. See CLI flags.

Common gotchas

  • The file is hidden: ~/.friday/.user_preferences.yaml. Use ls -a ~/.friday to see it, or open by full path.
  • Enum values are uppercase names, not lowercase values. working_style: COLLABORATIVE, not collaborative. Same for approval_mode. The mapping is EnumMember.name, not EnumMember.value.
  • Paths under working_directory_mappings must be absolute. Relative paths or ~ shorthand won't match.
  • Booleans are YAML booleans (true / false), not strings.
  • Quit Friday before editing by hand. A running session may overwrite your edits on its next save.
  • Unknown or misspelled keys are ignored, not warned about. After a manual edit, confirm via /settings that the change took.

Read next