brainjar

brainjar

Shape how your AI thinks.

brainjar composes soul + persona + rules + procedure into prompts for AI agents and emits skills as on-demand capabilities to the platform's skills directory. It's a Go CLI that runs offline against a single local SQLite workspace. No server, no network calls, no account.

Status: pre-1.0. CLI local mode, Claude platform sync (Codex and Cursor sync without skill emit), HTTP API, MCP tool surface, five content primitives, brain bundles. Single-workspace, single-user.

Install

There are no binary releases yet. Build from source:

git clone https://github.com/brainjar-sh/brainjar
cd brainjar
go build -o brainjar ./cmd/brainjar

Or with the included just recipes:

just build   # go build -o brainjar ./cmd/brainjar
just test    # go test ./...
just lint    # golangci-lint run ./...

Requires Go 1.25 or later. Put the resulting brainjar binary on your PATH.

Quick start

brainjar init                                             # create ~/.brainjar; prints one API key — save it
echo "You speak with conviction"          | brainjar soul create straight-shooter
echo "You are the CTO"                    | brainjar persona create cto
echo "Test before merging"                | brainjar rule create testing
echo "1. Design  2. Approve  3. Build"    | brainjar procedure create delivery
brainjar soul use straight-shooter
brainjar persona use cto
brainjar rule add testing
brainjar procedure use delivery
brainjar compose > prompt.txt                             # compose effective state

Content for soul create, persona create, rule create, and procedure create comes from stdin, --content "...", or --file <path> in that precedence.

Save the current soul+persona+rules+procedure (and optional skills) as a reusable brain:

brainjar brain save cto \
  --soul straight-shooter --persona cto --procedure delivery \
  --rule testing \
  --skill incident-response                             # repeatable; or --skills a,b,c
brainjar brain save cto \
  --soul straight-shooter --persona cto \
  --platform claude --model opus                        # pin platform + default model
brainjar compose cto > prompt.txt                       # compose from a brain
brainjar compose --persona architect --task "design the auth layer"

Activate a saved brain on the workspace state in one shot:

brainjar brain use cto                                  # load soul + persona + procedure + rules + skills
brainjar sync                                           # write the composed prompt + emit skill files

Inspect what's active:

brainjar status

Primitives

brainjar splits agent configuration into five content kinds. Four of them compose into the prompt; the fifth (skills) is on-demand and emitted to the platform's skills directory rather than inlined.

A brain is a saved bundle of (soul, persona, rules, optional procedure, skills) you can name and re-activate. State is the live, mutable version of the same shape — what brainjar sync writes to your platform.

Skills

A skill is a Markdown body the platform's runtime loads when the user's task matches its description or triggers. brainjar stores skills in the workspace and writes one <slug>/SKILL.md per resolved skill on brainjar sync. Each skill carries a scope — project skills land under <repo>/.claude/skills/, user skills under ~/.claude/skills/. brainjar drops a .brainjar-managed marker into each emitted directory so prune only removes brainjar-owned skills and leaves hand-authored ones alone.

Skills do not enter the composed prompt — they appear on compose --json as skills reference metadata so callers know what's available, but bodies stay on disk. Today only Claude Code consumes the emitted SKILL files; Codex and Cursor sync warns that skills are unsupported and continues.

Commands

Run brainjar <cmd> --help for flags and examples on any command.

Global flags

Home resolution

The home directory is resolved in this order:

1. --home <dir> flag
2. $BRAINJAR_HOME environment variable
3. ~/.brainjar

It holds config.yaml and brainjar.db (SQLite). Nothing else is written there by brainjar itself.

Agent mode (--json)

Every command supports --json. In JSON mode:

• Success output on stdout is a single JSON document.

• Errors on stderr are a structured envelope:

  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "invalid references",
      "hint": "re-run `brainjar init --force` after backing up",
      "invalid_refs": { "soul_slug": "ghost", "rule_slugs": ["missing"] }
    }
  }
  

  code is one of NOT_FOUND, CONFLICT, BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, INTERNAL. hint and invalid_refs are optional.

• Human warnings (missing slugs during compose, etc.) still go to stderr so they don't pollute a piped prompt.

Server and MCP

brainjar exposes the same content through two surfaces: CLI and MCP. Both share one SQLite workspace.

HTTP server

brainjar serve --port 8080

The server listens at http://127.0.0.1:8080 and exposes one application endpoint — MCP Streamable HTTP at /mcp. Every request needs Authorization: Bearer <key>, where <key> is the plaintext printed once by brainjar init (or by brainjar api-key create for additional keys). The server only stores the SHA-256 hash — lose the plaintext and you revoke and re-mint. /healthz (liveness) and /readyz (DB-reachable readiness) are unauthenticated and intended for container probes.

MCP over stdio

brainjar mcp runs an MCP server on stdio, bound to the same workspace the CLI uses. Register it with your agent the way that agent registers any stdio MCP server. For Claude Code:

claude mcp add brainjar -- brainjar mcp
# or, if you use a non-default workspace:
claude mcp add brainjar -- brainjar --home ~/.brainjar-prod mcp

From that point on, tools like soul_list, persona_save, skill_save, compose, and status show up as MCP tools in your Claude session. The skill surface is skill_list / show / save / delete / attach / detach; brain_save accepts skill_slugs alongside its rule and procedure references.

Shell completions

brainjar completion <shell> prints a completion script for bash, zsh, fish, or powershell. Pipe the output into your shell's completion directory:

# bash (system-wide)
brainjar completion bash | sudo tee /etc/bash_completion.d/brainjar > /dev/null

# zsh (first fpath entry; reload with `exec zsh`)
brainjar completion zsh > "${fpath[1]}/_brainjar"

# fish
brainjar completion fish > ~/.config/fish/completions/brainjar.fish

# PowerShell (dot-source the file in $PROFILE)
brainjar completion powershell > brainjar.ps1

Man pages

brainjar man [dir] writes nroff(1) man pages for every subcommand into dir (default ./man). Packagers typically install them under $prefix/share/man/man1/:

brainjar man /usr/local/share/man/man1
man brainjar-shell

Exit codes

Exit codes are a stable contract — safe for scripts and CI:

License

MIT — see LICENSE.