Configuration

Most users configure Brainwrite from the app. The packaged desktop validates credentials before saving them and stores supported secrets with the operating system's secure storage.

Simple and Advanced mode

Brainwrite has two modes. Simple mode shows the everyday controls; Advanced mode shows every technical control, such as usage and tokens, the Inspector and other tools for builders.

• A new install starts in Simple mode. An app updated from an earlier version keeps Advanced mode, so nothing you already use disappears.
• Switch with Settings → General → Advanced mode. The choice applies to this device.
• The mode only shows or hides controls. No setting, conversation or server configuration changes when you switch, and nothing is deleted.

In Simple mode:

• Settings is grouped into five pages: General, Appearance, AI, Computers and Account. Usage, Backups, Experimental, Installations and Skills are in Advanced mode only.
• In a chat's header menu, Usage and Inspector are marked In Advanced mode.
• The composer's Where this conversation works chip and the sidebar's Team map are hidden.
• A bot's settings open on a shorter view; see Bot settings.

Appearance

Choose a look under Settings → Appearance → Skin. Meadow is fresh white with a calm green.

Chat width, on the same page, sets how wide messages can grow on this computer: Standard (the usual width), Wide or Full width. Wide and Full width use more of a large window.

Notification feed

Turn on Notification feed in Settings → Appearance to keep a list of what your bots told you. A bell appears on the right edge of the window; it opens Notifications, the last 500 notifications from every bot, newest first, read or not. Filter it by bot, choose Mark all read, or select a notification to open its conversation. The feed is off unless you turn it on, and it is part of the desktop app only.

Shared user profile

Open Settings → General → Profile → About me to save information you want every bot to know, such as your preferences, background, or working hours. It saves automatically and shows Saved when the server confirms the update. The question mark beside the field explains where it is shared.

The text is included in the instructions for subsequent private-chat and group-chat turns, across model providers. Existing bots receive it too; an already running turn keeps the instructions it started with. Clear the field to stop including it in future prompts. Clearing does not erase information already present in conversation history.

This is workspace-wide context, not a private note for a single bot. It is stored in the workspace configuration and sent to the model provider with bot requests. Use credential settings for secrets. The field accepts up to 24,000 characters.

Engine discovery

Brainwrite checks the inherited process path, common install locations, and the login shell. If an engine is installed somewhere unusual, open Settings → Model providers and choose its executable explicitly.

Explicit paths are useful when you:

• keep multiple CLI versions;
• use a wrapper script;
• installed an engine in a directory desktop apps cannot discover; or
• open Brainwrite from Finder or the Dock, which can give it a different environment from your Terminal.

Optional credentials

Local agent chat works without these credentials.

Environment configuration

Source and headless runs can set supported environment variables before starting the harness. The app-level settings are preferable for normal packaged use because they validate inputs and keep secret values out of the renderer.

Per-instance Claude tool scope

Source and headless installations can give separate Claude instances different built-in tool sets in ~/.brainwrite/config.json:

{
  "instances": {
    "claude-browser": {
      "driver": "claudeAgent",
      "config": {
        "tools": ["Read", "WebFetch", "WebSearch"],
        "disallowedTools": ["Bash(git *)", "Edit", "Write"]
      }
    }
  }
}

tools selects Claude's available built-ins; an explicit empty array disables every built-in, while omitting it keeps Claude's default set. disallowedTools applies Claude tool-name patterns as an additional deny list. These settings do not grant or pre-approve MCP integrations, which remain controlled by the instance's mounted integrations and Brainwrite permission flow.

Claude Code isolation

A bot on the Claude engine sees only what its owner gave it: the servers under Connected apps → MCP servers, its integrations (computer, browser, agents, phone), and its own project's .mcp.json. It does not load this machine's Claude Code setup — the MCP servers and claude.ai connectors in your user or local Claude config, your skills and agents, your hooks, or your personal ~/.claude/CLAUDE.md. Loading those into every turn of every bot cost one measured desktop about 407 extra tools and 10k tokens per model call.

If a bot needs one of those servers, add it under Connected apps → MCP servers or to the bot project's .mcp.json, or turn on Also use my Claude Code MCP servers there. See Custom MCP servers.

ACP session reuse

Every ACP engine (Antigravity, Grok, Gemini CLI, Kimi, Droid, Cursor, OpenCode, Qwen, Hermes, custom ACP CLIs) keeps one agent process alive per conversation thread and reuses it across turns, so the ACP handshake — which can take tens of seconds for a heavy runtime like Antigravity — is paid once per thread instead of once per message. The process is closed after 10 minutes of quiet, and sooner on a spawn-contract change (different model flags, working directory, or approval level), a crash, or app shutdown; the next turn then resumes the recorded session over a fresh process. Integration credentials rotate every turn, so a follow-up re-establishes the native session over the wire (session/load) on the same process — the handshake is still paid only once.

An agent that refuses session/load for a session already live in its own process gets exactly one replacement process for that turn: Brainwrite closes the pooled child, starts a fresh one, pays the handshake again, and resumes the recorded session there. The conversation is never traded for a blank session/new; the one-time handshake cost is the price of continuity. Only if the session also fails to load on the replacement process does the turn start a genuinely new session.