Configuration

Brainstorm uses a layered configuration system where each layer overrides the previous one. This lets you set personal defaults globally while customizing behavior per project.

Configuration Layers

Configuration is resolved in this order (last wins):

1. Built-in defaults -- Sensible defaults for all settings

2. Global config -- ~/.brainstorm/config.toml -- your personal preferences

3. Project config -- ./brainstorm.toml -- per-project settings checked into the repo

4. Environment variables -- BRAINSTORM_* env vars for CI/CD and ephemeral overrides

Global Config

Located at ~/.brainstorm/config.toml. Create it manually or run storm init.

``toml

[routing]

strategy = "combined"

quality_weight = 0.7

cost_weight = 0.3

default_model = "claude-opus-4-6"

[providers.anthropic]

enabled = true

[providers.openai]

enabled = true

[providers.google]

enabled = true

[budget]

monthly_limit = 50.00

session_warning = 5.00

currency = "USD"

[tools]

sandbox = "restricted" # "restricted", "docker", or "none"

confirm_writes = true

[tui]

theme = "default"

show_cost = true

show_tokens = false

`

Project Config

Located at ./brainstorm.toml in your project root. Commit this to your repo so all contributors share the same settings.

`toml

[project]

name = "my-app"

description = "A Next.js application with Python backend"

[routing]

strategy = "quality" # override global strategy for this project

[agents.default]

model = "claude-opus-4-6"

[context]

include = ["src/", "docs/"]

exclude = ["node_modules/", "dist/", ".next/**"]

`

BRAINSTORM.md

The BRAINSTORM.md file provides natural language context about your project. Unlike TOML config, this is free-form markdown that helps Brainstorm understand your codebase conventions, architecture, and preferences.

BRAINSTORM.md files are hierarchical:

• ~/.brainstorm/BRAINSTORM.md -- global context (your coding style, preferences)
• ./BRAINSTORM.md -- repo root context (project architecture, conventions)
• ./src/BRAINSTORM.md -- subdirectory context (module-specific details)

All matching files are merged into the system prompt, with more specific files taking priority.

Environment Variables

Every config key can be overridden with an environment variable using the BRAINSTORM_ prefix and double underscores for nesting:

`bash

BRAINSTORM_ROUTING__STRATEGY=cost storm run "Generate docs"

BRAINSTORM_BUDGET__MONTHLY_LIMIT=100 storm chat

BRAINSTORM_TOOLS__SANDBOX=docker storm run --unattended "Run migrations"

`

Viewing Active Config

See the fully merged configuration:

`bash

storm config # display merged config

storm config --raw # show each layer separately

storm config --edit # open global config in $EDITOR

``

Config Validation

All configuration is validated with Zod schemas at load time. Invalid values produce clear error messages pointing to the exact field and expected type.