brainctl 0.1.4 → 0.1.6

package/README.md

@@ -1,121 +1,120 @@
 # 🧠 brainctl
 
-> Stop reconfiguring your AI tools.
+> One AI setup. Multiple agents. Zero reconfiguration.
 
-`brainctl` is a CLI for managing a portable AI environment across tools like Claude Code and Codex.
+**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.
 
-Define your memory, skills, and execution flow once, then reuse them across different AI agents.
+[![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)
 
 ---
 
-## ✨ Why brainctl?
+## ✨ Features
 
-If you're using multiple AI tools, you've probably already hit the same problems:
-
-- Rewriting the same prompt for different agents
-- Losing context between tools
-- Rebuilding your environment every time you switch
-
-`brainctl` solves that with one core idea:
-
-> **One AI setup. Multiple agents.**
-
----
-
-## 🚀 Features
-
-- 🧠 File-based memory from Markdown files
-- 🧩 Reusable skills stored in `ai-stack.yaml`
-- 🔌 Multi-agent execution with Claude and Codex
-- ⚙️ Unified context builder
-- 🛠 CLI-first workflow
-- 🔍 `status` and `doctor` for visibility
-- 🔁 Optional fallback agent support with `--fallback`
+- 🔀 **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
 
 ---
 
-## 📦 Installation
+## 📸 Demo
 
-### Option 1: Install from npm
+### Web Dashboard — Drag MCPs between agents
 
-```bash
-npm install -g brainctl
 ```
-
-Then:
-
-```bash
-brainctl --help
+┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+│    Claude     │  │    Codex     │  │    Gemini    │
+│ ┌──────────┐ │  │ ┌──────────┐ │  │              │
+│ │ github   │◄├──┤►│ github   │ │  │  Drop here   │
+│ │ brainctl │ │  │ │ brainctl │ │  │  to copy     │
+│ └──────────┘ │  │ └──────────┘ │  │              │
+│ Skills: 11   │  │ Skills: 3    │  │ Skills: 0    │
+└──────────────┘  └──────────────┘  └──────────────┘
 ```
 
-### Option 2: Local CLI install from source
+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.
 
-```bash
-npm install
-npm run build
-npm link
-```
+---
 
-Then:
+## 📦 Installation
 
 ```bash
-brainctl --help
+npm install -g brainctl
 ```
 
-### Option 3: Run without linking
+Or from source:
 
 ```bash
-npm install
-npm run build
-node dist/cli.js --help
+git clone https://github.com/Rorogogogo/brainctl.git
+cd brainctl
+npm install && npm run build && npm link
 ```
 
-`brainctl` does not bundle agent CLIs. You still need at least one supported agent installed separately and available on `PATH`, such as `claude` or `codex`.
+> **Prerequisite:** At least one supported agent CLI must be installed and on your `PATH` (`claude`, `codex`, or `gemini`).
 
 ---
 
-## ⚡ Quick Start
-
-### 1. Initialize a project
+## 🚀 Quick Start
 
 ```bash
+# 1. Initialize a project
 brainctl init
-```
-
-This creates:
-
-- `ai-stack.yaml`
-- `memory/`
-- `memory/notes.md`
 
-### 2. Inspect the setup
-
-```bash
+# 2. Check your setup
 brainctl status
 brainctl doctor
-```
-
-### 3. Run a task
 
-```bash
+# 3. Run a skill
 brainctl run summarize ./memory/notes.md --with claude
+
+# 4. Launch the web dashboard
+brainctl ui
+# → http://127.0.0.1:3333
 ```
 
-Or:
+---
+
+## 📖 Usage
 
-```bash
-brainctl run summarize ./memory/notes.md --with codex
-```
+### 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 |
+| `brainctl ui` | Start the web dashboard |
 
-With fallback:
+### Run Examples
 
 ```bash
-brainctl run summarize ./memory/notes.md --with claude --fallback codex
+# Basic execution
+brainctl run summarize ./notes.md --with claude
+
+# With fallback agent
+brainctl run analyze ./report.md --with codex --fallback claude
+
+# Using Gemini
+brainctl run review ./code.md --with gemini
 ```
 
 ---
 
-## 🧠 Example `ai-stack.yaml`
+## 🧠 Config: `ai-stack.yaml`
 
 ```yaml
 memory:
@@ -124,119 +123,144 @@ memory:
 
 skills:
   summarize:
-    description: Summarize content
+    description: Summarize content into bullet points
     prompt: |
       Summarize the following content into concise bullet points.
 
-  analyze:
-    description: Analyze content deeply
+  review:
+    description: Code review with actionable feedback
     prompt: |
-      Analyze the following content and extract key insights.
+      Review the following code and provide actionable feedback.
 
 mcps: {}
 ```
 
----
+### How Context Assembly Works
 
-## 🧩 How It Works
+```
+┌─────────────┐
+│   MEMORY    │  ← Markdown files from configured paths
+├─────────────┤
+│   SKILL     │  ← Prompt template from ai-stack.yaml
+├─────────────┤
+│   INPUT     │  ← Your file
+└─────────────┘
+        ↓
+   Agent CLI (claude / codex / gemini)
+```
 
-`brainctl` builds a unified context before calling an agent:
+---
 
-```text
---- MEMORY ---
-[your markdown files]
+## 🔌 MCP Server
 
---- SKILL ---
-[prompt template]
+brainctl exposes **20 MCP tools** that any compatible agent can call:
 
---- INPUT ---
-[your file]
+```bash
+# Add brainctl as an MCP server in your agent config
+# Claude (~/.claude.json):
+{
+  "mcpServers": {
+    "brainctl": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "brainctl", "mcp"]
+    }
+  }
+}
 ```
 
-That context is then sent to the selected agent over stdin.
-
----
-
-## 🛠 Usage
+**Available tools:**
 
-### Commands
+| 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` |
 
