brains-cli 0.1.0 → 1.0.1

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.1",
   "description": "🧠 Brains.io — Install AI-powered dev agents. Build, review, architect, and ship with one command.",
   "main": "src/index.js",
   "bin": {
@@ -24,6 +24,7 @@
   "author": "Brains.io",
   "license": "MIT",
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
     "inquirer": "^8.2.6",

package/src/api.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const Anthropic = require('@anthropic-ai/sdk');
+const { getApiKey, getModel } = require('./config');
+
+let client = null;
+
+/**
+ * Initialize or return existing Anthropic client
+ */
+function getClient() {
+  if (client) return client;
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw new Error('NO_API_KEY');
+  }
+  client = new Anthropic({ apiKey });
+  return client;
+}
+
+/**
+ * Stream a Claude response to the terminal in real-time.
+ * Returns the full assistant message text.
+ *
+ * @param {Object} opts
+ * @param {string} opts.systemPrompt - System prompt
+ * @param {Array} opts.messages - Conversation history [{role, content}]
+ * @param {number} [opts.maxTokens] - Max tokens (default from config)
+ * @param {string} [opts.model] - Model override
+ * @param {Function} [opts.onText] - Callback for each text chunk
+ * @param {Function} [opts.onStart] - Called when streaming starts
+ * @param {Function} [opts.onEnd] - Called when streaming ends
+ * @returns {Promise<string>} Full response text
+ */
+async function streamMessage(opts) {
+  const {
+    systemPrompt,
+    messages,
+    maxTokens = 8096,
+    model,
+    onText = (text) => process.stdout.write(text),
+    onStart = () => {},
+    onEnd = () => {},
+  } = opts;
+
+  const anthropic = getClient();
+  const modelId = model || getModel();
+
+  let fullText = '';
+
+  const stream = await anthropic.messages.stream({
+    model: modelId,
+    max_tokens: maxTokens,
+    system: systemPrompt,
+    messages: messages,
+  });
+
+  onStart();
+
+  for await (const event of stream) {
+    if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
+      const text = event.delta.text;
+      fullText += text;
+      onText(text);
+    }
+  }
+
+  onEnd();
+  return fullText;
+}
+
+/**
+ * Send a single message (non-streaming). Used for short tasks.
+ */
+async function sendMessage(opts) {
+  const {
+    systemPrompt,
+    messages,
+    maxTokens = 8096,
+    model,
+  } = opts;
+
+  const anthropic = getClient();
+  const modelId = model || getModel();
+
+  const response = await anthropic.messages.create({
+    model: modelId,
+    max_tokens: maxTokens,
+    system: systemPrompt,
+    messages: messages,
+  });
+
+  return response.content
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('');
+}
+
+module.exports = {
+  getClient,
+  streamMessage,
+  sendMessage,
+};

package/src/commands/config.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const chalk = require('chalk');
+const Table = require('cli-table3');
+const { loadConfig, setConfigValue, getApiKey, maskApiKey, DEFAULTS } = require('../config');
+const { showSuccess, showError, showInfo, ACCENT, DIM } = require('../utils/ui');
+
+async function configCommand(action, args) {
+  if (!action) {
+    // Show all config
+    showCurrentConfig();
+    return;
+  }
+
+  if (action === 'set') {
+    if (args.length < 2) {
+      showError('Usage: brains config set <key> <value>');
+      showInfo(`Example: ${ACCENT('brains config set api_key sk-ant-...')}`);
+      showInfo(`Example: ${ACCENT('brains config set model claude-sonnet-4-20250514')}`);
+      return;
+    }
+
+    const key = args[0];
+    let value = args.slice(1).join(' ');
+
+    // Validate known keys
+    const validKeys = ['api_key', 'model', 'max_tokens', 'theme', 'telemetry'];
+    if (!validKeys.includes(key)) {
+      showError(`Unknown config key "${key}".`);
+      showInfo(`Valid keys: ${validKeys.map(k => ACCENT(k)).join(', ')}`);
+      return;
+    }
+
+    // Type coercion
+    if (key === 'max_tokens') value = parseInt(value, 10);
+    if (key === 'telemetry') value = value === 'true';
+
+    setConfigValue(key, value);
+    const displayValue = key === 'api_key' ? maskApiKey(value) : value;
+    showSuccess(`${key} = ${displayValue}`);
+    console.log('');
+    return;
+  }
+
+  if (action === 'get') {
+    if (args.length < 1) {
+      showError('Usage: brains config get <key>');
+      return;
+    }
+
+    const key = args[0];
+    const config = loadConfig();
+    let value = config[key];
+
+    if (key === 'api_key') {
+      value = maskApiKey(getApiKey());
+    }
+
+    if (value === undefined) {
+      showInfo(`${key} is not set (default: ${DEFAULTS[key] || 'none'})`);
+    } else {
+      console.log(`\n  ${chalk.bold(key)} = ${value}\n`);
+    }
+    return;
+  }
+
+  if (action === 'reset') {
+    const { saveConfig } = require('../config');
+    saveConfig({ ...DEFAULTS });
+    showSuccess('Config reset to defaults.');
+    console.log('');
+    return;
+  }
+
+  showError(`Unknown action "${action}". Use: set, get, reset, or no action to view all.`);
+}
+
+function showCurrentConfig() {
+  const config = loadConfig();
+  const apiKey = getApiKey();
+
+  console.log(`\n  ${chalk.bold('Brains Configuration')}\n`);
+
+  const table = new Table({
+    style: { head: [], border: ['dim'] },
+    colWidths: [20, 46],
+  });
+
+  table.push(
+    [chalk.bold('api_key'), apiKey ? maskApiKey(apiKey) : chalk.red('(not set)')],
+    [chalk.bold('model'), config.model || DEFAULTS.model],
+    [chalk.bold('max_tokens'), String(config.max_tokens || DEFAULTS.max_tokens)],
+    [chalk.bold('theme'), config.theme || DEFAULTS.theme],
+    [chalk.bold('telemetry'), String(config.telemetry ?? DEFAULTS.telemetry)]
+  );
+
+  console.log(table.toString());
+
+  if (!apiKey) {
+    console.log('');
+    showInfo(`Set your API key: ${ACCENT('brains config set api_key sk-ant-...')}`);
+    showInfo(`Or set env var: ${ACCENT('export ANTHROPIC_API_KEY=sk-ant-...')}`);
+  }
+
+  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 {};
 }