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.2.0-dev — CLI local mode. 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
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.

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.