Configuration

State cascade

brainjar state merges in three tiers. Each tier overrides the previous:

workspace  →  project  →  env

Workspace state

Stored on the server. Applies to all projects within the workspace.

brainjar persona use engineer        # Sets workspace persona
brainjar rules add security          # Adds to workspace rules

Project state

Stored on the server at project scope. Overrides workspace for that project only. Project scope is auto-detected when your working directory contains a .brainjar/ directory — no --project flag needed.

cd my-project         # has .brainjar/ dir
brainjar persona use planner     # auto-scoped to project
brainjar rules add no-delete     # auto-scoped to project

You can also use --project explicitly to force project scope.

Workspace settings still apply — project only overrides what you specify:

soul     craftsman (workspace)
persona  planner (project)
rules    boundaries (workspace), no-delete (+project)

Environment variables

Override everything for a single session:

Variable	Effect
BRAINJAR_HOME	Override ~/.brainjar/ location
BRAINJAR_SOUL	Override active soul
BRAINJAR_PERSONA	Override active persona
BRAINJAR_RULES_ADD	Comma-separated rules to add
BRAINJAR_RULES_REMOVE	Comma-separated rules to remove

Set to empty string to explicitly unset (e.g., BRAINJAR_SOUL="" removes the soul for that session).

BRAINJAR_PERSONA=reviewer claude

Config file

The CLI config lives at ~/.brainjar/config.yaml and uses named contexts:

version: 2
current_context: local
contexts:
  local:
    url: http://localhost:7742
    mode: local
    bin: ~/.brainjar/bin/brainjar-server
    pid_file: ~/.brainjar/server.pid
    log_file: ~/.brainjar/server.log
    workspace: default
backend: claude

Each context has its own URL, mode, and workspace. See Architecture for details on server modes and contexts.

Backends

brainjar supports multiple agent backends:

brainjar init --backend claude   # Default — writes ~/.claude/CLAUDE.md
brainjar init --backend codex    # Writes ~/.codex/AGENTS.md

Switch backends:

brainjar reset --backend codex

Backup & restore

On first sync, brainjar backs up any existing config to CLAUDE.md.pre-brainjar. Running brainjar reset removes brainjar-managed config and restores the backup.

For a step-by-step guide to decomposing an existing config file into brainjar layers, see Migrating from Monolithic Prompts.