Braide manages the full lifecycle of AI agents on your machine. All agent management happens through the Settings panel.
Toggle an agent on to enable it. When enabled:
You'll see progress indicators during download and extraction.
Toggle an agent off to disable it. This stops the agent process and prevents it from starting automatically.
Agents distributed as binary archives expose an Uninstall button beside the version label once the selected version has been downloaded. Uninstall stops the agent (if running) and deletes the entire ~/.braide/agents/<agent>/<version> directory — including the archive, the extracted binary, and any sidecar files produced during install.
Use it when:
After uninstall, toggling the agent back on re-downloads it. Agents distributed via npx or uvx do not have this button — those runtimes manage their own package cache.
Each agent shows a color-coded status:
Each enabled agent card in Settings > Agents has a cog icon beside the on/off toggle that opens the Additional Settings dialog. This dialog lets you attach arbitrary JSON metadata to every protocol request Braide makes to that agent.
The ACP protocol reserves an optional _meta field on every request for client-to-agent extensibility. Braide attaches this metadata to the newSession request only (see Where the Meta Is Sent below). Agents are free to read these values to enable tenant tagging, debug flags, feature toggles, routing hints, tracing IDs, or any other out-of-band context they understand. Implementations that don't recognise a key must ignore it, so setting metadata is safe even for agents that make no use of it.
The dialog shows a single textarea containing a JSON object. Keys and values are entirely agent-specific — consult the agent's documentation for what it expects. The editor provides a few ergonomics to make hand-editing easier:
Invalid JSON is rejected on save with an inline error — the agent is never started with malformed meta. An empty object ({}) is treated as "no meta" and is stored as absent.
Unlike most settings, changing the JSON does not automatically restart the agent. Active sessions would be interrupted by a surprise restart, so the app surfaces the change instead of enacting it.
When the saved JSON differs from the meta the running agent was started with, an Apply button appears on the agent card. Clicking it gracefully stops the agent and starts it again with the new meta. The button hides itself once the restart settles and the running agent's applied meta matches what's on disk. If no agent is running yet, simply enabling the agent is enough — the saved meta is used on first start.
Once applied, the meta is attached as _meta to the newSession request only — whenever the app creates a fresh ACP session, including new sessions, session resets, config probes, and fallbacks after an agent restart. newSession is the natural boundary for session-scoped agent configuration: the agent receives the meta once per session at creation and can propagate it to any internal state it associates with that session.
The meta is not sent on initialize (which is tied to the agent process rather than a session) or on prompt (where repeating it on every turn would be redundant).
The stored meta is per-agent and global: it applies to every session and project that uses that agent. It is persisted in ~/.braide/settings.json under the agentMeta field — see the Configuration reference for the file layout.
Agents are discovered through registries. To manage registries:
Only one registry is active at a time. Changing the active registry updates the available agent list.
The Process Manager section in Settings provides a fallback mechanism for managing processes when normal operation experiences issues — for example, if an agent process becomes unresponsive or a terminal session gets stuck.
It lists all active processes with color-coded badges:
Each entry shows the process label, version (for agents), PID, and the underlying command. You can stop any process directly from this view. The list refreshes automatically every 3 seconds.