-| Command | Purpose |
-| --- | --- |
-| `brainctl init` | Initialize `ai-stack.yaml` and memory files |
-| `brainctl status` | Show memory, skills, MCP count, and agent availability |
-| `brainctl doctor` | Validate config, memory paths, skills, and installed agents |
-| `brainctl run <skill> <file> --with <agent>` | Build context and execute with an agent |
+---
 
-### Examples
+## 🖥️ Web Dashboard
 
 ```bash
-brainctl run summarize ./memory/notes.md --with claude
-brainctl run analyze ./memory/notes.md --with codex
-brainctl run summarize ./memory/notes.md --with claude --fallback codex
+brainctl ui
 ```
 
+Opens a local dashboard at `http://127.0.0.1:3333` with:
+
+- **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
+
 ---
 
-## 📂 Project Structure
+## 🏗️ Architecture
 
-```text
+```
 brainctl/
 ├── src/
-│   ├── cli.ts
-│   ├── config.ts
-│   ├── context/
-│   ├── commands/
-│   ├── executor/
-│   └── services/
-├── tests/
-├── ai-stack.yaml
-├── memory/
-├── package.json
-└── tsconfig.json
+│   ├── 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
 ```
 
+### 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
 
 ```bash
 npm install
-npm test
-npm run build
+npm test              # Run all tests (Vitest)
+npm run build         # Build server (tsc) + web (Vite)
+npm run dev -- <args> # Run CLI via tsx
 ```
 
 ---
 
-## 🧠 Philosophy
-
-`brainctl` does not replace your AI tools.
-
-It sits between you and them as a thin orchestration layer:
+## 🤝 Contributing
 
-- You keep using Claude, Codex, and other agent CLIs
-- `brainctl` keeps the environment consistent
+Contributions are welcome! Please open an issue or submit a pull request.
 
----
-
-## 🗺 Roadmap
-
-- [ ] JSON output mode
-- [ ] Multi-agent pipelines
-- [ ] MCP runtime integration
-- [ ] Better execution tracing and logs
-- [ ] UI / dashboard
+```bash
+git clone https://github.com/Rorogogogo/brainctl.git
+cd brainctl
+npm install
+npm test
+```
 
 ---
 
-## 💡 Inspiration
+## 💡 Philosophy
 
-AI tools are getting more powerful, but also more fragmented.
+brainctl doesn't replace your AI tools. It sits between you and them as a thin orchestration layer:
 
-`brainctl` is an attempt to bring state, structure, and consistency to that workflow.
+- **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
 
 ---
 
 ## 📄 License
 
-MIT
+[MIT](https://opensource.org/licenses/MIT) — use it however you want.

package/dist/cli.d.ts

@@ -2,6 +2,8 @@
 import { Command } from 'commander';
 import { type DoctorService } from './services/doctor-service.js';
 import { type InitService } from './services/init-service.js';
+import { type ProfileExportService } from './services/profile-export-service.js';
+import { type ProfileImportService } from './services/profile-import-service.js';
 import { type ProfileService } from './services/profile-service.js';
 import { type RunService } from './services/run-service.js';
 import { type StatusService } from './services/status-service.js';
@@ -12,6 +14,8 @@ export interface CliServices {
     statusService: StatusService;
     doctorService: DoctorService;
     profileService: ProfileService;
+    profileExportService: ProfileExportService;
+    profileImportService: ProfileImportService;
     syncService: SyncService;
 }
 export declare function createProgram(overrides?: Partial<CliServices>): Command;

package/dist/cli.js

@@ -14,6 +14,8 @@ import { registerUiCommand } from './commands/ui.js';
 import { printError } from './output.js';
 import { createDoctorService } from './services/doctor-service.js';
 import { createInitService } from './services/init-service.js';
+import { createProfileExportService } from './services/profile-export-service.js';
+import { createProfileImportService } from './services/profile-import-service.js';
 import { createProfileService } from './services/profile-service.js';
 import { createRunService } from './services/run-service.js';
 import { createStatusService } from './services/status-service.js';
@@ -31,7 +33,11 @@ export function createProgram(overrides = {}) {
     registerStatusCommand(program, services.statusService);
     registerRunCommand(program, services.runService);
     registerDoctorCommand(program, services.doctorService);
-    registerProfileCommand(program, services.profileService);
+    registerProfileCommand(program, {
+        profileService: services.profileService,
+        profileExportService: services.profileExportService,
+        profileImportService: services.profileImportService,
+    });
     registerSyncCommand(program, services.syncService);
     registerUiCommand(program);
     registerMcpCommand(program);
@@ -62,6 +68,8 @@ function createDefaultServices(overrides) {
         statusService: createStatusService({ resolver }),
         doctorService: createDoctorService({ resolver }),
         profileService,
+        profileExportService: createProfileExportService({ profileService }),
+        profileImportService: createProfileImportService(),
         syncService: createSyncService({ profileService }),
         ...overrides
     };

package/dist/commands/profile.d.ts

@@ -1,3 +1,10 @@
 import type { Command } from 'commander';
+import type { ProfileExportService } from '../services/profile-export-service.js';
+import type { ProfileImportService } from '../services/profile-import-service.js';
 import type { ProfileService } from '../services/profile-service.js';
-export declare function registerProfileCommand(program: Command, profileService: ProfileService): void;
+export interface ProfileCommandServices {
+    profileService: ProfileService;
+    profileExportService: ProfileExportService;
+    profileImportService: ProfileImportService;
+}
+export declare function registerProfileCommand(program: Command, services: ProfileCommandServices): void;

package/dist/commands/profile.js

@@ -1,5 +1,6 @@
 import pc from 'picocolors';
-export function registerProfileCommand(program, profileService) {
+export function registerProfileCommand(program, services) {
+    const { profileService, profileExportService, profileImportService } = services;
     const profileCmd = program
         .command('profile')
         .description('Manage brainctl profiles');
@@ -40,4 +41,33 @@ export function registerProfileCommand(program, profileService) {
         const prev = result.previousProfile ? ` (was "${result.previousProfile}")` : '';
         console.log(`Switched to profile "${name}"${prev}`);
     });
+    profileCmd
+        .command('export')
+        .argument('<name>', 'Profile name to export')
+        .option('-o, --output <path>', 'Output file path')
+        .description('Export a profile as a portable tarball')
+        .action(async (name, options) => {
+        const result = await profileExportService.execute({
+            cwd: process.cwd(),
+            name,
+            outputPath: options.output,
+        });
+        console.log(`Exported profile to ${result.archivePath}`);
+    });
+    profileCmd
+        .command('import')
+        .argument('<archive>', 'Path to profile tarball')
+        .option('--force', 'Overwrite existing profile', false)
+        .description('Import a profile from a tarball')
+        .action(async (archive, options) => {
+        const result = await profileImportService.execute({
+            cwd: process.cwd(),
+            archivePath: archive,
+            force: options.force,
+        });
+        console.log(`Imported profile "${result.profileName}"`);
+        if (result.installedMcps.length > 0) {
+            console.log(`Installed bundled MCPs: ${result.installedMcps.join(', ')}`);
+        }
+    });
 }