brains-cli 0.1.0 → 1.0.2

package/.env.example

@@ -0,0 +1,2 @@
+# Get your API key at https://console.anthropic.com/
+ANTHROPIC_API_KEY=sk-ant-your-key-here

package/README.md

@@ -1,8 +1,8 @@
-# 🧠 Brains.io
+# brains-cli
 
 > **Install the world's greatest brains.** AI-powered dev agents you can browse, install, and run from your terminal.
 
-Brains are intelligent, conversational AI agents that act as specialized team members. Unlike dumb templates or scaffolders, Brains **talk to you**, understand your context, and generate production-grade output tailored to your specific needs.
+Brains are intelligent, conversational AI agents powered by Claude. Unlike dumb templates or scaffolders, Brains **talk to you**, understand your context, and generate production-grade output tailored to your specific needs.
 
 ## Quick Start
 
@@ -10,29 +10,38 @@ Brains are intelligent, conversational AI agents that act as specialized team me
 # Install globally
 npm install -g brains-cli
 
+# Set your Anthropic API key
+brains config set api_key sk-ant-your-key-here
+
 # Explore available brains
 brains explore
 
-# Install a brain
+# Install and run a brain
 brains install resume
-
-# Run it
 brains run resume
 ```
 
-## What are Brains?
+## How It Works
+
+1. **Browse** the registry of 11 specialized AI agent Brains
+2. **Install** the ones you need to `~/.brains/`
+3. **Run** them — they interview you, then generate real output using Claude
+
+Every Brain has a unique personality, methodology, and expertise defined by a detailed system prompt. When you run a Brain, it calls the Claude API with that system prompt and your context to generate real, production-grade results.
 
-A Brain is an AI agent with a specific personality, methodology, and expertise. Think of it as hiring a world-class specialist for any dev task — but they live in your terminal.
+## Brain Categories
 
-### 🔨 Builder Brains — Generate entire projects
+### Builder Brains — Generate entire projects
 
 | Brain | Description | Price |
 |-------|-------------|-------|
-| `resume` | Build a stunning developer resume/portfolio site | Free |
+| `resume` | Build a complete Next.js resume/portfolio site | Free |
 | `mvp` | Turn a product idea into a full-stack MVP | $9.99 |
 | `landing` | Generate high-converting landing pages | Free |
 
-### 👤 Role Brains — Act as team members
+Builder brains ask you questions, then call Claude to generate a complete project with all files written to disk.
+
+### Role Brains — Act as team members
 
 | Brain | Description | Price |
 |-------|-------------|-------|
@@ -40,14 +49,18 @@ A Brain is an AI agent with a specific personality, methodology, and expertise.
 | `backend` | Backend architect (APIs, databases, infra) | $4.99 |
 | `architect` | System design, diagrams, and technical decisions | $9.99 |
 
-### 🔍 Reviewer Brains — Analyze & improve code
+Role brains enter a conversational REPL — chat back and forth with a specialist who maintains full context.
+
+### Reviewer Brains — Analyze & improve code
 
 | Brain | Description | Price |
 |-------|-------------|-------|
 | `reviewer` | Deep, senior-level code review | Free |
 | `security` | Find vulnerabilities and harden your app | $4.99 |
 
-### ⚡ Domain Brains — Deep tech expertise
+Reviewer brains scan your project files, send them to Claude, and output a structured review report.
+
+### Domain Brains — Deep tech expertise
 
 | Brain | Description | Price |
 |-------|-------------|-------|
@@ -55,11 +68,13 @@ A Brain is an AI agent with a specific personality, methodology, and expertise.
 | `supabase` | Supabase expert (auth, RLS, edge functions) | $4.99 |
 | `stripe` | Payments, subscriptions, webhooks | $4.99 |
 
+Domain brains are conversational experts in a specific technology.
+
 ## Commands
 
 ### `brains explore`
 
-Browse and discover available Brains with an interactive terminal UI.
+Interactive terminal browser for discovering Brains.
 
 ```bash
 brains explore                    # Browse all
