brainjar

brainjar

Shape how your AI thinks.

brainjar composes soul + persona + rules into prompts for AI agents. It's a Go CLI that runs offline against a single local SQLite workspace. No server, no network calls, no account.

Status: v0.3.0 — CLI local mode, Claude platform sync, HTTP API, MCP tool surface. 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
brainjar soul use straight-shooter
brainjar persona use cto
brainjar rule add testing
brainjar compose > prompt.txt                             # compose effective state

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

Save the current soul+persona+rules as a reusable brain:

brainjar brain save cto
brainjar compose cto > prompt.txt          # compose from a brain
brainjar compose --persona architect --task "design the auth layer"

Inspect what's active:

brainjar status

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, compose, and status show up as MCP tools in your Claude session.

Shell completions

brainjar completion <shell> prints a completion script for bash, zsh, fish, or powershell. For example, to enable completion in zsh:

brainjar completion zsh > "${fpath[1]}/_brainjar"

Exit codes

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

License

MIT — see LICENSE.