brain-cli 🧠

CLI tools for managing a "second brain" (PARA-style markdown notes) + Lobster workflow pipelines.

Built by Alfred in 30 minutes.

The Problem

AI assistants burn tokens orchestrating multi-step tasks. 10 tool calls for an inbox triage? Expensive and fragile.

The Solution

Move orchestration into deterministic workflows with explicit approval checkpoints.

• brain-cli: Small, composable commands for brain management
• Lobster pipelines: Multi-step workflows that run as ONE operation

Installation

# Clone the repo
git clone https://github.com/bloomedai/brain-cli.git

# Add to PATH
export PATH="$PATH:$(pwd)/brain-cli/bin"

# Optional: Install Lobster for pipelines
npm install -g @clawdbot/lobster

AI-Powered Categorization

brain-categorize uses AI when available, falls back to bilingual keyword matching (EN/DE).

Backends (auto-detected):

1. claude CLI (Anthropic)
2. ollama with llama3.2

Force mode:

USE_AI=false brain-categorize  # Keywords only
USE_AI=true brain-categorize   # Require AI (fails if unavailable)

Brain CLI Commands

brain stats           # Overview of all brains
brain inbox [brain]   # List inbox items
brain tasks [brains]  # Find open [ ] todos
brain scan [days]     # Find stale files (default: 7 days)
brain memory list     # List recent memory files
brain memory daily    # Output daily memories as JSON

JSON Mode

For piping between commands:

JSON_MODE=true brain inbox all | brain-categorize | brain-file --approve

Lobster Pipelines

Running Pipelines

# With Lobster CLI
lobster run pipelines/inbox-triage.lobster

# Via Clawdbot (if Lobster tool enabled)
# Just ask: "run the inbox triage pipeline"

Brain Structure

The CLI expects a PARA-style structure:

brain/
├── jero/           # Personal brain
├── jeanine/        # Partner's brain (optional)
├── shared/         # Shared brain (optional)
│   ├── 0-inbox/
│   ├── 1-projects/
│   ├── 2-areas/
│   ├── 3-resources/
│   └── 4-archive/

Configure the root path:

export BRAIN_ROOT="$HOME/notes/brain"

The Pattern

1. Build small, composable CLI commands
2. Chain them with JSON pipes
3. Add approval gates for side effects
4. AI triggers workflows, doesn't orchestrate each step

Less tokens. More deterministic. Full audit trail.

Stack

• Bash scripts (brain CLI)
• jq for JSON transforms
• Lobster for orchestration
• Clawdbot as AI interface

License

MIT

---

Built with 🪄 by Alfred & @plattenschieber