@@ -69,27 +84,29 @@ brains explore -s "nextjs"       # Search
 
 ### `brains install <brain>`
 
-Download and configure a Brain.
+Download and save a Brain locally.
 
 ```bash
-brains install resume             # Install resume builder
-brains install mvp                # Install MVP generator
+brains install resume
 brains i reviewer                 # Short alias
 ```
 
 ### `brains run <brain>`
 
-Activate a Brain in conversational mode.
+The core feature. Activates a Brain and connects it to Claude.
 
 ```bash
-brains run resume                 # Start resume builder
-brains run reviewer               # Review current project
+brains run resume                 # Builder: generates a project
+brains run reviewer               # Reviewer: scans and reviews your codebase
+brains run frontend               # Role: conversational REPL with a specialist
 brains run mvp --with stripe supabase  # Stack multiple brains
 ```
 
+**Brain stacking** merges system prompts so a single agent has combined expertise.
+
 ### `brains list`
 
-Show all installed Brains.
+Show installed Brains.
 
 ```bash
 brains list                       # or: brains ls
@@ -97,94 +114,60 @@ brains list                       # or: brains ls
 
 ### `brains create [name]`
 
-Author a new Brain from scratch.
+Author a new Brain with an interactive wizard.
 
 ```bash
 brains create my-brain
-brains create --template builder  # Start from a template
 ```
 
 ### `brains publish`
 
-Publish your Brain to the Brains.io registry.
+Publish your Brain to the registry.
 
 ```bash
 cd my-brain/
-brains publish                    # Public
-brains publish --private          # Private (team only)
+brains publish
 ```
 
-## Brain Stacking
+### `brains config`
 
-Combine multiple Brains for complex tasks:
+Manage your API key and settings.
 
 ```bash
-# Build an MVP with Stripe payments and Supabase backend
-brains run mvp --with stripe supabase
-
-# Review code with security focus
-brains run reviewer --with security
+brains config                     # Show all settings
+brains config set api_key sk-ant-...  # Save API key
+brains config set model claude-sonnet-4-20250514
+brains config get api_key         # Show current key (masked)
+brains config reset               # Reset to defaults
 ```
 
-## Creating Your Own Brain
+## Configuration
 
-Every Brain is defined by three files:
-
-```
-my-brain/
-├── brain.json      ← Configuration (name, category, capabilities, price)
-├── BRAIN.md        ← System prompt & documentation
-└── README.md       ← Public readme for the registry
-```
-
-The **system prompt** in `BRAIN.md` is the core of your Brain. It defines:
-- **Personality** — How the brain communicates
-- **Methodology** — Step-by-step workflow
-- **Principles** — Rules and best practices
-- **Output format** — How results are structured
-
-```bash
-# Scaffold a new brain
-brains create my-brain
-
-# Edit the system prompt
-$EDITOR my-brain/BRAIN.md
-
-# Test locally
-brains run my-brain
-
-# Publish to registry
-cd my-brain && brains publish
-```
+API key resolution order:
+1. `ANTHROPIC_API_KEY` environment variable
+2. `~/.brains/config.json` (set via `brains config set api_key`)
+3. Interactive prompt on first run
 
 ## Architecture
 
 ```
-~/.brains/                        ← Global brains directory
-├── installed.json                ← Registry of installed brains
+~/.brains/
+├── config.json                  # API key, model, preferences
+├── installed.json               # Registry of installed brains
+├── sessions/                    # Saved conversation transcripts
 ├── resume/
