brainctl 0.1.0

package/README.md

@@ -0,0 +1,242 @@
+# 🧠 brainctl
+
+> Stop reconfiguring your AI tools.
+
+`brainctl` is a CLI for managing a portable AI environment across tools like Claude Code and Codex.
+
+Define your memory, skills, and execution flow once, then reuse them across different AI agents.
+
+---
+
+## ✨ Why brainctl?
+
+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`
+
+---
+
+## 📦 Installation
+
+### Option 1: Install from npm
+
+```bash
+npm install -g brainctl
+```
+
+Then:
+
+```bash
+brainctl --help
+```
+
+### Option 2: Local CLI install from source
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+Then:
+
+```bash
+brainctl --help
+```
+
+### Option 3: Run without linking
+
+```bash
+npm install
+npm run build
+node dist/cli.js --help
+```
+
+`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`.
+
+---
+
+## ⚡ Quick Start
+
+### 1. Initialize a project
+
+```bash
+brainctl init
+```
+
+This creates:
+
+- `ai-stack.yaml`
+- `memory/`
+- `memory/notes.md`
+
+### 2. Inspect the setup
+
+```bash
+brainctl status
+brainctl doctor
+```
+
+### 3. Run a task
+
+```bash
+brainctl run summarize ./memory/notes.md --with claude
+```
+
+Or:
+
+```bash
+brainctl run summarize ./memory/notes.md --with codex
+```
+
+With fallback:
+
+```bash
+brainctl run summarize ./memory/notes.md --with claude --fallback codex
+```
+
+---
+
+## 🧠 Example `ai-stack.yaml`
+
+```yaml
+memory:
+  paths:
+    - ./memory
+
+skills:
+  summarize:
+    description: Summarize content
+    prompt: |
+      Summarize the following content into concise bullet points.
+
+  analyze:
+    description: Analyze content deeply
+    prompt: |
+      Analyze the following content and extract key insights.
+
+mcps: {}
+```
+
+---
+
+## 🧩 How It Works
+
+`brainctl` builds a unified context before calling an agent:
+
+```text
+--- MEMORY ---
+[your markdown files]
+
+--- SKILL ---
+[prompt template]
+
+--- INPUT ---
+[your file]
+```
+
+That context is then sent to the selected agent over stdin.
+
+---
+
+## 🛠 Usage
+
+### Commands
+
+| 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
+
+```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
+```
+
+---
+
+## 📂 Project Structure
+
+```text
+brainctl/
+├── src/
+│   ├── cli.ts
+│   ├── config.ts
+│   ├── context/
+│   ├── commands/
+│   ├── executor/
+│   └── services/
+├── tests/
+├── ai-stack.yaml
+├── memory/
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## 🧪 Development
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+---
+
+## 🧠 Philosophy
+
+`brainctl` does not replace your AI tools.
+
+It sits between you and them as a thin orchestration layer:
+
+- You keep using Claude, Codex, and other agent CLIs
+- `brainctl` keeps the environment consistent
+
+---
+
+## 🗺 Roadmap
+
+- [ ] JSON output mode
+- [ ] Multi-agent pipelines
+- [ ] MCP runtime integration
+- [ ] Better execution tracing and logs
+- [ ] UI / dashboard
+
+---
+
+## 💡 Inspiration
+
+AI tools are getting more powerful, but also more fragmented.
+
+`brainctl` is an attempt to bring state, structure, and consistency to that workflow.
+
+---
+
+## 📄 License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { type DoctorService } from './services/doctor-service.js';
+import { type InitService } from './services/init-service.js';
+import { type RunService } from './services/run-service.js';
+import { type StatusService } from './services/status-service.js';
+export interface CliServices {
+    initService: InitService;
+    runService: RunService;
+    statusService: StatusService;
+    doctorService: DoctorService;
+}
+export declare function createProgram(overrides?: Partial<CliServices>): Command;
+export declare function main(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { registerDoctorCommand } from './commands/doctor.js';
+import { registerInitCommand } from './commands/init.js';
+import { registerRunCommand } from './commands/run.js';
+import { registerStatusCommand } from './commands/status.js';
+import { printError } from './output.js';
+import { createDoctorService } from './services/doctor-service.js';
+import { createInitService } from './services/init-service.js';
+import { createRunService } from './services/run-service.js';
+import { createStatusService } from './services/status-service.js';
+import { createExecutorResolver } from './executor/resolver.js';
+export function createProgram(overrides = {}) {
+    const services = createDefaultServices(overrides);
+    const program = new Command();
+    program
+        .name('brainctl')
+        .description('Manage repeatable AI environments for local agent workflows')
+        .version('0.1.0');
+    registerInitCommand(program, services.initService);
+    registerStatusCommand(program, services.statusService);
+    registerRunCommand(program, services.runService);
+    registerDoctorCommand(program, services.doctorService);
+    return program;
+}
+export async function main(argv = process.argv) {
+    const program = createProgram();
+    try {
+        await program.parseAsync(argv);
+    }
+    catch (error) {
+        printError(error);
+        process.exitCode = 1;
+    }
+}
+function createDefaultServices(overrides) {
+    const resolver = createExecutorResolver();
+    return {
+        initService: createInitService(),
+        runService: createRunService({ resolver }),
+        statusService: createStatusService({ resolver }),
+        doctorService: createDoctorService({ resolver }),
+        ...overrides
+    };
+}
+const entryPointPath = process.argv[1] ? path.resolve(process.argv[1]) : '';
+const currentFilePath = fileURLToPath(import.meta.url);
+if (entryPointPath === currentFilePath) {
+    void main();
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { DoctorService } from '../services/doctor-service.js';
+export declare function registerDoctorCommand(program: Command, doctorService: DoctorService): void;

package/dist/commands/doctor.js

@@ -0,0 +1,13 @@
+import { formatDiagnosticStatus } from '../output.js';
+export function registerDoctorCommand(program, doctorService) {
+    program
+        .command('doctor')
+        .description('Validate the local brainctl setup')
+        .action(async () => {
+        const result = await doctorService.execute({ cwd: process.cwd() });
+        for (const check of result.checks) {
+            console.log(`${formatDiagnosticStatus(check.status)} ${check.label}: ${check.message}`);
+        }
+        process.exitCode = result.hasIssues ? 1 : 0;
+    });
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { InitService } from '../services/init-service.js';
+export declare function registerInitCommand(program: Command, initService: InitService): void;

package/dist/commands/init.js

@@ -0,0 +1,27 @@
+import pc from 'picocolors';
+export function registerInitCommand(program, initService) {
+    program
+        .command('init')
+        .description('Initialize brainctl in the current directory')
+        .option('--force', 'Overwrite existing scaffolded files')
+        .action(async (options) => {
+        const result = await initService.execute({
+            cwd: process.cwd(),
+            force: options.force
+        });
+        if (result.alreadyInitialized) {
+            console.log('brainctl is already initialized in this directory');
+            console.log('Use --force to overwrite existing files.');
+            return;
+        }
+        for (const item of result.created) {
+            console.log(pc.green(`created ${item}`));
+        }
+        for (const item of result.replaced) {
+            console.log(pc.yellow(`replaced ${item}`));
+        }
+        if (result.created.length === 0 && result.replaced.length === 0) {
+            console.log('No changes were required.');
+        }
+    });
+}

package/dist/commands/run.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { RunService } from '../services/run-service.js';
+export declare function registerRunCommand(program: Command, runService: RunService): void;

package/dist/commands/run.js

@@ -0,0 +1,25 @@
+export function registerRunCommand(program, runService) {
+    program
+        .command('run')
+        .description('Run a file through a configured skill and AI agent')
+        .argument('<skill>', 'Skill name from ai-stack.yaml')
+        .argument('<file>', 'Input file to send to the agent')
+        .requiredOption('--with <agent>', 'Primary agent to run', validateAgentName)
+        .option('--fallback <agent>', 'Fallback agent if the primary agent is unavailable', validateAgentName)
+        .action(async (skill, inputFile, options) => {
+        const trace = await runService.execute({
+            cwd: process.cwd(),
+            skill,
+            inputFile,
+            primaryAgent: options.with,
+            fallbackAgent: options.fallback
+        });
+        process.exitCode = trace.finalExitCode;
+    });
+}
+function validateAgentName(value) {
+    if (value !== 'claude' && value !== 'codex') {
+        throw new Error(`Unsupported agent: ${value}`);
+    }
+    return value;
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { StatusService } from '../services/status-service.js';
+export declare function registerStatusCommand(program: Command, statusService: StatusService): void;

package/dist/commands/status.js

@@ -0,0 +1,18 @@
+import pc from 'picocolors';
+export function registerStatusCommand(program, statusService) {
+    program
+        .command('status')
+        .description('Show current brainctl configuration status')
+        .action(async () => {
+        const status = await statusService.execute({ cwd: process.cwd() });
+        console.log(pc.bold('brainctl status'));
+        console.log(`Config: ${status.configPath}`);
+        console.log(`Memory files loaded: ${status.memory.count}`);
+        console.log(`Available skills: ${status.skills.length > 0 ? status.skills.join(', ') : 'none'}`);
+        console.log(`MCP count: ${status.mcpCount}`);
+        console.log('Available agents:');
+        for (const agent of Object.values(status.agents)) {
+            console.log(`- ${agent.agent}: ${agent.available ? pc.green('available') : pc.yellow('missing')}`);
+        }
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import type { BrainctlConfig } from './types.js';
+interface LoadConfigOptions {
+    cwd?: string;
+}
+export declare function loadConfig(options?: LoadConfigOptions): Promise<BrainctlConfig>;
+export {};

package/dist/config.js

@@ -0,0 +1,78 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+import { ConfigError } from './errors.js';
+export async function loadConfig(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const configPath = path.join(cwd, 'ai-stack.yaml');
+    let source;
+    try {
+        source = await readFile(configPath, 'utf8');
+    }
+    catch (error) {
+        throw new ConfigError(`Could not read ai-stack.yaml in ${cwd}.`);
+    }
+    let parsed;
+    try {
+        parsed = (YAML.parse(source) ?? {});
+    }
+    catch (error) {
+        throw new ConfigError('ai-stack.yaml could not be parsed.');
+    }
+    if (!parsed.memory || !Array.isArray(parsed.memory.paths)) {
+        throw new ConfigError('ai-stack.yaml is missing the required "memory.paths" section.');
+    }
+    if (!parsed.skills || typeof parsed.skills !== 'object' || Array.isArray(parsed.skills)) {
+        throw new ConfigError('ai-stack.yaml is missing the required "skills" section.');
+    }
+    const skills = normalizeSkills(parsed.skills);
+    return {
+        configPath,
+        rootDir: cwd,
+        memory: {
+            paths: parsed.memory.paths.map((memoryPath) => {
+                if (typeof memoryPath !== 'string' || memoryPath.trim().length === 0) {
+                    throw new ConfigError('ai-stack.yaml contains an invalid memory path.');
+                }
+                return path.resolve(cwd, memoryPath);
+            })
+        },
+        skills,
+        mcps: normalizeMcps(parsed.mcps)
+    };
+}
+function normalizeSkills(value) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+        throw new ConfigError('ai-stack.yaml must define at least one skill.');
+    }
+    return Object.fromEntries(entries.map(([name, skillValue]) => {
+        if (!skillValue || typeof skillValue !== 'object' || Array.isArray(skillValue)) {
+            throw new ConfigError(`Skill "${name}" must be an object with a prompt.`);
+        }
+        const prompt = skillValue.prompt;
+        const description = skillValue.description;
+        if (typeof prompt !== 'string' || prompt.trim().length === 0) {
+            throw new ConfigError(`Skill "${name}" is missing a valid prompt.`);
+        }
+        if (description !== undefined && typeof description !== 'string') {
+            throw new ConfigError(`Skill "${name}" has an invalid description.`);
+        }
+        return [
+            name,
+            {
+                prompt,
+                description
+            }
+        ];
+    }));
+}
+function normalizeMcps(value) {
+    if (value === null || value === undefined) {
+        return {};
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new ConfigError('The "mcps" section must be an object when present.');
+    }
+    return value;
+}

package/dist/context/builder.d.ts

@@ -0,0 +1,6 @@
+export interface BuildContextInput {
+    memory: string;
+    skill: string;
+    input: string;
+}
+export declare function buildContext({ memory, skill, input }: BuildContextInput): string;

package/dist/context/builder.js

@@ -0,0 +1,13 @@
+export function buildContext({ memory, skill, input }) {
+    const sections = [memory, skill, input].map((value) => value.replace(/\n+$/, ''));
+    return [
+        '--- MEMORY ---',
+        sections[0],
+        '',
+        '--- SKILL ---',
+        sections[1],
+        '',
+        '--- INPUT ---',
+        sections[2]
+    ].join('\n');
+}

package/dist/context/memory.d.ts

@@ -0,0 +1,5 @@
+import type { MemoryLoadResult } from '../types.js';
+export interface LoadMemoryOptions {
+    paths: string[];
+}
+export declare function loadMemory(options: LoadMemoryOptions): Promise<MemoryLoadResult>;

package/dist/context/memory.js

@@ -0,0 +1,38 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { MemoryPathError } from '../errors.js';
+export async function loadMemory(options) {
+    const markdownFiles = (await Promise.all(options.paths.map(async (memoryPath) => collectMarkdownFiles(memoryPath))))
+        .flat()
+        .sort((left, right) => left.localeCompare(right));
+    const contents = await Promise.all(markdownFiles.map(async (filePath) => (await readFile(filePath, 'utf8')).trim()));
+    return {
+        files: markdownFiles,
+        count: markdownFiles.length,
+        content: contents.filter((entry) => entry.length > 0).join('\n\n')
+    };
+}
+async function collectMarkdownFiles(targetPath) {
+    let targetStats;
+    try {
+        targetStats = await stat(targetPath);
+    }
+    catch (error) {
+        throw new MemoryPathError(`Memory path does not exist: ${targetPath}`);
+    }
+    if (!targetStats.isDirectory()) {
+        throw new MemoryPathError(`Memory path is not a directory: ${targetPath}`);
+    }
+    const entries = await readdir(targetPath, { withFileTypes: true });
+    const nestedResults = await Promise.all(entries.map(async (entry) => {
+        const entryPath = path.join(targetPath, entry.name);
+        if (entry.isDirectory()) {
+            return collectMarkdownFiles(entryPath);
+        }
+        if (entry.isFile() && path.extname(entry.name).toLowerCase() === '.md') {
+            return [entryPath];
+        }
+        return [];
+    }));
+    return nestedResults.flat();
+}

package/dist/context/skills.d.ts

@@ -0,0 +1,2 @@
+import type { BrainctlConfig } from '../types.js';
+export declare function resolveSkillPrompt(config: BrainctlConfig, skillName: string): string;

package/dist/context/skills.js

@@ -0,0 +1,8 @@
+import { SkillNotFoundError } from '../errors.js';
+export function resolveSkillPrompt(config, skillName) {
+    const skill = config.skills[skillName];
+    if (!skill) {
+        throw new SkillNotFoundError(`Skill "${skillName}" is not defined in ai-stack.yaml.`);
+    }
+    return skill.prompt;
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+import type { ErrorCategory } from './types.js';
+export declare class BrainctlError extends Error {
+    readonly category: ErrorCategory;
+    readonly code: string;
+    constructor(message: string, category: ErrorCategory, code: string);
+}
+export declare class ConfigError extends BrainctlError {
+    constructor(message: string);
+}
+export declare class ValidationError extends BrainctlError {
+    constructor(message: string);
+}
+export declare class MemoryPathError extends BrainctlError {
+    constructor(message: string);
+}
+export declare class SkillNotFoundError extends BrainctlError {
+    constructor(message: string);
+}
+export declare class InputFileError extends BrainctlError {
+    constructor(message: string);
+}
+export declare class AgentNotAvailableError extends BrainctlError {
+    constructor(message: string);
+}
+export declare class ExecutionError extends BrainctlError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,45 @@
+export class BrainctlError extends Error {
+    category;
+    code;
+    constructor(message, category, code) {
+        super(message);
+        this.name = new.target.name;
+        this.category = category;
+        this.code = code;
+    }
+}
+export class ConfigError extends BrainctlError {
+    constructor(message) {
+        super(message, 'user', 'CONFIG_ERROR');
+    }
+}
+export class ValidationError extends BrainctlError {
+    constructor(message) {
+        super(message, 'user', 'VALIDATION_ERROR');
+    }
+}
+export class MemoryPathError extends BrainctlError {
+    constructor(message) {
+        super(message, 'user', 'MEMORY_PATH_ERROR');
+    }
+}
+export class SkillNotFoundError extends BrainctlError {
+    constructor(message) {
+        super(message, 'user', 'SKILL_NOT_FOUND');
+    }
+}
+export class InputFileError extends BrainctlError {
+    constructor(message) {
+        super(message, 'user', 'INPUT_FILE_ERROR');
+    }
+}
+export class AgentNotAvailableError extends BrainctlError {
+    constructor(message) {
+        super(message, 'user', 'AGENT_NOT_AVAILABLE');
+    }
+}
+export class ExecutionError extends BrainctlError {
+    constructor(message) {
+        super(message, 'system', 'EXECUTION_ERROR');
+    }
+}

package/dist/executor/claude.d.ts

@@ -0,0 +1,5 @@
+import type { Executor, ExecutorRunOptions, ExecutorResult } from './types.js';
+export declare class ClaudeExecutor implements Executor {
+    readonly agent: "claude";
+    run(context: string, options?: ExecutorRunOptions): Promise<ExecutorResult>;
+}

package/dist/executor/claude.js

@@ -0,0 +1,12 @@
+import { runAgentProcess } from './process.js';
+export class ClaudeExecutor {
+    agent = 'claude';
+    async run(context, options) {
+        return await runAgentProcess({
+            command: 'claude',
+            agent: this.agent,
+            context,
+            runOptions: options
+        });
+    }
+}