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.

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 → Engines 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.