-│   ├── brain.json                ← Brain config + system prompt
-│   └── BRAIN.md                  ← Human-readable docs
-├── reviewer/
-│   ├── brain.json
-│   └── BRAIN.md
+│   ├── brain.json               # Brain config + system prompt
+│   └── BRAIN.md                 # Human-readable docs
 └── ...
 ```
 
-## Pricing
-
-| Tier | Price | Includes |
-|------|-------|----------|
-| Free | $0 | 4 free brains (resume, landing, reviewer, nextjs) |
-| Pro | $20/mo | All brains + brain stacking + priority |
-| Enterprise | Custom | Private registry + team management |
-
-Brain creators set their own prices. Platform takes 20%.
-
-## Contributing
+## Tech Stack
 
-Want to contribute a Brain to the registry? See [CONTRIBUTING.md](./CONTRIBUTING.md).
+- **Runtime**: Node.js 16+ (CommonJS)
+- **AI**: Claude via `@anthropic-ai/sdk` (streaming)
+- **CLI**: Commander.js, Inquirer.js
+- **UI**: Chalk, Ora, Boxen, Figlet, gradient-string, cli-table3
 
 ## License
 
-MIT © Brains.io
+MIT

package/bin/brains.js

@@ -10,8 +10,24 @@ const { run } = require('../src/commands/run');
 const { list } = require('../src/commands/list');
 const { create } = require('../src/commands/create');
 const { publish } = require('../src/commands/publish');
+const { config } = require('../src/commands/config');
 const { showBanner } = require('../src/utils/ui');
 
+// Graceful shutdown on Ctrl+C
+process.on('SIGINT', () => {
+  console.log('\n');
+  process.exit(0);
+});
+
+// Suppress unhandled rejection noise — errors are handled in commands
+process.on('unhandledRejection', (err) => {
+  if (err && err.message !== 'NO_API_KEY') {
+    const chalk = require('chalk');
+    console.error(`\n  ${chalk.red('✗')} Unexpected error: ${err.message || err}\n`);
+  }
+  process.exit(1);
+});
+
 showBanner();
 
 program
@@ -39,7 +55,7 @@ program
 program
   .command('run <brain>')
   .alias('r')
-  .description('Run an installed Brain in conversational mode')
+  .description('Run an installed Brain — the core AI experience')
   .option('-w, --with <brains...>', 'Stack multiple brains together')
   .option('-d, --dir <directory>', 'Target directory (default: current)')
   .option('--no-interactive', 'Run without interactive prompts')
@@ -66,6 +82,12 @@ program
   .option('--private', 'Publish as a private Brain')
   .action(publish);
 
+// ─── Config: Manage settings ───
+program
+  .command('config [action] [args...]')
+  .description('Manage settings (set/get api_key, model, etc.)')
+  .action(config);
+
 program.parse(process.argv);
 
 // If no args, show help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brains-cli",
-  "version": "0.1.0",
+  "version": "1.0.2",
   "description": "🧠 Brains.io — Install AI-powered dev agents. Build, review, architect, and ship with one command.",
   "main": "src/index.js",
   "bin": {
@@ -24,6 +24,8 @@
   "author": "Brains.io",
   "license": "MIT",
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "openai": "^4.78.0",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
     "inquirer": "^8.2.6",

package/src/api.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * API Router — delegates to the active provider.
+ *
+ * All brain commands call streamMessage/sendMessage from here.
+ * This module resolves which provider to use and routes accordingly.
+ */
+
+const { getActiveProvider, getProviderApiKey, getProviderModel, getProviderBaseUrl } = require('./config');
+const { getProviderDef } = require('./providers/registry');
+
+/**
+ * Stream a response from the active AI provider.
+ * Returns the full assistant message text.
+ *
+ * @param {Object} opts
+ * @param {string} opts.systemPrompt
+ * @param {Array}  opts.messages - [{role, content}]
+ * @param {number} [opts.maxTokens]
+ * @param {string} [opts.model] - Override model
+ * @param {Function} [opts.onText]
+ * @param {Function} [opts.onStart]
+ * @param {Function} [opts.onEnd]
+ * @returns {Promise<string>}
+ */
+async function streamMessage(opts) {
+  const {
+    systemPrompt,
+    messages,
+    maxTokens = 8096,
+    model,
+    onText = (text) => process.stdout.write(text),
+    onStart = () => {},
+    onEnd = () => {},
+  } = opts;
+
+  const providerName = getActiveProvider();
+  const providerDef = getProviderDef(providerName);
+
+  if (!providerDef) {
+    throw new Error(`Unknown provider "${providerName}". Run: brains config set provider <name>`);
+  }
+
+  const apiKey = getProviderApiKey(providerName);
+  const modelId = model || getProviderModel(providerName);
+  const baseURL = getProviderBaseUrl(providerName);
+
+  if (!apiKey && providerDef.requires_key !== false) {
+    throw new Error('NO_API_KEY');
+  }
+
+  const callOpts = {
+    apiKey,
+    systemPrompt,
+    messages,
+    maxTokens,
+    model: modelId,
+    onText,
+    onStart,
+    onEnd,
+  };
+
+  if (providerDef.type === 'anthropic') {
+    const provider = require('./providers/anthropic');
+    return provider.streamMessage(callOpts);
+  } else {
+    const provider = require('./providers/openai-compat');
+    callOpts.baseURL = baseURL;
+    return provider.streamMessage(callOpts);
+  }
+}
+
+/**
+ * Send a single message (non-streaming).
+ */
+async function sendMessage(opts) {
+  const {
+    systemPrompt,
+    messages,
+    maxTokens = 8096,
+    model,
+  } = opts;
+
+  const providerName = getActiveProvider();
+  const providerDef = getProviderDef(providerName);
+
+  if (!providerDef) {
+    throw new Error(`Unknown provider "${providerName}".`);
+  }
+
+  const apiKey = getProviderApiKey(providerName);
+  const modelId = model || getProviderModel(providerName);
+  const baseURL = getProviderBaseUrl(providerName);
+
+  if (!apiKey && providerDef.requires_key !== false) {
+    throw new Error('NO_API_KEY');
+  }
+
+  const callOpts = { apiKey, systemPrompt, messages, maxTokens, model: modelId };
+
+  if (providerDef.type === 'anthropic') {
+    const provider = require('./providers/anthropic');
+    return provider.sendMessage(callOpts);
+  } else {
+    const provider = require('./providers/openai-compat');
+    callOpts.baseURL = baseURL;
+    return provider.sendMessage(callOpts);
+  }
+}
+
+module.exports = {
+  streamMessage,
+  sendMessage,
+};

package/src/commands/config.js

@@ -0,0 +1,236 @@
+'use strict';
+
+const chalk = require('chalk');
+const Table = require('cli-table3');
+const {
+  loadConfig, saveConfig, setConfigValue,
+  getActiveProvider, getProviderApiKey, getProviderModel, getProviderBaseUrl,
+  setProviderApiKey, setProviderModel, setActiveProvider,
+  maskApiKey, DEFAULTS,
+} = require('../config');
+const { getAllProviders, getProviderDef, getAllProviderNames } = require('../providers/registry');
+const { showSuccess, showError, showInfo, showWarning, ACCENT, DIM, SUCCESS } = require('../utils/ui');
+
+async function configCommand(action, args) {
+  if (!action) {
+    showCurrentConfig();
+    return;
+  }
+
+  // ─── brains config set <key> <value> ───
+  if (action === 'set') {
+    if (args.length < 2) {
+      showError('Usage: brains config set <key> <value>');
+      console.log('');
+      showInfo(`${ACCENT('provider')}     — Switch AI provider (groq, anthropic, gemini, openrouter, ollama)`);
+      showInfo(`${ACCENT('api_key')}      — Set API key for current provider`);
+      showInfo(`${ACCENT('model')}        — Set model for current provider`);
+      showInfo(`${ACCENT('max_tokens')}   — Set max tokens`);
+      console.log('');
+      showInfo(`Example: ${ACCENT('brains config set provider groq')}`);
+      showInfo(`Example: ${ACCENT('brains config set api_key gsk_...')}`);
+      return;
+    }
+
+    const key = args[0];
+    let value = args.slice(1).join(' ');
+
+    // ── Switch provider ──
+    if (key === 'provider') {
+      const providerDef = getProviderDef(value);
+      if (!providerDef) {
+        showError(`Unknown provider "${value}".`);
+        showInfo(`Available: ${getAllProviderNames().map(n => ACCENT(n)).join(', ')}`);
+        return;
+      }
+
+      setActiveProvider(value);
+      showSuccess(`Provider switched to ${chalk.bold(providerDef.name)}`);
+
+      // Check if key is configured
+      const apiKey = getProviderApiKey(value);
+      if (!apiKey && providerDef.requires_key !== false) {
+        console.log('');
+        showWarning(`No API key set for ${providerDef.name}.`);
+        showInfo(`Get one at: ${ACCENT(providerDef.key_url)}`);
+        showInfo(`Then run:   ${ACCENT(`brains config set api_key <your-key>`)}`);
+      } else {
+        showInfo(`Model: ${DIM(getProviderModel(value))}`);
+      }
+      console.log('');
+      return;
+    }
+
+    // ── Set API key (for current provider) ──
+    if (key === 'api_key') {
+      const currentProvider = getActiveProvider();
+      setProviderApiKey(currentProvider, value);
+      showSuccess(`API key saved for ${getProviderDef(currentProvider).name}: ${maskApiKey(value)}`);
+      console.log('');
+      return;
+    }
+
+    // ── Set model (for current provider) ──
+    if (key === 'model') {
+      const currentProvider = getActiveProvider();
+      setProviderModel(currentProvider, value);
+      showSuccess(`Model set for ${getProviderDef(currentProvider).name}: ${value}`);
+      console.log('');
+      return;
+    }
+
+    // ── Generic config keys ──
+    const validKeys = ['max_tokens', 'theme', 'telemetry'];
+    if (!validKeys.includes(key)) {
+      showError(`Unknown config key "${key}".`);
+      showInfo(`Valid keys: provider, api_key, model, ${validKeys.map(k => ACCENT(k)).join(', ')}`);
+      return;
+    }
+
+    if (key === 'max_tokens') value = parseInt(value, 10);
+    if (key === 'telemetry') value = value === 'true';
+
+    setConfigValue(key, value);
+    showSuccess(`${key} = ${value}`);
+    console.log('');
+    return;
+  }
+
+  // ─── brains config get <key> ───
+  if (action === 'get') {
+    if (args.length < 1) {
+      showError('Usage: brains config get <key>');
+      return;
+    }
+
+    const key = args[0];
+
+    if (key === 'provider') {
+      const p = getActiveProvider();
+      const def = getProviderDef(p);
+      console.log(`\n  ${chalk.bold('provider')} = ${p} (${def ? def.name : 'unknown'})\n`);
+      return;
+    }
+
+    if (key === 'api_key') {
+      const p = getActiveProvider();
+      const k = getProviderApiKey(p);
+      console.log(`\n  ${chalk.bold('api_key')} [${p}] = ${k ? maskApiKey(k) : chalk.red('(not set)')}\n`);
+      return;
+    }
+
+    if (key === 'model') {
+      const p = getActiveProvider();
+      console.log(`\n  ${chalk.bold('model')} [${p}] = ${getProviderModel(p)}\n`);
+      return;
+    }
+
+    const config = loadConfig();
+    const value = config[key];
+    if (value === undefined) {
+      showInfo(`${key} is not set (default: ${DEFAULTS[key] || 'none'})`);
+    } else {
+      console.log(`\n  ${chalk.bold(key)} = ${value}\n`);
+    }
+    return;
+  }
+
+  // ─── brains config providers ───
+  if (action === 'providers') {
+    showProviderList();
+    return;
+  }
+
+  // ─── brains config reset ───
+  if (action === 'reset') {
+    saveConfig({ ...DEFAULTS, providers: {} });
+    showSuccess('Config reset to defaults (provider: groq).');
+    console.log('');
+    return;
+  }
+
+  showError(`Unknown action "${action}". Use: set, get, providers, reset, or no action to view all.`);
+}
+
+// ═══════════════════════════════════════════
+//  Display helpers
+// ═══════════════════════════════════════════
+
+function showCurrentConfig() {
+  const config = loadConfig();
+  const currentProvider = getActiveProvider();
+  const providerDef = getProviderDef(currentProvider);
+  const apiKey = getProviderApiKey(currentProvider);
+  const model = getProviderModel(currentProvider);
+
+  console.log(`\n  ${chalk.bold('Brains Configuration')}\n`);
+
+  const table = new Table({
+    style: { head: [], border: ['dim'] },
+    colWidths: [20, 46],
+  });
+
+  table.push(
+    [chalk.bold('provider'), `${currentProvider} ${DIM(`(${providerDef ? providerDef.name : 'unknown'})`)}`],
+    [chalk.bold('api_key'), apiKey ? maskApiKey(apiKey) : (providerDef && providerDef.requires_key === false ? DIM('(not required)') : chalk.red('(not set)'))],
+    [chalk.bold('model'), model],
+    [chalk.bold('max_tokens'), String(config.max_tokens || DEFAULTS.max_tokens)],
+    [chalk.bold('telemetry'), String(config.telemetry ?? DEFAULTS.telemetry)]
+  );
+
+  console.log(table.toString());
+
+  if (!apiKey && providerDef && providerDef.requires_key !== false) {
+    console.log('');
+    showInfo(`Set API key: ${ACCENT(`brains config set api_key <your-${currentProvider}-key>`)}`);
+    if (providerDef.key_url) {
+      showInfo(`Get one at:  ${ACCENT(providerDef.key_url)}`);
+    }
+  }
+
+  console.log('');
+  showInfo(`Switch provider: ${ACCENT('brains config set provider <name>')}`);
+  showInfo(`See all providers: ${ACCENT('brains config providers')}`);
+  console.log('');
+}
+
+function showProviderList() {
+  const currentProvider = getActiveProvider();
+  const allProviders = getAllProviders();
+
+  console.log(`\n  ${chalk.bold('Available Providers')}\n`);
+
+  const table = new Table({
+    head: [
+      chalk.white.bold('Provider'),
+      chalk.white.bold('Type'),
+      chalk.white.bold('Default Model'),
+      chalk.white.bold('Free?'),
+      chalk.white.bold('Status'),
+    ],
+    style: { head: [], border: ['dim'] },
+    colWidths: [16, 12, 36, 8, 14],
+  });
+
+  for (const [name, def] of Object.entries(allProviders)) {
+    const isActive = name === currentProvider;
+    const hasKey = !!getProviderApiKey(name) || def.requires_key === false;
+
+    table.push([
+      isActive ? chalk.hex('#7B2FFF').bold(`▸ ${name}`) : `  ${name}`,
+      DIM(def.type),
+      DIM(def.default_model),
+      def.free ? SUCCESS('Yes') : DIM('Paid'),
+      hasKey ? SUCCESS('Ready') : chalk.yellow('Need key'),
+    ]);
+  }
+
+  console.log(table.toString());
+
+  console.log('');
+  showInfo(`Active: ${ACCENT(currentProvider)}`);
+  showInfo(`Switch: ${ACCENT('brains config set provider <name>')}`);
+  console.log('');
+}
+
+module.exports = { config: configCommand };

package/src/commands/install.js

@@ -15,7 +15,9 @@ function getInstalledBrains() {
     if (fs.existsSync(INSTALLED_FILE)) {
       return JSON.parse(fs.readFileSync(INSTALLED_FILE, 'utf-8'));
     }
-  } catch (e) {}
+  } catch (e) {
+    // corrupted file, return empty
+  }
   return {};
 }