brainctl 0.1.5 → 0.1.7

package/README.md

@@ -1,121 +1,146 @@
 # 🧠 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:
+- 🔀 **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
 
-- 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.**
+## 📸 Demo
 
----
+### Web Dashboard — Drag MCPs between agents
 
-## 🚀 Features
+```
+┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+│    Claude     │  │    Codex     │  │    Gemini    │
+│ ┌──────────┐ │  │ ┌──────────┐ │  │              │
+│ │ github   │◄├──┤►│ github   │ │  │  Drop here   │
+│ │ brainctl │ │  │ │ brainctl │ │  │  to copy     │
+│ └──────────┘ │  │ └──────────┘ │  │              │
+│ Skills: 11   │  │ Skills: 3    │  │ Skills: 0    │
+└──────────────┘  └──────────────┘  └──────────────┘
+```
 
-- 🧠 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`
+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.
 
 ---
 
 ## 📦 Installation
 
-### Option 1: Install from npm
-
 ```bash
 npm install -g brainctl
 ```
 
-Then:
+Or from source:
 
 ```bash
-brainctl --help
+git clone https://github.com/Rorogogogo/brainctl.git
+cd brainctl
+npm install && npm run build && npm link
 ```
 
-### Option 2: Local CLI install from source
+> **Prerequisite:** At least one supported agent CLI must be installed and on your `PATH` (`claude`, `codex`, or `gemini`).
 
-```bash
-npm install
-npm run build
-npm link
-```
+---
 
-Then:
+## 🚀 Quick Start
 
 ```bash
-brainctl --help
-```
+# 1. Initialize a project
+brainctl init
 
-### Option 3: Run without linking
+# 2. Check your setup
+brainctl status
+brainctl doctor
 
-```bash
-npm install
-npm run build
-node dist/cli.js --help
-```
+# 3. Run a skill
+brainctl run summarize ./memory/notes.md --with claude
 
-`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`.
+# 4. Launch the web dashboard
+brainctl ui
+# → http://127.0.0.1:3333
+```
 
 ---
 
-## ⚡ Quick Start
+## 📖 Usage
 
-### 1. Initialize a project
-
-```bash
-brainctl init
-```
+### CLI Commands
 
-This creates:
+| 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 |
 
-- `ai-stack.yaml`
-- `memory/`
-- `memory/notes.md`
-
-### 2. Inspect the setup
+### Run Examples
 
 ```bash
-brainctl status
-brainctl doctor
-```
+# Basic execution
+brainctl run summarize ./notes.md --with claude
 
-### 3. Run a task
+# With fallback agent
+brainctl run analyze ./report.md --with codex --fallback claude
 
-```bash
-brainctl run summarize ./memory/notes.md --with claude
+# Using Gemini
+brainctl run review ./code.md --with gemini
 ```
 
-Or:
+### Profile MCP Format
 
-```bash
-brainctl run summarize ./memory/notes.md --with codex
+Packed/published profiles should classify every MCP as either `local` or `remote`.
+
+```yaml
+mcps:
+  github:
+    kind: local
+    source: npm
+    package: "@modelcontextprotocol/server-github"
+
+  internal-docs:
+    kind: remote
+    transport: http
+    url: "https://mcp.example.com"
 ```
 
-With fallback:
+Rules:
 
-```bash
-brainctl run summarize ./memory/notes.md --with claude --fallback codex
-```
+- local profile files may still use the older `type: npm` / `type: bundled` MCP shape
+- `brainctl profile export` writes the packed profile using the explicit format below
+- `local` MCPs must declare `source: npm` or `source: bundled`
+- `remote` MCPs must declare `transport` and `url`
+- bundled local MCPs must declare `path` and `command`
+- `brainctl sync` currently supports local MCPs only; remote MCPs remain in the profile package but are not written into agent configs yet
 
 ---
 
-## 🧠 Example `ai-stack.yaml`
+## 🧠 Config: `ai-stack.yaml`
 
 ```yaml
 memory:
@@ -124,119 +149,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/executor/resolver.js

@@ -1,9 +1,7 @@
-import { access } from 'node:fs/promises';
-import { constants } from 'node:fs';
-import path from 'node:path';
 import { AgentNotAvailableError } from '../errors.js';
 import { ClaudeExecutor } from './claude.js';
 import { CodexExecutor } from './codex.js';
+import { findExecutable } from '../system/executables.js';
 const SUPPORTED_AGENTS = ['claude', 'codex', 'gemini'];
 const AGENT_COMMANDS = {
     claude: 'claude',
@@ -60,38 +58,3 @@ async function checkAvailability(agentName) {
         resolvedPath: resolvedPath ?? undefined
     };
 }
