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.

Deep Linking

Settings can be opened programmatically to a specific section using the acp:open-settings custom event. The event detail supports a section field — every section has a unique ID, so no tab or scope disambiguation is needed.

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
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 _meta attached to every ACP request. 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.

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 (~/.braide/logs/acp.log).

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 ~/.braide directory 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.

Approved Commands

Configure tools and arguments that agents can execute without asking for permission.

Add commands using the format:
- ToolName — Approve all uses of a tool (e.g., Read)
- ToolName(arg) — Approve a specific tool with specific arguments (e.g., Bash(npm test))
Wildcards (*) are supported for flexible matching (e.g., Bash(git * --no-edit))
Use */.braide/*/worktree in a path pattern to limit changes to session worktrees instead of the broader filesystem
Edit commands by double-clicking or clicking the edit icon
Remove commands by clicking the trash icon
Approved commands are scoped to the current project and apply to all sessions within it
Commands are displayed in alphabetical order

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 reclaim disk space. Archived sessions include full git worktrees with installed dependencies and can grow to several gigabytes over time.

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. For full details, see the Archive Retention guide.

Data Storage

Application Settings

Global settings are stored in a single file:

~/.braide/settings.json

This includes theme preference, diff view mode, selected project, enabled agents, registry configuration, and user commands.

Project Settings

Per-project settings are stored alongside the project metadata:

~/.braide/projects/<project-id>/settings.json

This includes approved commands, actions, the selected agent, and agent config options.

Directory Structure

All project data, session data, and worktrees are organized under the ~/.braide/ directory:

~/.braide/
├── settings.json                          # Global app settings
└── projects/
    └── <project-id>/
        ├── settings.json                  # Project settings & preferences
        └── sessions/
            └── <session-id>/
                ├── session.json           # Session metadata (agent, label, worktree path)
                └── worktree/              # Isolated git worktree for this session

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 meta	Global	Per-agent JSON attached as `_meta` on every ACP request
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
Approved commands	Per-project	Commands agents can run without permission
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