@brainjar/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 brainjar contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,309 @@
+# brainjar
+
+[![CI](https://github.com/brainjar-sh/brainjar-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/brainjar-sh/brainjar-cli/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/brainjar)](https://www.npmjs.com/package/brainjar)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Shape how your AI thinks — identity, soul, persona, rules.
+
+brainjar manages AI agent behavior through composable layers. Instead of one monolithic config file, you separate **what the agent sounds like** (soul), **how it works** (persona), and **what constraints it follows** (rules). Each layer is a markdown file. Mix and match them per project, per task, or per session.
+
+## Quick start
+
+```bash
+# Install
+bun install -g brainjar
+
+# Initialize with starter content
+brainjar init --default
+
+# See what's active
+brainjar status
+```
+
+That gives you a soul (craftsman), a persona (engineer), and rules (boundaries, git discipline, security) — all wired into your `CLAUDE.md` and ready to go.
+
+## Concepts
+
+brainjar has four core concepts. Understanding these makes everything else click.
+
+### Soul — who the agent is
+
+The soul defines personality: tone, character, standards. It's the constant across all tasks. You probably only have one or two. Think of it as the agent's voice.
+
+### Persona — how the agent works
+
+Personas define role and workflow. An engineer persona works differently than a reviewer or an architect. Switch personas based on what you're doing — they're the agent's job description.
+
+Personas bundle their own rules via frontmatter:
+
+```yaml
+---
+rules:
+  - default
+  - security
+---
+```
+
+### Rules — what the agent must follow
+
+Rules are behavioral constraints — guardrails that apply regardless of persona. Single files or multi-file packs (directories). Rules from a persona's frontmatter activate automatically when that persona is active.
+
+### Brain — a saved configuration
+
+A brain is a named snapshot of soul + persona + rules. Instead of switching three things separately, save your setup once and activate it in one shot. Useful for repeatable workflows like "code review" or "design session."
+
+### How they compose
+
+```
+soul + persona + rules = full agent behavior
+      │                    │
+      └── bundled rules ───┘  (from persona frontmatter)
+```
+
+A brain captures all three layers. `compose` assembles them into a single prompt for subagent dispatch.
+
+## State cascade
+
+State merges in three tiers. Each tier overrides the previous:
+
+```
+global  →  local  →  env
+```
+
+| Tier | Storage | When to use |
+|------|---------|-------------|
+| **Global** | `~/.brainjar/state.yaml` | Default behavior across all projects |
+| **Local** | `.brainjar/state.yaml` (in project) | Per-project overrides |
+| **Env** | `BRAINJAR_*` environment variables | Per-session or CI overrides |
+
+```bash
+# Global (default for all projects)
+brainjar persona use engineer
+
+# Local (this project only)
+brainjar persona use planner --local
+
+# Env (this session only)
+BRAINJAR_PERSONA=reviewer claude
+
+# Or use a subshell for scoped sessions
+brainjar shell --persona reviewer --rules-add security
+```
+
+`brainjar status` shows where each setting comes from:
+
+```
+soul     craftsman (global)
+persona  planner (local)
+rules    default (global), security (+local)
+```
+
+### Scope annotations
+
+When you see scope labels in `status` and `rules list` output:
+
+| Label | Meaning |
+|-------|---------|
+| `(global)` | Set in `~/.brainjar/state.yaml` |
+| `(local)` | Overridden in `.brainjar/state.yaml` |
+| `(+local)` | Added by local override (not in global) |
+| `(-local)` | Removed by local override (active globally, suppressed here) |
+| `(env)` | Overridden by `BRAINJAR_*` env var |
+| `(+env)` | Added by env var |
+| `(-env)` | Removed by env var |
+
+### Environment variables
+
+These env vars override all other state when set:
+
+| Variable | Effect |
+|----------|--------|
+| `BRAINJAR_HOME` | Override `~/.brainjar/` location |
+| `BRAINJAR_SOUL` | Override active soul |
+| `BRAINJAR_PERSONA` | Override active persona |
+| `BRAINJAR_IDENTITY` | Override active identity |
+| `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).
+
+## What it does
+
+```
+~/.brainjar/
+  souls/            # Voice and character — who the agent is
+    craftsman.md
+  personas/         # Role and workflow — how the agent works
+    engineer.md
+    planner.md
+    reviewer.md
+  rules/            # Constraints — what the agent must follow
+    default/        # Boundaries, context recovery, task completion
+    git-discipline.md
+    security.md
+  brains/           # Full-stack snapshots — soul + persona + rules
+    review.yaml
+```
+
+brainjar reads these markdown files, merges the active layers, and inlines them into your agent's config (`~/.claude/CLAUDE.md` or `.codex/AGENTS.md`) between `<!-- brainjar:start -->` / `<!-- brainjar:end -->` markers. Everything outside the markers is yours. Change a layer, and the agent's behavior changes on next sync.
+
+## Layers
+
+### Soul
+
+```bash
+brainjar soul create mysoul --description "Direct and rigorous"
+brainjar soul use mysoul
+```
+
+### Persona
+
+```bash
+brainjar persona use planner    # Design session
+brainjar persona use engineer   # Build session
+brainjar persona use reviewer   # Review session
+```
+
+### Rules
+
+```bash
+brainjar rules create no-delete --description "Never delete files without asking"
+brainjar rules add no-delete
+brainjar rules remove no-delete
+```
+
+### Brain
+
+```bash
+brainjar brain save review           # Snapshot current state as a brain
+brainjar brain use review            # Activate soul + persona + rules in one shot
+brainjar brain list                  # See available brains
+brainjar brain show review           # Inspect a brain's config
+```
+
+When to use a brain vs. switching layers individually:
+- **Brain:** Repeatable workflow you do often (code review, design, debugging). Save once, activate in one command.
+- **Individual layers:** Exploratory work, one-off overrides, or when you only need to change one thing.
+
+## Subagent orchestration
+
+Personas can spawn other personas as subagents. For example, a tech-lead persona can:
+
+1. Spawn an **architect** subagent for design — produces a design doc
+2. Get user approval
+3. Implement the design itself
+4. Spawn a **reviewer** subagent to verify — compares code against the spec
+
+Each subagent gets the full brain context: soul + persona + rules. The `compose` command assembles the full prompt in a single call:
+
+```bash
+# Primary path — brain drives everything
+brainjar compose review --task "Review the changes in src/sync.ts"
+
+# Ad-hoc — no saved brain, specify persona directly
+brainjar compose --persona reviewer --task "Review the changes in src/sync.ts"
+```
+
+For more granular control, use `brainjar persona show <name>` and `brainjar rules show <name>` to retrieve individual layers.
+
+## Recipes
+
+### Code review session
+
+```bash
+# Save a review brain once
+brainjar soul use craftsman
+brainjar persona use reviewer
+brainjar rules add default
+brainjar rules add security
+brainjar brain save review
+
+# Then activate it anytime
+brainjar brain use review
+
+# Or scope it to a single session
+brainjar shell --brain review
+```
+
+### CI pipeline — enforce rules without a persona
+
+```bash
+# In CI, use env vars to override behavior
+BRAINJAR_PERSONA=auditor BRAINJAR_RULES_ADD=security,compliance brainjar status --sync
+```
+
+### Project-specific persona
+
+```bash
+# In your project directory
+brainjar persona use planner --local
+brainjar rules add no-delete --local
+
+# Global settings still apply — local just overrides what you specify
+brainjar status
+# soul     craftsman (global)
+# persona  planner (local)
+# rules    default (global), no-delete (+local)
+```
+
+## Commands
+
+```
+brainjar init [--default] [--obsidian] [--backend claude|codex]
+brainjar status [--sync] [--global|--local] [--short]
+brainjar compose <brain> [--task <text>]
+brainjar compose --persona <name> [--task <text>]
+
+brainjar brain save|use|list|show|drop
+brainjar soul create|list|show|use|drop
+brainjar persona create|list|show|use|drop
+brainjar rules create|list|show|add|remove
+
+brainjar identity create|list|show|use|drop|unlock|get|status|lock
+brainjar shell [--brain|--soul|--persona|--identity|--rules-add|--rules-remove]
+brainjar reset [--backend claude|codex]
+```
+
+`show` accepts an optional name to view any item, not just the active one. Use `--short` to get just the active name (useful in scripts and statuslines):
+
+```bash
+brainjar persona show reviewer    # View a specific persona
+brainjar soul show                # View the active soul
+brainjar rules show security      # View a rule's content
+brainjar status --short           # One-liner: soul | persona | identity
+brainjar soul show --short        # Just the active soul name
+```
+
+## Obsidian support
+
+`~/.brainjar/` is a folder of markdown files — it's already almost an Obsidian vault.
+
+```bash
+brainjar init --obsidian
+```
+
+Adds `.obsidian/` config that hides private files (state, identities) from the file explorer and includes templates for creating new souls, personas, and rules from within Obsidian.
+
+## Backends
+
+```bash
+brainjar init --backend codex      # writes ~/.codex/AGENTS.md
+brainjar reset --backend codex
+```
+
+Supported: `claude` (default), `codex`
+
+## Backup & restore
+
+On first sync, brainjar backs up any existing config file to `CLAUDE.md.pre-brainjar`. Running `brainjar reset` removes brainjar-managed config and restores the backup.
+
+## Development
+
+Built with [Bun](https://bun.sh) and [incur](https://github.com/bradjones/incur).
+
+```bash
+bun install
+bun test
+bun run src/cli.ts --help
+```

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@brainjar/cli",
+  "version": "0.1.0",
+  "description": "Shape how your AI thinks — composable identity, soul, persona, and rules for AI agents",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brainjar-sh/brainjar-cli.git"
+  },
+  "homepage": "https://github.com/brainjar-sh/brainjar-cli",
+  "bugs": "https://github.com/brainjar-sh/brainjar-cli/issues",
+  "keywords": [
+    "ai",
+    "agent",
+    "claude",
+    "claude-code",
+    "codex",
+    "prompt",
+    "persona",
+    "configuration",
+    "cli"
+  ],
+  "bin": {
+    "brainjar": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "prepare": "git config core.hooksPath .hooks",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "check": "tsc --noEmit && bun test",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:tag": "changeset tag",
+    "changeset:publish": "changeset publish"
+  },
+  "dependencies": {
+    "incur": "^0.3.4",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@types/bun": "^1.3.10",
+    "typescript": "^5.9.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+import { Cli } from 'incur'
+import pkg from '../package.json'
+import { init } from './commands/init.js'
+import { identity } from './commands/identity.js'
+import { soul } from './commands/soul.js'
+import { persona } from './commands/persona.js'
+import { rules } from './commands/rules.js'
+import { brain } from './commands/brain.js'
+import { status } from './commands/status.js'
+import { reset } from './commands/reset.js'
+import { shell } from './commands/shell.js'
+import { compose } from './commands/compose.js'
+
+Cli.create('brainjar', {
+  description: 'Shape how your AI thinks — identity, soul, persona, rules',
+  version: pkg.version,
+  sync: { depth: 0 },
+})
+  .command(init)
+  .command(status)
+  .command(soul)
+  .command(persona)
+  .command(rules)
+  .command(brain)
+  .command(identity)
+  .command(reset)
+  .command(shell)
+  .command(compose)
+  .serve()

package/src/commands/brain.ts

@@ -0,0 +1,256 @@
+import { Cli, z, Errors } from 'incur'
+
+const { IncurError } = Errors
+import { readdir, readFile, writeFile, access, rm } from 'node:fs/promises'
+import { join, basename } from 'node:path'
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
+import { paths } from '../paths.js'
+import {
+  readState,
+  writeState,
+  withStateLock,
+  readLocalState,
+  writeLocalState,
+  withLocalStateLock,
+  readEnvState,
+  mergeState,
+  requireBrainjarDir,
+  normalizeSlug,
+} from '../state.js'
+import { sync } from '../sync.js'
+
+/** Brain YAML schema: soul + persona + rules */
+export interface BrainConfig {
+  soul: string
+  persona: string
+  rules: string[]
+}
+
+/** Read and validate a brain YAML file. */
+export async function readBrain(name: string): Promise<BrainConfig> {
+  const slug = normalizeSlug(name, 'brain name')
+  const file = join(paths.brains, `${slug}.yaml`)
+
+  let raw: string
+  try {
+    raw = await readFile(file, 'utf-8')
+  } catch {
+    throw new IncurError({
+      code: 'BRAIN_NOT_FOUND',
+      message: `Brain "${slug}" not found.`,
+      hint: 'Run `brainjar brain list` to see available brains.',
+    })
+  }
+
+  let parsed: unknown
+  try {
+    parsed = parseYaml(raw)
+  } catch (e) {
+    throw new IncurError({
+      code: 'BRAIN_CORRUPT',
+      message: `Brain "${slug}" has invalid YAML: ${(e as Error).message}`,
+    })
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new IncurError({
+      code: 'BRAIN_CORRUPT',
+      message: `Brain "${slug}" is empty or invalid.`,
+    })
+  }
+
+  const p = parsed as Record<string, unknown>
+
+  if (typeof p.soul !== 'string' || !p.soul) {
+    throw new IncurError({
+      code: 'BRAIN_INVALID',
+      message: `Brain "${slug}" is missing required field "soul".`,
+    })
+  }
+
+  if (typeof p.persona !== 'string' || !p.persona) {
+    throw new IncurError({
+      code: 'BRAIN_INVALID',
+      message: `Brain "${slug}" is missing required field "persona".`,
+    })
+  }
+
+  const rules = Array.isArray(p.rules) ? p.rules.map(String) : []
+
+  return { soul: p.soul, persona: p.persona, rules }
+}
+
+export const brain = Cli.create('brain', {
+  description: 'Manage brains — full-stack configuration snapshots (soul + persona + rules)',
+})
+  .command('save', {
+    description: 'Snapshot current effective state as a named brain',
+    args: z.object({
+      name: z.string().describe('Brain name (will be used as filename)'),
+    }),
+    options: z.object({
+      overwrite: z.boolean().default(false).describe('Overwrite existing brain file'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'brain name')
+      const dest = join(paths.brains, `${name}.yaml`)
+
+      // Check for existing brain
+      if (!c.options.overwrite) {
+        try {
+          await access(dest)
+          throw new IncurError({
+            code: 'BRAIN_EXISTS',
+            message: `Brain "${name}" already exists.`,
+            hint: 'Use --overwrite to replace it, or choose a different name.',
+          })
+        } catch (e) {
+          if (e instanceof IncurError) throw e
+        }
+      }
+
+      // Read effective state
+      const globalState = await readState()
+      const localState = await readLocalState()
+      const envState = readEnvState()
+      const effective = mergeState(globalState, localState, envState)
+
+      if (!effective.soul.value) {
+        throw new IncurError({
+          code: 'NO_ACTIVE_SOUL',
+          message: 'Cannot save brain: no active soul.',
+          hint: 'Activate a soul first with `brainjar soul use <name>`.',
+        })
+      }
+
+      if (!effective.persona.value) {
+        throw new IncurError({
+          code: 'NO_ACTIVE_PERSONA',
+          message: 'Cannot save brain: no active persona.',
+          hint: 'Activate a persona first with `brainjar persona use <name>`.',
+        })
+      }
+
+      const activeRules = effective.rules
+        .filter(r => !r.scope.startsWith('-'))
+        .map(r => r.value)
+
+      const config: BrainConfig = {
+        soul: effective.soul.value,
+        persona: effective.persona.value,
+        rules: activeRules,
+      }
+
+      await writeFile(dest, stringifyYaml(config))
+
+      return { saved: name, ...config }
+    },
+  })
+  .command('use', {
+    description: 'Activate a brain — sets soul, persona, and rules in one shot',
+    args: z.object({
+      name: z.string().describe('Brain name to activate'),
+    }),
+    options: z.object({
+      local: z.boolean().default(false).describe('Apply brain at project scope'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'brain name')
+      const config = await readBrain(name)
+
+      // Validate soul exists
+      try {
+        await readFile(join(paths.souls, `${config.soul}.md`), 'utf-8')
+      } catch {
+        throw new IncurError({
+          code: 'SOUL_NOT_FOUND',
+          message: `Brain "${name}" references soul "${config.soul}" which does not exist.`,
+          hint: 'Create the soul first or update the brain file.',
+        })
+      }
+
+      // Validate persona exists
+      try {
+        await readFile(join(paths.personas, `${config.persona}.md`), 'utf-8')
+      } catch {
+        throw new IncurError({
+          code: 'PERSONA_NOT_FOUND',
+          message: `Brain "${name}" references persona "${config.persona}" which does not exist.`,
+          hint: 'Create the persona first or update the brain file.',
+        })
+      }
+
+      if (c.options.local) {
+        await withLocalStateLock(async () => {
+          const local = await readLocalState()
+          local.soul = config.soul
+          local.persona = config.persona
+          // Replace rules entirely — brain is a complete snapshot
+          local.rules = { add: config.rules, remove: [] }
+          await writeLocalState(local)
+          await sync({ local: true })
+        })
+      } else {
+        await withStateLock(async () => {
+          const state = await readState()
+          state.soul = config.soul
+          state.persona = config.persona
+          state.rules = config.rules
+          await writeState(state)
+          await sync()
+        })
+      }
+
+      return { activated: name, local: c.options.local, ...config }
+    },
+  })
+  .command('list', {
+    description: 'List available brains',
+    async run() {
+      await requireBrainjarDir()
+      const entries = await readdir(paths.brains).catch(() => [])
+      const brains = entries
+        .filter(f => f.endsWith('.yaml'))
+        .map(f => basename(f, '.yaml'))
+      return { brains }
+    },
+  })
+  .command('show', {
+    description: 'Show a brain configuration',
+    args: z.object({
+      name: z.string().describe('Brain name to show'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'brain name')
+      const config = await readBrain(name)
+      return { name, ...config }
+    },
+  })
+  .command('drop', {
+    description: 'Delete a brain',
+    args: z.object({
+      name: z.string().describe('Brain name to delete'),
+    }),
+    async run(c) {
+      await requireBrainjarDir()
+      const name = normalizeSlug(c.args.name, 'brain name')
+      const file = join(paths.brains, `${name}.yaml`)
+
+      try {
+        await access(file)
+      } catch {
+        throw new IncurError({
+          code: 'BRAIN_NOT_FOUND',
+          message: `Brain "${name}" not found.`,
+          hint: 'Run `brainjar brain list` to see available brains.',
+        })
+      }
+
+      await rm(file)
+
+      return { dropped: name }
+    },
+  })