-async function findExecutable(command) {
-    if (command.includes(path.sep)) {
-        return (await isExecutable(command)) ? command : null;
-    }
-    const pathEntries = (process.env.PATH ?? '')
-        .split(path.delimiter)
-        .filter((entry) => entry.length > 0);
-    const extensions = process.platform === 'win32'
-        ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM')
-            .split(';')
-            .filter((entry) => entry.length > 0)
-        : [''];
-    for (const pathEntry of pathEntries) {
-        for (const extension of extensions) {
-            const candidate = process.platform === 'win32' &&
-                extension.length > 0 &&
-                !command.toLowerCase().endsWith(extension.toLowerCase())
-                ? path.join(pathEntry, `${command}${extension}`)
-                : path.join(pathEntry, command);
-            if (await isExecutable(candidate)) {
-                return candidate;
-            }
-        }
-    }
-    return null;
-}
-async function isExecutable(filePath) {
-    try {
-        await access(filePath, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/mcp/server.js

@@ -4,7 +4,9 @@ import { FastMCP } from 'fastmcp';
 import { z } from 'zod';
 import { loadConfig } from '../config.js';
 import { loadMemory } from '../context/memory.js';
+import { createAgentConfigService } from '../services/agent-config-service.js';
 import { createDoctorService } from '../services/doctor-service.js';
+import { startUiServer } from '../ui/server.js';
 import { createMemoryWriteService } from '../services/memory-write-service.js';
 import { createProfileExportService } from '../services/profile-export-service.js';
 import { createProfileImportService } from '../services/profile-import-service.js';
@@ -177,6 +179,111 @@ export function createMcpServer(options = {}) {
             return JSON.stringify(result, null, 2);
         },
     });
+    server.addTool({
+        name: 'brainctl_get_profile',
+        description: 'Get the full config of a profile including all skills, MCPs, and memory paths.',
+        parameters: z.object({
+            name: z.string().describe('Profile name'),
+        }),
+        execute: async (args) => {
+            const profileService = createProfileService();
+            const profile = await profileService.get({ cwd, name: args.name });
+            return JSON.stringify(profile, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_create_profile',
+        description: 'Create a new profile with a default example skill.',
+        parameters: z.object({
+            name: z.string().describe('Profile name to create'),
+            description: z.string().optional().describe('Profile description'),
+        }),
+        execute: async (args) => {
+            const profileService = createProfileService();
+            const result = await profileService.create({
+                cwd,
+                name: args.name,
+                description: args.description,
+            });
+            return JSON.stringify(result, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_update_profile',
+        description: 'Update a profile config. Pass the full profile object with skills, mcps, and memory fields. Use this to add, remove, or modify skills and MCPs within a profile.',
+        parameters: z.object({
+            name: z.string().describe('Profile name to update'),
+            config: z.object({
+                name: z.string(),
+                description: z.string().optional(),
+                skills: z.record(z.string(), z.object({
+                    description: z.string().optional(),
+                    prompt: z.string(),
+                })),
+                mcps: z.record(z.string(), z.unknown()),
+                memory: z.object({
+                    paths: z.array(z.string()),
+                }),
+            }).describe('Full profile config object'),
+        }),
+        execute: async (args) => {
+            const profileService = createProfileService();
+            await profileService.update({
+                cwd,
+                name: args.name,
+                config: args.config,
+            });
+            return JSON.stringify({ ok: true, updated: args.name });
+        },
+    });
+    server.addTool({
+        name: 'brainctl_delete_profile',
+        description: 'Delete a profile. Cannot delete the currently active profile.',
+        parameters: z.object({
+            name: z.string().describe('Profile name to delete'),
+        }),
+        execute: async (args) => {
+            const profileService = createProfileService();
+            await profileService.delete({ cwd, name: args.name });
+            return JSON.stringify({ ok: true, deleted: args.name });
+        },
+    });
+    server.addTool({
+        name: 'brainctl_copy_profile_items',
+        description: 'Copy skills and/or MCPs from one profile to another. Specify which skill and MCP keys to copy. Existing items with the same key in the target are overwritten.',
+        parameters: z.object({
+            source: z.string().describe('Source profile name'),
+            target: z.string().describe('Target profile name'),
+            skills: z.array(z.string()).default([]).describe('Skill keys to copy'),
+            mcps: z.array(z.string()).default([]).describe('MCP keys to copy'),
+        }),
+        execute: async (args) => {
+            const profileService = createProfileService();
+            const sourceProfile = await profileService.get({ cwd, name: args.source });
+            const targetProfile = await profileService.get({ cwd, name: args.target });
+            const copiedSkills = [];
+            const copiedMcps = [];
+            for (const key of args.skills) {
+                if (sourceProfile.skills[key]) {
+                    targetProfile.skills[key] = sourceProfile.skills[key];
+                    copiedSkills.push(key);
+                }
+            }
+            for (const key of args.mcps) {
+                if (sourceProfile.mcps[key]) {
+                    targetProfile.mcps[key] = sourceProfile.mcps[key];
+                    copiedMcps.push(key);
+                }
+            }
+            await profileService.update({ cwd, name: args.target, config: targetProfile });
+            return JSON.stringify({
+                source: args.source,
+                target: args.target,
+                copiedSkills,
+                copiedMcps,
+            }, null, 2);
+        },
+    });
     server.addTool({
         name: 'brainctl_export_profile',
         description: 'Export a profile as a portable tarball. Packages the profile config and bundled MCP source code for sharing.',
@@ -211,6 +318,82 @@ export function createMcpServer(options = {}) {
             return JSON.stringify(result, null, 2);
         },
     });
+    let uiServerInstance = null;
+    server.addTool({
+        name: 'brainctl_open_ui',
+        description: 'Start the brainctl web dashboard. Returns the URL to open in a browser. If already running, returns the existing URL.',
+        parameters: z.object({
+            port: z.number().default(3333).describe('Port number for the UI server'),
+        }),
+        execute: async (args) => {
+            if (uiServerInstance) {
+                return JSON.stringify({ url: uiServerInstance.url, status: 'already_running' });
+            }
+            try {
+                uiServerInstance = await startUiServer({ cwd, port: args.port });
+                return JSON.stringify({ url: uiServerInstance.url, status: 'started' });
+            }
+            catch (err) {
+                return JSON.stringify({ error: err.message, status: 'failed' });
+            }
+        },
+    });
+    server.addTool({
+        name: 'brainctl_close_ui',
+        description: 'Stop the brainctl web dashboard if it is running.',
+        parameters: z.object({}),
+        execute: async () => {
+            if (!uiServerInstance) {
+                return JSON.stringify({ status: 'not_running' });
+            }
+            await uiServerInstance.close();
+            uiServerInstance = null;
+            return JSON.stringify({ status: 'stopped' });
+        },
+    });
+    server.addTool({
+        name: 'brainctl_read_agent_configs',
+        description: 'Read the live MCP configs from all agents (Claude, Codex, Gemini). Shows what is actually configured in each agent right now, by reading their real config files.',
+        parameters: z.object({}),
+        execute: async () => {
+            const agentConfigService = createAgentConfigService();
+            const configs = await agentConfigService.readAll({ cwd });
+            return JSON.stringify(configs, null, 2);
+        },
+    });
+    server.addTool({
+        name: 'brainctl_add_agent_mcp',
+        description: 'Add or overwrite an MCP server entry in a specific agent config. Writes directly to the agent config file (e.g., ~/.claude.json).',
+        parameters: z.object({
+            agent: z.enum(['claude', 'codex', 'gemini']).describe('Target agent'),
+            key: z.string().describe('MCP server name/key'),
+            command: z.string().describe('Command to run the MCP server'),
+            args: z.array(z.string()).default([]).describe('Arguments for the command'),
+        }),
+        execute: async (args) => {
+            const agentConfigService = createAgentConfigService();
+            await agentConfigService.addMcp({
+                cwd,
+                agent: args.agent,
+                key: args.key,
+                entry: { command: args.command, args: args.args },
+            });
+            return JSON.stringify({ ok: true, agent: args.agent, key: args.key });
+        },
+    });
+    server.addTool({
+        name: 'brainctl_remove_agent_mcp',
+        description: 'Remove an MCP server entry from a specific agent config.',
+        parameters: z.object({
+            agent: z.enum(['claude', 'codex', 'gemini']).describe('Target agent'),
+            key: z.string().describe('MCP server name/key to remove'),
+        }),
+        execute: async (args) => {
+            const agentConfigService = createAgentConfigService();
+            await agentConfigService.removeMcp({ cwd, agent: args.agent, key: args.key });
+            return JSON.stringify({ ok: true, agent: args.agent, removed: args.key });
+        },
+    });
     return server;
 }
 export async function startMcpServer(options = {}) {