Settings & Preferences
Braide provides several layers of configuration — global settings, project-level settings, and UI preferences.
Accessing Settings
Click the gear icon in the top-right corner of the navigation bar to open the Settings modal.
Theme
Use the theme switcher in the top-right corner of the page to switch between:
- Light — Light color scheme
- Dark — Dark color scheme
- System — Follows your operating system preference
Click the icon to cycle through themes, or click the dropdown arrow to select directly.
Settings Modal Layout
The settings modal uses a single sidebar on the left listing every available section. Sections appear under two headings — General Settings first, then Project Settings below a divider when a project is selected. The Fun section appears below a separator at the bottom.
Selecting a project-scoped section requires a project to be selected. When no project is selected, the "Project Settings" divider and its sections are hidden.
Global Settings
Global settings apply across all projects.
ACP Registry
Configure which registries Braide uses to discover agents.
- The default registry is pre-configured and cannot be removed
- Click Add Registry to add a custom registry URL
- Click Set Active to switch which registry is used — only one can be active at a time
- Changing the active registry updates the available agent list
Agents
Manage agent processes from the active registry. See Managing Agents for full details.
- Lists all available agents sorted alphabetically
- Toggle agents on/off to enable or disable them — agents with no compatible build for your platform stay listed but show an Unsupported on this platform pill, with their toggle and settings disabled
- View agent metadata: name, description, authors, version, license, repository, and website
- See real-time status for each agent (idle, starting, running, downloading, error)
- Download progress with percentage is shown during installation
- Upgrade agents when a newer version is available in the registry
- Each enabled agent has a cog icon opening an Additional Settings dialog — a JSON editor for per-agent settings attached to each session the agent runs. Changes are staged until you click the Apply button that appears on the agent card, which restarts the agent without interrupting unrelated sessions. See Managing Agents > Additional Settings.
Commands
Define reusable slash commands that can be invoked from any session's prompt input by typing /command-name. Commands are global — they are available across all projects and sessions.
Each command has two fields:
- Name — A lowercase kebab-case identifier (e.g.,
run-tests,fix-lint). This is what you type after/in the prompt input. - Text — The content that is expanded when the command is used. This can be a short instruction, a detailed prompt template, or any text you want to reuse.
When you type /command-name in a prompt and send it, the /command-name token is stripped from the prompt text and the command's text is sent alongside the prompt as an additional content block. This means the agent receives both your instructions and the expanded command content. Multiple commands can be used in a single prompt.
Commands can also be referenced in action prompts — for example, setting a Commit action's prompt to /commit will expand the commit command's text when the action button is clicked.
To manage commands:
- Click Add to create a new command with a name and text body
- Edit existing commands by clicking the edit icon or double-clicking
- Delete commands by clicking the trash icon
- Duplicate names are not allowed
Secrets
Manage credentials used by Braide for integrations. Currently supports storing a GitHub Personal Access Token for the GitHub integration. The token is stored locally in your Braide settings directory.
Process Manager
Monitor and manage all running processes. This section is primarily a fallback for when normal operation experiences issues — for example, if an agent becomes unresponsive or a terminal session gets stuck. See Managing Agents for more details.
System Dependencies
Braide relies on a small set of external command-line tools that you install on your machine: git for repo detection and worktrees, npx/node for running npm-distributed ACP agents, uvx for uv/PyPI-distributed agents, and gh for GitHub CLI Actions. This panel probes each tool, parses its version, and reports whether it is present and at the required minimum.
Only git is genuinely required — the desktop app ships its own Node runtime (the server runs on Electron's bundled Node), so a system node is needed only to host npx-distributed agents. node, npx, uvx, and gh are therefore optional and gated on the features that use them.
Each row shows a state badge (OK, Outdated, or Missing), the detected version, a short description of what the tool is used for, and — for missing or outdated tools — an Install link to the official download page.
Minimum versions
| Tool | Minimum | Required | Used for | Install |
|---|---|---|---|---|
git | 2.30.0 | Yes | Repo detection, worktrees, branch listing | git-scm.com/downloads |
node | 18.17.0 | No | Hosting npx-distributed agents (Braide runs on Electron's Node) | nodejs.org |
npx | 9.0.0 | No | Spawning ACP agents that ship as npm packages (ships with Node) | nodejs.org |
uvx | 0.3.0 | No | Spawning ACP agents that ship as uv/PyPI packages (ships with uv) | astral.sh/uv |
gh | 2.40.0 | No | GitHub CLI Actions (issue and PR shortcuts) | cli.github.com |
Probes run on first open and the result is cached for the lifetime of the process — re-opening the modal is instant. Click Re-check to re-probe each tool from disk; the panel shows a skeleton while the refresh is in flight.
When an ACP agent spawn fails because one of these tools is missing or not on PATH (typically npx for an npm-distributed agent), the error message on the agent card points back to this panel so you can confirm what's installed and where to get it.
Logging
Configure log verbosity for console and file outputs. Open Settings > Logging to see two independent level pickers:
- Console Log Level — Controls what appears in the terminal (default:
info) - File Log Level — Controls what is written to log files on disk (default:
debug)
Changes take effect immediately when a level is selected. For full details on log levels, areas, output format, and configuration options, see the Logging reference.
Log Viewer
The View Log button on the File Log Level card opens a near-full-screen viewer for browsing the global log file.
- Table columns — Timestamp, Level, Area, Correlation ID, Message, and Update Type
- Lazy loading — The most recent 100 entries load initially; scrolling up loads older entries in batches
- Live tailing — New entries are polled every 2 seconds and appended at the bottom. Auto-scroll follows new entries only when already at the bottom; use Skip to Current to jump back
- Detail expansion — Rows with extra data show an arrow (▶). Click to expand an inline JSON detail panel. A Copy to clipboard button in the top-right corner copies the JSON content. Use Arrow Up / Arrow Down to move between expandable rows; Escape closes the panel
- Column filters — Level, Area, and Update Type use multi-select dropdowns. Correlation ID filters by clicking a value in the table. Message supports case-insensitive substring search. All filters are cumulative; Clear Filters resets them all
- Level colors — Log levels are color-coded for quick scanning: TRACE (gray), DEBUG (secondary), INFO (blue), WARN (golden), ERROR (red), FATAL (dark red)
Application
Configure the home directory used by Braide for storing all data — projects, settings, sessions, and agent data.
- Home Directory (BRAIDE_HOME) — Override the default
~/.braidedirectory by entering a custom path - Leave the field empty to use the default location
- Click Save to apply the new path, or Reset to Default to clear a previously set override
- Changes take effect after restarting the app
This is useful when you want to keep Braide data on a different volume, share configuration across environments, or isolate data for testing purposes.
Fun
Toggle between Work and Life modes, and configure custom word lists for fun mode.
Project Settings
The Project Settings section of the sidebar is only visible when a project is selected.
Overview
A read-only display of the project's basic information:
- Name — The project's display name
- Root Path — The filesystem path the project is linked to
- ID — The internal project identifier
Personas
Define reusable roles that bundle agent preferences, custom instructions, MCP servers, and per-agent config options into a single selectable profile. Personas replace the agent dropdown in the session prompt input — instead of choosing an agent directly, you choose a persona.
Each persona includes:
- Name and optional Description
- Instructions — Custom text prepended to the agent's first prompt in each session
- Preferred Agent (required) — The agent to use when this persona is selected
- Fallback Agents — Alternatives if the preferred agent is offline
- Agent Config Options — Pre-configured settings (e.g., bypass permissions, model) per agent
- MCP Servers — Tool servers passed to the agent at session creation (stdio or http)
When editing a persona, selecting an agent as preferred or fallback triggers a config probe — Braide creates a temporary session with the agent to discover its available configuration options, then displays them as toggles and dropdowns.
For full details on creating and using personas, see the Personas guide.
Actions
Actions are configurable buttons that appear in the session UI, allowing you to trigger agent prompts or terminal commands with a single click. Each action type is defined per-project and supports multiple named actions.
The following action types are available:
| Action Type | UI Location | Description |
|---|---|---|
| Commit | Diff report header | Commits the current changes |
| Merge | Diff report header | Merges session branch into base branch |
| Pull Request | Diff report header | Creates a pull request from the session branch |
| Run | Prompt input toolbar | Runs the application |
| Build | Prompt input toolbar | Builds the application |
| Test | Prompt input toolbar | Runs the test suite |
| Browse | Prompt input toolbar | Opens the application in a web browser |
To add an action:
- Click the + button next to the action type
- Enter a name for the action (e.g., "Dev", "Debug", "Lint")
- Select a mode:
- Terminal — runs the command text in the session terminal
- Agent — sends the prompt text to the active agent
- Enter the prompt or command text
- Click Save
Each type can have multiple actions. When multiple actions exist for a type, use the up/down arrows to reorder them — the first action is the default and is marked with a badge. To remove an action, click the delete icon (×) and confirm.
Action buttons only appear in the session UI when at least one action of that type has been configured. When a type has multiple actions, a split button is shown — the primary button runs the default action, and a dropdown provides access to the alternatives.
Terminal mode actions open the session terminal (if not already open) and execute the command there. Output appears in the terminal pane at the bottom of the session view.
Agent mode actions send the prompt text to the active agent as if you had typed it into the prompt input. The agent's response appears in the session's message stream. Agent-mode prompts support user command expansion — /command-name tokens are resolved before sending.
For more details on where these buttons appear and how they behave, see Running a Session and Actions.
Archive Retention
Configure automatic pruning of archived sessions to permanently delete the session record and its preserved git refs after a retention window. Archiving a session already removes its worktree directory immediately — see Archive & Retention for the full two-tier disk-reclaim story.
- Auto-prune archived sessions — Toggle to enable or disable automatic pruning for this project
- Remove after N days — Sessions older than this are eligible for pruning (minimum 1 day, default 7)
- Prune now — Immediately run the pruning logic instead of waiting for the next hourly sweep
Individual sessions can be protected from pruning by enabling retention protection, regardless of their age. Because archive already removes the worktree, retention protection is now a low-disk way to keep a session recoverable forever. For full details, see the Archive & Retention guide.
Setting Scopes
| Setting | Scope | Description |
|---|---|---|
| Theme | Global | Light, dark, or system |
| Diff view mode | Global | Unified, split, or raw |
| Selected project | Global | Last active project ID |
| Enabled agents | Global | Which agents are toggled on |
| Agent settings | Global | Per-agent JSON passed to each session |
| Registries | Global | List of agent registries |
| User commands | Global | Reusable slash commands available in all sessions |
| Personas | Per-project | Reusable roles with agent preferences, instructions, and MCP servers |
| Actions | Per-project | Configurable buttons for agent prompts or terminal commands |
| Agent config | Per-project | Agent-specific configuration options |
| Archive retention | Per-project | Auto-prune archived sessions after N days |
| Terminal states | Per-session | Terminal open/closed and height |
See the Configuration reference for where these settings are stored on disk and how to override the home directory.
If you ever see a red "Could not load …" toast on startup, your settings or session-meta file has failed to decode and Braide is refusing to overwrite it. See Recovering from a corrupted settings or meta file for the recovery flow.