supermind-claude 2.0.0

package/.env.example

@@ -0,0 +1,5 @@
+# Copy this to .env and fill in your keys
+# DO NOT commit .env to git
+
+TAVILY_API_KEY=your_tavily_api_key_here
+TWENTYFIRST_API_KEY=your_21st_dev_api_key_here

package/README.md

@@ -0,0 +1,77 @@
+# Supermind
+
+Complete, opinionated Claude Code setup — hooks, skills, status line, MCP servers, and living documentation.
+
+## Quick Install
+
+```bash
+npx supermind-claude
+```
+
+Or give Claude Code the repo URL and it will figure out the setup.
+
+## What Gets Installed
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| Hooks | ~/.claude/hooks/ | Session persistence, bash permissions, status line, cost tracking |
+| Skills | ~/.claude/skills/ | /supermind-init, /supermind-living-docs |
+| Plugins | settings.json | Superpowers, frontend-design, claude-md-management, ui-ux-pro-max |
+| Settings | settings.json | Thinking mode, effort level, hook registration |
+| Templates | ~/.claude/templates/ | CLAUDE.md project template |
+
+## Project Setup
+
+After installing, run `/supermind-init` in any project to:
+1. Create or merge CLAUDE.md with project-specific config
+2. Generate ARCHITECTURE.md (and DESIGN.md for UI projects)
+3. Check setup health and discover relevant tools
+
+## Living Documentation
+
+- **Auto-read**: Session-start hook reads ARCHITECTURE.md and DESIGN.md at every conversation start
+- **Manual sync**: Run `/supermind-living-docs` to update docs after code changes
+
+## Status Line
+
+Two-line terminal display showing: user, model, path, git branch, context usage, thinking level, active agents, and session cost.
+
+## MCP Servers
+
+Choose during setup:
+- **Docker** (AIRIS gateway): Single endpoint routing to context7, playwright, serena, tavily, chrome-devtools, shadcn
+- **Direct**: Individual servers via npx/uvx
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npx supermind-claude` | Full global setup |
+| `npx supermind-claude update` | Refresh hooks, skills, templates |
+| `npx supermind-claude doctor` | Verify installation health |
+| `npx supermind-claude uninstall` | Remove all components |
+| `npx supermind-claude approve "cmd"` | Permanently auto-approve a command |
+
+## Approved Commands
+
+Permanently auto-approve specific commands that the bash-permissions hook would normally flag:
+
+```bash
+npx supermind-claude approve "git push"        # exact/prefix match
+npx supermind-claude approve "/npm run .*/"    # regex match
+npx supermind-claude approve --list            # see all approved
+npx supermind-claude approve --remove "git push"  # remove approval
+```
+
+Or tell Claude: "add that to my approved commands" — it knows how to edit the file directly.
+
+## Platforms
+
+Windows, macOS, and Linux. Requires Node.js >= 18.
+
+## Troubleshooting
+
+Run `npx supermind-claude doctor` to check installation health. Common issues:
+- **Plugins not active**: Restart Claude Code after install
+- **Status line not showing**: Ensure Node.js is in PATH
+- **Hooks not firing**: Run `npx supermind-claude update` to re-register

package/airis/docker-compose.yml

@@ -0,0 +1,76 @@
+# AIRIS MCP Gateway - Distribution Version
+# Usage: cd ~/.claude/airis && docker compose up -d
+
+name: airis-mcp-gateway
+
+services:
+  # Serena MCP Server (semantic code retrieval)
+  serena:
+    container_name: airis-serena
+    image: ghcr.io/oraios/serena:latest
+    command:
+      - serena
+      - start-mcp-server
+      - --transport
+      - sse
+      - --port
+      - "8000"
+      - --context
+      - claude-code
+    expose:
+      - "8000"
+    volumes:
+      - ${HOST_WORKSPACE_DIR:-~/github}:/workspaces/projects:rw
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8000/health 2>/dev/null || exit 0"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+    restart: unless-stopped
+
+  # Docker MCP Gateway (manages MCP servers from Docker catalog)
+  gateway:
+    container_name: airis-mcp-gateway-core
+    image: docker/mcp-gateway:latest
+    command:
+      - --transport=sse
+      - --port=9390
+      - --watch
+      - --servers=time
+    expose:
+      - "9390"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ${HOST_WORKSPACE_DIR:-~/github}:/workspace:rw
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qS --spider http://localhost:9390/health 2>&1 | grep -q '200'"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped
+
+  # FastAPI Proxy (MCP Multiplexer)
+  api:
+    container_name: airis-mcp-gateway
+    image: ghcr.io/agiletec-inc/airis-mcp-gateway:latest
+    ports:
+      - "9400:8000"
+    environment:
+      - MCP_GATEWAY_URL=http://gateway:9390
+      - MCP_CONFIG_PATH=/app/mcp-config.json
+      - AIRIS_MODE=${AIRIS_MODE:-embedded}
+
+      - TAVILY_API_KEY=${TAVILY_API_KEY:-}
+    volumes:
+      - ./mcp-config.json:/app/mcp-config.json:ro
+      - ./profiles:/app/profiles:rw
+    depends_on:
+      gateway:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+    restart: unless-stopped

package/airis/mcp-config.json

@@ -0,0 +1,43 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"],
+      "enabled": true,
+      "mode": "cold"
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+      "enabled": true,
+      "mode": "cold"
+    },
+    "serena": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "claude-code", "--enable-web-dashboard", "false", "--enable-gui-log-window", "false"],
+      "enabled": true,
+      "mode": "cold"
+    },
+    "tavily": {
+      "command": "npx",
+      "args": ["-y", "tavily-mcp@0.1.2"],
+      "enabled": true,
+      "mode": "cold",
+      "env": {
+        "TAVILY_API_KEY": "${TAVILY_API_KEY}"
+      }
+    },
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"],
+      "enabled": true,
+      "mode": "cold"
+    },
+    "shadcn": {
+      "command": "npx",
+      "args": ["-y", "shadcn@latest", "mcp"],
+      "enabled": true,
+      "mode": "cold"
+    }
+  }
+}

package/cli/commands/approve.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { PATHS } = require('../lib/platform');
+const logger = require('../lib/logger');
+
+const APPROVED_FILE = path.join(PATHS.claudeHome, 'supermind-approved.json');
+
+function loadApproved() {
+  try {
+    const data = JSON.parse(fs.readFileSync(APPROVED_FILE, 'utf-8'));
+    return Array.isArray(data) ? data : [];
+  } catch {
+    return [];
+  }
+}
+
+function saveApproved(list) {
+  fs.writeFileSync(APPROVED_FILE, JSON.stringify(list, null, 2) + '\n');
+}
+
+module.exports = function approve(flags) {
+  const args = process.argv.slice(3).filter(a => !a.startsWith('-'));
+
+  // supermind-claude approve --list
+  if (flags.list || args.length === 0) {
+    const approved = loadApproved();
+    if (approved.length === 0) {
+      console.log('\n  No approved commands. Add one with:\n');
+      console.log('    supermind-claude approve "git push"');
+      console.log('    supermind-claude approve "/npm run .*/"\n');
+      return;
+    }
+    console.log('\n  Approved commands:\n');
+    for (const cmd of approved) {
+      logger.success(cmd);
+    }
+    console.log('');
+    return;
+  }
+
+  // supermind-claude approve --remove "pattern"
+  if (flags.remove) {
+    const pattern = args[0];
+    if (!pattern) {
+      logger.error('Specify the command to remove: supermind-claude approve --remove "git push"');
+      return;
+    }
+    const approved = loadApproved();
+    const filtered = approved.filter(c => c !== pattern);
+    if (filtered.length === approved.length) {
+      logger.warn(`"${pattern}" not found in approved commands`);
+      return;
+    }
+    saveApproved(filtered);
+    logger.success(`Removed: ${pattern}`);
+    return;
+  }
+
+  // supermind-claude approve "command"
+  const pattern = args[0];
+  const approved = loadApproved();
+  if (approved.includes(pattern)) {
+    logger.info(`Already approved: ${pattern}`);
+    return;
+  }
+  approved.push(pattern);
+  saveApproved(approved);
+  logger.success(`Approved: ${pattern}`);
+  logger.info('This command will now be auto-allowed by bash-permissions hook');
+};

package/cli/commands/doctor.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { PATHS } = require('../lib/platform');
+const logger = require('../lib/logger');
+const { readSettings, SUPERMIND_PLUGINS } = require('../lib/settings');
+const { getHookFiles } = require('../lib/hooks');
+const { getSkillDirs } = require('../lib/skills');
+const { version } = require('../../package.json');
+
+function check(label, pass, detail) {
+  if (pass) {
+    logger.success(label);
+  } else {
+    logger.error(`${label}${detail ? ' \u2014 ' + detail : ''}`);
+  }
+  return pass;
+}
+
+module.exports = function doctor(flags) {
+  logger.banner();
+  console.log('  Running health checks...\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  function run(label, pass, detail) {
+    if (check(label, pass, detail)) passed++;
+    else failed++;
+  }
+
+  // Node.js version
+  const nodeVersion = parseInt(process.versions.node.split('.')[0], 10);
+  run('Node.js >= 18', nodeVersion >= 18, `found v${process.versions.node}`);
+
+  // Claude home
+  run('~/.claude/ exists', fs.existsSync(PATHS.claudeHome));
+
+  // Settings
+  const settingsExists = fs.existsSync(PATHS.settings);
+  run('settings.json exists', settingsExists);
+
+  let settings = {};
+  if (settingsExists) {
+    try {
+      settings = JSON.parse(fs.readFileSync(PATHS.settings, 'utf-8'));
+      run('settings.json is valid JSON', true);
+    } catch {
+      run('settings.json is valid JSON', false, 'parse error');
+    }
+  }
+
+  // Hooks present
+  const expectedHooks = getHookFiles();
+  for (const file of expectedHooks) {
+    run(`Hook: ${file}`, fs.existsSync(path.join(PATHS.hooksDir, file)));
+  }
+
+  // Skills present
+  const expectedSkills = getSkillDirs();
+  for (const dir of expectedSkills) {
+    const skillPath = path.join(PATHS.skillsDir, dir);
+    run(`Skill: ${dir}`, fs.existsSync(skillPath) && fs.existsSync(path.join(skillPath, 'SKILL.md')));
+  }
+
+  // Plugins
+  for (const id of SUPERMIND_PLUGINS) {
+    run(`Plugin: ${id.split('@')[0]}`, settings.enabledPlugins?.[id] === true);
+  }
+
+  // Template
+  run('CLAUDE.md template', fs.existsSync(path.join(PATHS.templatesDir, 'CLAUDE.md')));
+
+  // Sessions directory
+  run('Sessions directory writable', (() => {
+    try {
+      const testFile = path.join(PATHS.sessionsDir, '.doctor-test');
+      fs.writeFileSync(testFile, 'test');
+      fs.unlinkSync(testFile);
+      return true;
+    } catch { return false; }
+  })());
+
+  // Docker (warn only, not required)
+  try {
+    require('child_process').execSync('docker compose version', { stdio: 'pipe', timeout: 5000 });
+    logger.success('Docker available');
+    passed++;
+  } catch {
+    logger.warn('Docker not available (optional \u2014 needed for AIRIS mode)');
+  }
+
+  // Version
+  let installedVersion = 'not found';
+  try { installedVersion = fs.readFileSync(PATHS.versionFile, 'utf-8').trim(); } catch {}
+  run('Version marker', installedVersion === version, installedVersion !== version ? `installed: ${installedVersion}, package: ${version}` : undefined);
+
+  console.log(`\n  ${passed} passed, ${failed} failed\n`);
+  if (failed > 0) process.exit(1);
+};

package/cli/commands/install.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const fs = require('fs');
+const { PATHS, ensureDir } = require('../lib/platform');
+const logger = require('../lib/logger');
+const { readSettings, writeSettings, backupSettings, mergeSettings } = require('../lib/settings');
+const { installHooks, getHookSettings } = require('../lib/hooks');
+const { installSkills, removeLegacySkills } = require('../lib/skills');
+const { getPluginDefaults } = require('../lib/plugins');
+const { setupMcp } = require('../lib/mcp');
+const { installTemplates } = require('../lib/templates');
+const { version } = require('../../package.json');
+
+module.exports = async function install(flags) {
+  logger.banner();
+  const TOTAL = 7;
+
+  // Step 1: Platform setup
+  logger.step(1, TOTAL, 'Detecting platform and creating directories...');
+  ensureDir(PATHS.claudeHome);
+  ensureDir(PATHS.hooksDir);
+  ensureDir(PATHS.skillsDir);
+  ensureDir(PATHS.sessionsDir);
+  logger.success(`Claude home: ${PATHS.claudeHome}`);
+
+  // Clean up legacy files
+  if (fs.existsSync(PATHS.legacyHooksJson)) {
+    fs.unlinkSync(PATHS.legacyHooksJson);
+    logger.info('Removed legacy hooks.json');
+  }
+
+  // Step 2: Settings
+  logger.step(2, TOTAL, 'Configuring settings...');
+  backupSettings();
+  const existing = readSettings();
+  const hookSettings = getHookSettings();
+  const pluginDefaults = getPluginDefaults();
+  const defaults = {
+    ...hookSettings,
+    ...pluginDefaults,
+    alwaysThinkingEnabled: true,
+    effortLevel: 'high',
+  };
+  let merged = mergeSettings(existing, defaults);
+  writeSettings(merged);
+  logger.success('Settings merged');
+
+  // Step 3: Hooks
+  logger.step(3, TOTAL, 'Installing hooks...');
+  const hookFiles = installHooks();
+  logger.info(`${hookFiles.length} hooks installed`);
+
+  // Step 4: Skills
+  logger.step(4, TOTAL, 'Installing skills...');
+  removeLegacySkills();
+  const skillDirs = installSkills();
+  logger.info(`${skillDirs.length} skill directories installed`);
+
+  // Step 5: Plugins (data already merged in Step 2 via getPluginDefaults — this step is log-only)
+  logger.step(5, TOTAL, 'Enabling plugins...');
+  logger.success('superpowers, frontend-design, claude-md-management, ui-ux-pro-max');
+
+  // Step 6: MCP servers
+  logger.step(6, TOTAL, 'MCP server setup...');
+  const mcpConfig = await setupMcp(flags);
+  if (mcpConfig.mcpServers) {
+    merged = readSettings();
+    merged.mcpServers = { ...(merged.mcpServers || {}), ...mcpConfig.mcpServers };
+    writeSettings(merged);
+  }
+
+  // Step 7: Templates
+  logger.step(7, TOTAL, 'Installing templates...');
+  installTemplates();
+
+  // Write version marker
+  fs.writeFileSync(PATHS.versionFile, version);
+
+  // Summary
+  console.log(`\n${'\x1b[32m'}\u2713 Supermind v${version} installed successfully${'\x1b[0m'}\n`);
+  console.log('  Next steps:');
+  console.log('    1. Restart Claude Code to activate plugins');
+  console.log('    2. In any project, run /supermind-init to set up project docs');
+  console.log('    3. Run: npx supermind-claude doctor  to verify installation\n');
+};

package/cli/commands/uninstall.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const fs = require('fs');
+const readline = require('readline');
+const { PATHS } = require('../lib/platform');
+const logger = require('../lib/logger');
+const { readSettings, writeSettings, removeSupermindEntries } = require('../lib/settings');
+const { removeHooks } = require('../lib/hooks');
+const { removeSkills } = require('../lib/skills');
+const { removeTemplates } = require('../lib/templates');
+
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer.trim()); }));
+}
+
+module.exports = async function uninstall(flags) {
+  logger.banner();
+
+  if (!flags.yes && !flags.nonInteractive) {
+    const answer = await prompt('  Remove all Supermind components? [y/N]: ');
+    if (answer.toLowerCase() !== 'y') {
+      console.log('  Cancelled.\n');
+      return;
+    }
+  }
+
+  console.log('');
+
+  // Remove hooks
+  console.log('  Removing hooks...');
+  removeHooks();
+
+  // Remove skills
+  console.log('  Removing skills...');
+  removeSkills();
+
+  // Remove templates
+  console.log('  Removing templates...');
+  removeTemplates();
+
+  // Clean settings
+  console.log('  Cleaning settings...');
+  const settings = readSettings();
+  const cleaned = removeSupermindEntries(settings);
+  writeSettings(cleaned);
+  logger.success('Settings cleaned');
+
+  // Remove version marker
+  if (fs.existsSync(PATHS.versionFile)) {
+    fs.unlinkSync(PATHS.versionFile);
+  }
+
+  // Remove legacy hooks.json
+  if (fs.existsSync(PATHS.legacyHooksJson)) {
+    fs.unlinkSync(PATHS.legacyHooksJson);
+    logger.info('Removed legacy hooks.json');
+  }
+
+  // Optional: AIRIS config
+  if (fs.existsSync(PATHS.airisDir)) {
+    if (flags.yes || flags.nonInteractive) {
+      fs.rmSync(PATHS.airisDir, { recursive: true, force: true });
+      logger.success('Removed AIRIS config');
+    } else {
+      const answer = await prompt('  Also remove AIRIS/Docker config? [y/N]: ');
+      if (answer.toLowerCase() === 'y') {
+        fs.rmSync(PATHS.airisDir, { recursive: true, force: true });
+        logger.success('Removed AIRIS config');
+      }
+    }
+  }
+
+  console.log(`\n${'\x1b[32m'}\u2713 Supermind uninstalled${'\x1b[0m'}\n`);
+};

package/cli/commands/update.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const fs = require('fs');
+const { PATHS } = require('../lib/platform');
+const logger = require('../lib/logger');
+const { readSettings, writeSettings, mergeSettings } = require('../lib/settings');
+const { installHooks, getHookSettings } = require('../lib/hooks');
+const { installSkills, removeLegacySkills } = require('../lib/skills');
+const { installTemplates } = require('../lib/templates');
+const { version } = require('../../package.json');
+
+module.exports = function update(flags) {
+  logger.banner();
+
+  // Version comparison
+  let installedVersion = 'unknown';
+  try { installedVersion = fs.readFileSync(PATHS.versionFile, 'utf-8').trim(); } catch {}
+
+  if (installedVersion === version) {
+    logger.info(`Already at v${version}, refreshing files...`);
+  } else {
+    logger.info(`Updating from v${installedVersion} to v${version}...`);
+  }
+
+  const TOTAL = 4;
+
+  // Step 1: Hooks
+  logger.step(1, TOTAL, 'Updating hooks...');
+  installHooks();
+
+  // Step 2: Hook settings (re-merge to pick up any new hooks)
+  logger.step(2, TOTAL, 'Updating settings...');
+  const existing = readSettings();
+  const hookSettings = getHookSettings();
+  const merged = mergeSettings(existing, hookSettings);
+  writeSettings(merged);
+  logger.success('Hook settings refreshed');
+
+  // Step 3: Skills
+  logger.step(3, TOTAL, 'Updating skills...');
+  removeLegacySkills();
+  installSkills();
+
+  // Step 4: Templates
+  logger.step(4, TOTAL, 'Updating templates...');
+  installTemplates();
+
+  // Write version marker
+  fs.writeFileSync(PATHS.versionFile, version);
+
+  console.log(`\n${'\x1b[32m'}\u2713 Supermind updated to v${version}${'\x1b[0m'}\n`);
+};

package/cli/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+'use strict';
+
+const { version } = require('../package.json');
+
+const COMMANDS = {
+  install: () => require('./commands/install'),
+  update: () => require('./commands/update'),
+  doctor: () => require('./commands/doctor'),
+  uninstall: () => require('./commands/uninstall'),
+  approve: () => require('./commands/approve'),
+};
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const flags = {};
+  let command = 'install'; // default
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') { flags.help = true; continue; }
+    if (arg === '--version' || arg === '-v') { flags.version = true; continue; }
+    if (arg === '--non-interactive') { flags.nonInteractive = true; continue; }
+    if (arg === '--yes' || arg === '-y') { flags.yes = true; continue; }
+    if (arg === '--mcp' && args[i + 1]) { flags.mcp = args[++i]; continue; }
+    if (arg === '--list' || arg === '-l') { flags.list = true; continue; }
+    if (arg === '--remove' || arg === '-r') { flags.remove = true; continue; }
+    if (!arg.startsWith('-') && COMMANDS[arg]) { command = arg; continue; }
+  }
+
+  return { command, flags };
+}
+
+function showHelp() {
+  console.log(`
+  supermind-claude v${version}
+
+  Usage: supermind-claude [command] [options]
+
+  Commands:
+    install     Full global setup (default)
+    update      Refresh hooks, skills, and templates
+    doctor      Verify installation health
+    uninstall   Remove all Supermind components
+    approve     Manage auto-approved commands
+
+  Options:
+    --non-interactive   Skip all prompts, use defaults
+    --mcp <mode>        MCP setup: docker, direct, or skip
+    --yes, -y           Auto-confirm destructive operations
+    --help, -h          Show this help
+    --version, -v       Show version
+`);
+}
+
+async function main() {
+  const { command, flags } = parseArgs(process.argv);
+
+  if (flags.version) { console.log(version); process.exit(0); }
+  if (flags.help) { showHelp(); process.exit(0); }
+
+  const run = COMMANDS[command]();
+  await run(flags);
+}
+
+main().catch(err => {
+  console.error(`\n  \x1b[31m\u2717\x1b[0m ${err.message}\n`);
+  process.exit(1);
+});