brainctl 0.1.6 → 0.1.9

package/README.md

@@ -1,120 +1,231 @@
+<div align="center">
+
 # 🧠 brainctl
 
-> One AI setup. Multiple agents. Zero reconfiguration.
+**One AI setup. Three agents. Zero reconfiguration.**
 
-**brainctl** is a cross-agent AI workflow manager that unifies your environment across Claude Code, Codex, and Gemini CLI — with a web dashboard, MCP server, and portable profiles.
+*A cross-agent command centre for Claude Code, Codex, and Gemini CLI — CLI + MCP server + drag-and-drop web dashboard.*
 
 [![npm version](https://img.shields.io/npm/v/brainctl)](https://www.npmjs.com/package/brainctl)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Build](https://img.shields.io/github/actions/workflow/status/Rorogogogo/brainctl/deploy.yml?branch=main)](https://github.com/Rorogogogo/brainctl/actions)
+[![Stars](https://img.shields.io/github/stars/Rorogogogo/brainctl?style=social)](https://github.com/Rorogogogo/brainctl)
+
+</div>
 
 ---
 
-## ✨ Features
+## 📦 Install & Set Up
+
+> **Install once, wire into each agent.** The CLI is the same for everyone — only the MCP registration differs per agent.
+
+### 1. Install the CLI
+
+```bash
+npm install -g brainctl
+```
+
+Verify:
+
+```bash
+brainctl --version
+brainctl doctor   # checks which agents are on your PATH
+```
 
-- 🔀 **Multi-agent support** — Claude Code, Codex, and Gemini CLI from one config
-- 🖥️ **Web dashboard** — Visual drag-and-drop MCP management across agents
-- 🔌 **MCP server** — 20 tools exposable to any MCP-compatible agent
-- 📦 **Portable profiles** — Export/import skill + MCP bundles as tarballs
-- 🧠 **Shared memory** — Markdown-based context files shared across agents
-- 🧩 **Reusable skills** — Prompt templates stored in `ai-stack.yaml`
-- 🔄 **Profile sync** — Push configs to all agents in one command
-- 🩺 **Health checks** — `status` and `doctor` commands for visibility
-- 🔁 **Fallback agents** — Automatic failover if primary agent is unavailable
+> **Prerequisite:** at least one of `claude`, `codex`, or `gemini` installed and on your `PATH`.
 
 ---
 
-## 📸 Demo
+### 2. Register `brainctl` as an MCP server (pick your agents)
+
+Each agent has its own config file. Brainctl exposes **22 MCP tools** (profiles, sync, skills, run, web UI launch, etc.) — once you register it, any of them can call those tools.
 
-### Web Dashboard — Drag MCPs between agents
+<details open>
+<summary><b>🟣 Claude Code</b> — <code>~/.claude.json</code></summary>
 
+Easiest: use the `claude` CLI.
+
+```bash
+claude mcp add brainctl -s user -- npx -y brainctl mcp
 ```
-┌──────────────┐  ┌──────────────┐  ┌──────────────┐
-│    Claude     │  │    Codex     │  │    Gemini    │
-│ ┌──────────┐ │  │ ┌──────────┐ │  │              │
-│ │ github   │◄├──┤►│ github   │ │  │  Drop here   │
-│ │ brainctl │ │  │ │ brainctl │ │  │  to copy     │
-│ └──────────┘ │  │ └──────────┘ │  │              │
-│ Skills: 11   │  │ Skills: 3    │  │ Skills: 0    │
-└──────────────┘  └──────────────┘  └──────────────┘
+
+Or edit `~/.claude.json` directly:
+
+```jsonc
+{
+  "mcpServers": {
+    "brainctl": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "brainctl", "mcp"]
+    }
+  }
+}
+```
+
+Reload the MCP in Claude Code: `/mcp` → `brainctl` → **Reconnect**.
+
+</details>
+
+<details open>
+<summary><b>🟢 Codex</b> — <code>~/.codex/config.toml</code></summary>
+
+Append this block:
+
+```toml
+[mcp_servers.brainctl]
+command = "npx"
+args = ["-y", "brainctl", "mcp"]
+```
+
+Restart your Codex session to pick it up.
+
+</details>
+
+<details open>
+<summary><b>🔵 Gemini CLI</b> — <code>~/.gemini/settings.json</code></summary>
+
+Merge into the top-level `mcpServers` object:
+
+```json
+{
+  "mcpServers": {
+    "brainctl": {
+      "command": "npx",
+      "args": ["-y", "brainctl", "mcp"]
+    }
+  }
+}
 ```
 
-The dashboard reads **live config files** from each agent (`~/.claude.json`, `~/.codex/config.toml`, `~/.gemini/settings.json`) and lets you drag MCPs between them. Changes are staged and only applied on confirm.
+Restart your Gemini session.
+
+</details>
 
 ---
 
-## 📦 Installation
+### 3. Launch the dashboard
 
 ```bash
-npm install -g brainctl
+brainctl ui
+# → http://127.0.0.1:3333
 ```
 
-Or from source:
+Or from any MCP-connected agent: _"Open the brainctl UI"_ — it'll start the server **and** open your browser automatically.
+
+---
+
+## ✨ Features
+
+- 🔀 **Multi-agent** — Claude Code, Codex, Gemini CLI from one config
+- 🖱️ **Drag-and-drop dashboard** — shuffle MCPs and skills between agents, staged + previewed before save
+- 🔌 **MCP server** — 22 tools any compatible agent can call
+- 📦 **Portable profiles** _(preview)_ — pack an entire agent setup (plugins + skills + MCPs) into a self-contained tarball
+- 🌐 **Multi-runtime packing** — Node, Python, Java, Go, Rust, or plain binaries — auto-detected
+- 🧠 **Shared memory** — markdown files injected into every run
+- 🧩 **Reusable skills** — prompt templates in `ai-stack.yaml`
+- 🔄 **One-shot sync** — push the active profile to all agents in one command
+- 🩺 **Health checks** — `status` and `doctor` surface drift and broken config
+- 🔁 **Fallback agents** — automatic failover if the primary agent is unavailable
+
+---
+
+## 📸 Dashboard at a glance
 
-```bash
-git clone https://github.com/Rorogogogo/brainctl.git
-cd brainctl
-npm install && npm run build && npm link
+```
+┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+│    Claude    │  │    Codex     │  │    Gemini    │
+│ ┌──────────┐ │  │ ┌──────────┐ │  │              │
+│ │ github   │◄├──┤►│ github   │ │  │  drop here   │
+│ │ brainctl │ │  │ │ brainctl │ │  │  to copy     │
+│ └──────────┘ │  │ └──────────┘ │  │              │
+│ Skills: 11   │  │ Skills: 3    │  │ Skills: 0    │
+└──────────────┘  └──────────────┘  └──────────────┘
 ```
 
-> **Prerequisite:** At least one supported agent CLI must be installed and on your `PATH` (`claude`, `codex`, or `gemini`).
+The dashboard reads **live config files** (`~/.claude.json`, `~/.codex/config.toml`, `~/.gemini/settings.json`) and writes back atomically with timestamped backups.
 
 ---
 
 ## 🚀 Quick Start
 
 ```bash
-# 1. Initialize a project
+# Scaffold a project
 brainctl init
 
-# 2. Check your setup
+# See what's wired up
 brainctl status
 brainctl doctor
 
-# 3. Run a skill
+# Run a skill through an agent
 brainctl run summarize ./memory/notes.md --with claude
 
-# 4. Launch the web dashboard
+# Open the dashboard
 brainctl ui
-# → http://127.0.0.1:3333
 ```
 
 ---
 
-## 📖 Usage
-
-### CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `brainctl init` | Scaffold `ai-stack.yaml` and `memory/` directory |
-| `brainctl status` | Show memory, skills, MCPs, and agent availability |
-| `brainctl doctor` | Validate config, paths, and installed agents |
-| `brainctl run <skill> <file> --with <agent>` | Execute a skill through an agent |
-| `brainctl profile list` | List available profiles |
-| `brainctl profile create <name>` | Create a new profile |
-| `brainctl profile use <name>` | Switch active profile |
-| `brainctl profile export <name>` | Export profile as portable tarball |
-| `brainctl profile import <archive>` | Import profile from tarball |
-| `brainctl sync` | Sync active profile to all agent configs |
+## 📖 CLI reference
+
+| Command | What it does |
+|---|---|
+| `brainctl init` | Scaffold `ai-stack.yaml` and `memory/` |
+| `brainctl status` | Memory, skills, MCPs, and agent availability |
+| `brainctl doctor` | Validate config, paths, and agent CLIs |
+| `brainctl run <skill> <file> --with <agent>` | Execute a skill |
+| `brainctl profile list / create / use / delete` | Manage saved profiles |
+| `brainctl profile export [name] [--agent <agent>]` | Pack a profile or live agent as a portable tarball |
+| `brainctl profile import <archive> [--credential key=value]` | Restore a portable tarball |
+| `brainctl sync` | Push the active profile to every agent |
 | `brainctl ui` | Start the web dashboard |
+| `brainctl mcp` | Run as an MCP server over stdio |
 
-### Run Examples
+### Run examples
 
 ```bash
-# Basic execution
 brainctl run summarize ./notes.md --with claude
+brainctl run analyze   ./report.md --with codex --fallback claude
+brainctl run review    ./code.md   --with gemini
+```
+
+---
+
+## 📦 Portable profiles
 
-# With fallback agent
-brainctl run analyze ./report.md --with codex --fallback claude
+Pack your complete agent setup — **plugins, user-authored skills, and MCPs** — into a single `.tar.gz`. The receiver imports it with one command; no marketplace, no network lookups.
 
-# Using Gemini
-brainctl run review ./code.md --with gemini
+```bash
+# Pack a saved profile
+brainctl profile export starter
+
+# Pack a live agent's state (plugins + skills + MCPs)
+brainctl profile export --agent claude
+
+# Restore on another machine
+brainctl profile import ./claude.tar.gz \
+  --credential github_token=ghp_xxx
 ```
 
+**Supported MCP runtimes when packing bundled servers:**
+
+| Runtime | Detected via | Install on unpack | Excluded |
+|---|---|---|---|
+| Node.js | `node`, `npx` | `npm install` | `node_modules/` |
+| Python | `python`, `python3` | `pip install` / `uv sync` | `.venv/`, `__pycache__/` |
+| Java | `java -jar` | — | — |
+| Java (project) | `pom.xml`, `build.gradle` | `mvn package` / `gradle build` | `target/`, `build/` |
+| Go | `go run` | `go build ./...` | — |
+| Rust | `cargo run` | `cargo build --release` | `target/` |
+| Binary | `./server` | — | — |
+
+Credentials are redacted to `${credentials.<key>}` placeholders on export and resolved on import.
+
+> ⚠️ Pack / Install via the web UI is currently disabled while we grind the last rough edges. The CLI commands above work today.
+
 ---
 
-## 🧠 Config: `ai-stack.yaml`
+## 🧠 `ai-stack.yaml`
 
 ```yaml
 memory:
@@ -135,15 +246,15 @@ skills:
 mcps: {}
 ```
 
-### How Context Assembly Works
+### How context is assembled
 
 ```
 ┌─────────────┐
-│   MEMORY    │  ← Markdown files from configured paths
+│   MEMORY    │  ← markdown files from configured paths
 ├─────────────┤
-│   SKILL     │  ← Prompt template from ai-stack.yaml
+│   SKILL     │  ← prompt template from ai-stack.yaml
 ├─────────────┤
-│   INPUT     │  ← Your file
+│   INPUT     │  ← your file
 └─────────────┘
         ↓
    Agent CLI (claude / codex / gemini)
@@ -151,51 +262,29 @@ mcps: {}
 
 ---
 
-## 🔌 MCP Server
-
-brainctl exposes **20 MCP tools** that any compatible agent can call:
-
-```bash
-# Add brainctl as an MCP server in your agent config
-# Claude (~/.claude.json):
-{
-  "mcpServers": {
-    "brainctl": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "brainctl", "mcp"]
-    }
-  }
-}
-```
-
-**Available tools:**
+## 🔌 MCP tools
 
 | Category | Tools |
-|----------|-------|
+|---|---|
 | **Skills** | `list_skills`, `get_skill`, `run` |
 | **Memory** | `read_memory`, `write_memory` |
 | **Profiles** | `list_profiles`, `get_profile`, `create_profile`, `update_profile`, `delete_profile`, `switch_profile`, `copy_profile_items`, `export_profile`, `import_profile` |
-| **Agent Configs** | `read_agent_configs`, `add_agent_mcp`, `remove_agent_mcp` |
-| **System** | `status`, `doctor`, `sync` |
+| **Agent configs** | `read_agent_configs`, `add_agent_mcp`, `remove_agent_mcp` |
+| **Sync** | `sync` |
+| **System** | `status`, `doctor` |
+| **UI** | `open_ui`, `close_ui` |
 
 ---
 
-## 🖥️ Web Dashboard
+## 🗂️ Agent config map
 
-```bash
-brainctl ui
-```
-
-Opens a local dashboard at `http://127.0.0.1:3333` with:
+| Agent | Config file | MCP location | Skills / plugins |
+|---|---|---|---|
+| Claude | `~/.claude.json` | `mcpServers` + `projects[cwd].mcpServers` | `~/.claude/plugins/` + `~/.claude/skills/` |
+| Codex | `~/.codex/config.toml` | `[mcp_servers.*]` | `~/.codex/plugins/` + `~/.codex/skills/` |
+| Gemini | `~/.gemini/settings.json` | `mcpServers` | `~/.gemini/skills/` |
 
-- **Agent Profiles** — See live MCPs and skills for Claude, Codex, and Gemini side-by-side
-- **Drag & Drop** — Copy MCPs between agents by dragging cards
-- **Staged Changes** — Preview adds/removes before applying, with undo support
-- **Skills Editor** — Edit skill prompts with live preview
-- **MCP Manager** — View and edit MCP configurations
-- **Memory Viewer** — Browse shared markdown memory files
-- **Run Console** — Execute skills with real-time streaming output
+Writes are atomic (temp file → rename) and always leave a timestamped `.bak.*` behind.
 
 ---
 
@@ -204,63 +293,53 @@ Opens a local dashboard at `http://127.0.0.1:3333` with:
 ```
 brainctl/
 ├── src/
-│   ├── cli.ts              # CLI entry point (Commander)
-│   ├── commands/            # 8 command handlers
-│   ├── services/            # 11 business logic services
-│   │   └── sync/            # Agent config readers/writers
-│   ├── context/             # Memory loader, skill resolver, context builder
-│   ├── executor/            # Agent spawning (Claude, Codex, Gemini)
-│   ├── mcp/                 # FastMCP server (20 tools)
-│   └── ui/                  # HTTP server with SSE streaming
-├── web/src/                 # React dashboard (Vite + dnd-kit)
-├── tests/                   # Vitest test suite
-└── ai-stack.yaml            # Project config
+│   ├── cli.ts              # Commander entry
+│   ├── commands/           # CLI handlers
+│   ├── services/           # Business logic (factory pattern)
+│   │   └── sync/           # Per-agent readers + writers
+│   ├── context/            # Memory + skill + context builder
+│   ├── executor/           # Agent subprocess spawning
+│   ├── mcp/                # FastMCP server
+│   └── ui/                 # HTTP server (SSE streaming)
+├── web/src/                # React dashboard (Vite + dnd-kit)
+└── tests/                  # Vitest suite
 ```
 
-### Agent Config Locations
-
-| Agent | Config Path | MCP Location |
-|-------|-------------|-------------|
-| Claude | `~/.claude.json` | `projects[cwd].mcpServers` |
-| Codex | `~/.codex/config.toml` | `[mcp_servers.*]` |
-| Gemini | `~/.gemini/settings.json` | `mcpServers` |
-
 ---
 
-## 🧪 Development
+## 🧪 Develop locally
 
 ```bash
+git clone https://github.com/Rorogogogo/brainctl.git
+cd brainctl
 npm install
-npm test              # Run all tests (Vitest)
-npm run build         # Build server (tsc) + web (Vite)
-npm run dev -- <args> # Run CLI via tsx
+
+npm test                  # vitest
+npm run build             # server (tsc) + web (vite)
+npm run dev -- status     # run CLI via tsx
+npx tsx src/cli.ts ui     # dashboard from source
 ```
 
+Point your agent's MCP config at `node <repo>/dist/cli.js mcp` to iterate without publishing.
+
 ---
 
-## 🤝 Contributing
+## 💡 Philosophy
 
-Contributions are welcome! Please open an issue or submit a pull request.
+brainctl doesn't replace your AI tools — it sits **between you and them** as a thin orchestration layer:
 
-```bash
-git clone https://github.com/Rorogogogo/brainctl.git
-cd brainctl
-npm install
-npm test
-```
+- You keep using Claude Code, Codex, and Gemini CLI directly.
+- brainctl keeps the environment consistent across all of them.
+- Portable profiles make your setup shareable in one file.
 
 ---
 
-## 💡 Philosophy
-
-brainctl doesn't replace your AI tools. It sits between you and them as a thin orchestration layer:
+## 🤝 Contributing
 
-- **You keep using** Claude Code, Codex, and Gemini CLI directly
-- **brainctl keeps** the environment consistent across all of them
-- **Profiles make it portable** — share your setup with your team
+Issues and PRs welcome. See [`CLAUDE.md`](CLAUDE.md) for the codebase map an agent-friendly contribution flow.
 
 ---
 
 ## 📄 License
 
-[MIT](https://opensource.org/licenses/MIT) — use it however you want.
+[MIT](https://opensource.org/licenses/MIT) — do whatever you want.

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { realpathSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { registerDoctorCommand } from './commands/doctor.js';
@@ -12,6 +13,7 @@ import { registerStatusCommand } from './commands/status.js';
 import { registerSyncCommand } from './commands/sync.js';
 import { registerUiCommand } from './commands/ui.js';
 import { printError } from './output.js';
+import { createUpdateCheckService } from './services/update-check-service.js';
 import { createDoctorService } from './services/doctor-service.js';
 import { createInitService } from './services/init-service.js';
 import { createProfileExportService } from './services/profile-export-service.js';
@@ -52,6 +54,44 @@ export async function main(argv = process.argv) {
         printError(error);
         process.exitCode = 1;
     }
+    // Skip update check for MCP mode (handled in mcp command), non-TTY, opt-out, or local dev
+    const isMcpCommand = argv.includes('mcp');
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isOptedOut = !!process.env.BRAINCTL_NO_UPDATE_CHECK;
+    const isLocalDev = import.meta.url.includes('/src/');
+    if (isMcpCommand || !isInteractive || isOptedOut || isLocalDev)
+        return;
+    try {
+        const service = createUpdateCheckService();
+        const check = await service.check();
+        if (!check.isOutdated)
+            return;
+        const answer = await promptYesNo(`\n⚠ brainctl ${check.latest} is available (you have ${check.current}).\n  Update now? [Y/n] `);
+        if (answer) {
+            process.stderr.write('  Updating...\n');
+            const result = await service.selfUpdate();
+            if (result.success) {
+                process.stderr.write(`  Updated to brainctl@${check.latest}\n`);
+            }
+            else {
+                process.stderr.write(`  Update failed: ${result.error ?? 'unknown error'}\n`);
+                process.stderr.write('  Run manually: npm install -g brainctl\n');
+            }
+        }
+    }
+    catch {
+        // Update check failed — don't interrupt the user
+    }
+}
+function promptYesNo(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            const trimmed = answer.trim().toLowerCase();
+            resolve(trimmed === '' || trimmed === 'y' || trimmed === 'yes');
+        });
+    });
 }
 export function shouldRunMain(entryPointPath, moduleUrl) {
     if (!entryPointPath) {

package/dist/commands/mcp.js

@@ -1,9 +1,44 @@
+import { spawn } from 'node:child_process';
 import { startMcpServer } from '../mcp/server.js';
+import { createUpdateCheckService } from '../services/update-check-service.js';
 export function registerMcpCommand(program) {
     program
         .command('mcp')
         .description('Start the brainctl MCP server (stdio transport)')
         .action(async () => {
+        if (!process.env.BRAINCTL_NO_UPDATE_CHECK) {
+            await autoUpdateIfNeeded();
+        }
         await startMcpServer({ cwd: process.cwd() });
     });
 }
+async function autoUpdateIfNeeded() {
+    try {
+        const service = createUpdateCheckService();
+        const check = await service.check();
+        if (!check.isOutdated)
+            return;
+        const result = await service.selfUpdate();
+        if (result.success) {
+            // Re-exec with the updated binary
+            const child = spawn(process.execPath, process.argv.slice(1), {
+                stdio: 'inherit',
+            });
+            await new Promise((resolve) => {
+                child.on('exit', (code) => {
+                    process.exit(code ?? 0);
+                });
+                child.on('error', () => {
+                    resolve(); // fall through to current version
+                });
+            });
+            return;
+        }
+        if (result.error) {
+            process.stderr.write(`brainctl: auto-update failed: ${result.error}\n`);
+        }
+    }
+    catch {
+        // Update check failed entirely — continue silently
+    }
+}

package/dist/commands/profile.js

@@ -43,13 +43,22 @@ export function registerProfileCommand(program, services) {
     });
     profileCmd
         .command('export')
-        .argument('<name>', 'Profile name to export')
+        .argument('[name]', 'Profile name to export')
+        .option('-a, --agent <name>', 'Pack a live agent config instead (claude, codex, gemini)')
         .option('-o, --output <path>', 'Output file path')
         .description('Export a profile as a portable tarball')
         .action(async (name, options) => {
+        const agent = options.agent === 'claude' || options.agent === 'codex' || options.agent === 'gemini'
+            ? options.agent
+            : undefined;
+        if (!agent && !name) {
+            throw new Error('Provide a profile name or --agent <name>.');
+        }
         const result = await profileExportService.execute({
             cwd: process.cwd(),
-            name,
+            source: agent
+                ? { source: 'agent', agent, cwd: process.cwd() }
+                : { source: 'profile', name: name },
             outputPath: options.output,
         });
         console.log(`Exported profile to ${result.archivePath}`);
@@ -58,12 +67,14 @@ export function registerProfileCommand(program, services) {
         .command('import')
         .argument('<archive>', 'Path to profile tarball')
         .option('--force', 'Overwrite existing profile', false)
+        .option('-c, --credential <key=value>', 'Provide a credential value for import', collectCredentialOption, [])
         .description('Import a profile from a tarball')
         .action(async (archive, options) => {
         const result = await profileImportService.execute({
             cwd: process.cwd(),
             archivePath: archive,
             force: options.force,
+            credentials: toCredentialMap(options.credential),
         });
         console.log(`Imported profile "${result.profileName}"`);
         if (result.installedMcps.length > 0) {
@@ -71,3 +82,25 @@ export function registerProfileCommand(program, services) {
         }
     });
 }
+function collectCredentialOption(value, previous) {
+    return [...previous, value];
+}
+function toCredentialMap(values) {
+    if (values.length === 0) {
+        return undefined;
+    }
+    const credentials = {};
+    for (const value of values) {
+        const separatorIndex = value.indexOf('=');
+        if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
+            throw new Error(`Invalid credential "${value}". Use key=value.`);
+        }
+        const key = value.slice(0, separatorIndex).trim();
+        const credentialValue = value.slice(separatorIndex + 1).trim();
+        if (!key || !credentialValue) {
+            throw new Error(`Invalid credential "${value}". Use key=value.`);
+        }
+        credentials[key] = credentialValue;
+    }
+    return credentials;
+}