amicus 1.0.0

package/electron/toolbar.js

@@ -0,0 +1,229 @@
+/**
+ * Amicus Toolbar HTML Builder
+ *
+ * Generates the toolbar HTML for the bottom bar of the Electron window.
+ * Supports two modes: 'sidecar' (default) and 'setup'.
+ */
+
+const TOOLBAR_H = 40;
+
+/**
+ * Get the brand name based on client type
+ * @param {string} [client='code-local'] - Client type (code-local, code-web, cowork)
+ * @returns {string} Brand name to display
+ */
+function getBrandName(client) {
+  return client === 'cowork' ? 'Openwork Amicus' : 'Amicus';
+}
+
+/**
+ * Build toolbar HTML string
+ * @param {object} [options={}]
+ * @param {string} [options.mode='sidecar'] - 'sidecar' or 'setup'
+ * @param {string} [options.taskId='unknown'] - Task ID to display
+ * @param {string} [options.foldShortcut='Cmd+Shift+F'] - Shortcut label
+ * @param {string} [options.client='code-local'] - Client type for branding
+ * @returns {string} Complete HTML document for the toolbar
+ */
+function buildToolbarHTML(options = {}) {
+  const {
+    mode = 'sidecar',
+    taskId = 'unknown',
+    foldShortcut = 'Cmd+Shift+F',
+    client = 'code-local',
+    updateInfo = null
+  } = options;
+
+  const brandName = getBrandName(client);
+
+  const baseStyles = `
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    height: ${TOOLBAR_H}px;
+    background: #2D2B2A;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 14px;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    border-top: 1px solid #3D3A38;
+    -webkit-app-region: no-drag;
+    user-select: none;
+  }
+  .info {
+    color: #A09B96;
+    font-size: 12px;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+  }
+  .brand {
+    color: #D97757;
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.8px;
+    text-transform: uppercase;
+  }
+  .sep { color: #3D3A38; font-size: 14px; }
+  .detail, .timer {
+    color: #7A756F;
+    font-size: 11px;
+    font-family: 'SF Mono', Menlo, Monaco, monospace;
+  }
+  .action-btn {
+    padding: 5px 14px;
+    background: #D97757;
+    color: #FFF;
+    border: none;
+    border-radius: 4px;
+    font-size: 12px;
+    font-weight: 500;
+    cursor: pointer;
+    transition: background 0.15s;
+  }
+  .action-btn:hover { background: #C4623F; }
+  .action-btn:disabled { opacity: 0.5; cursor: default; }
+  .icon-btn {
+    background: none; border: 1px solid #3D3A38;
+    border-radius: 4px; color: #A09B96; cursor: pointer;
+    font-size: 14px; padding: 3px 8px; transition: all 0.15s;
+    display: flex; align-items: center;
+  }
+  .icon-btn:hover { border-color: #D97757; color: #D97757; }
+  .right-actions { display: flex; align-items: center; gap: 8px; }
+  .update-banner {
+    position: fixed;
+    bottom: ${TOOLBAR_H}px;
+    left: 0;
+    right: 0;
+    height: 32px;
+    background: #3D3A38;
+    border-bottom: 1px solid #4D4A48;
+    display: none;
+    align-items: center;
+    justify-content: center;
+    gap: 10px;
+    font-size: 12px;
+    color: #D4D0CC;
+    z-index: 100;
+  }
+  .update-banner .update-btn {
+    padding: 2px 10px;
+    background: #D97757;
+    color: #FFF;
+    border: none;
+    border-radius: 3px;
+    font-size: 11px;
+    cursor: pointer;
+    transition: background 0.15s;
+  }
+  .update-banner .update-btn:hover { background: #C4623F; }
+  .update-banner .update-btn:disabled { opacity: 0.5; cursor: default; }
+  .update-banner .dismiss-btn {
+    background: none;
+    border: none;
+    color: #7A756F;
+    cursor: pointer;
+    font-size: 14px;
+    padding: 0 4px;
+  }
+  .update-banner .dismiss-btn:hover { color: #D4D0CC; }`;
+
+  const logoSvg = `<svg width="16" height="16" viewBox="0 0 16 16" fill="none">
+      <path d="M3 2v12" stroke="#D97757" stroke-width="2" stroke-linecap="round"/>
+      <path d="M10 2v5c0 2-3 3-7 5" stroke="#D97757" stroke-width="2" stroke-linecap="round" stroke-opacity="0.6"/>
+    </svg>`;
+
+  if (mode === 'setup') {
+    return `<!DOCTYPE html>
+<html><head><style>${baseStyles}</style></head><body>
+  <div class="info">
+    ${logoSvg}
+    <span class="brand">${brandName}</span>
+  </div>
+  <button class="action-btn" id="continue-btn" disabled>Continue</button>
+<script>
+  document.getElementById('continue-btn').addEventListener('click', function() {
+    if (!this.disabled) {
+      window.sidecar && window.sidecar.setupDone();
+    }
+  });
+</script>
+</body></html>`;
+  }
+
+  // Default: sidecar mode
+  return `<!DOCTYPE html>
+<html><head><style>${baseStyles}</style></head><body>
+  <div class="update-banner" id="update-banner">
+    <span id="update-text"></span>
+    <button class="update-btn" id="update-btn">Update</button>
+    <button class="dismiss-btn" id="dismiss-btn">&times;</button>
+  </div>
+  <div class="info">
+    ${logoSvg}
+    <span class="brand">${brandName}</span>
+    <span class="sep">|</span>
+    <span class="detail" title="Task ID — use with: amicus resume ${taskId}">task: ${taskId}</span>
+    <span class="sep">|</span>
+    <span class="timer" id="timer">0:00</span>
+  </div>
+  <div class="right-actions">
+    <button class="icon-btn" id="settings-btn" title="Settings">&#x2699;</button>
+    <button class="action-btn" id="fold-btn">Fold (${foldShortcut})</button>
+  </div>
+<script>
+  var start = Date.now();
+  setInterval(function() {
+    var s = Math.floor((Date.now() - start) / 1000);
+    var m = Math.floor(s / 60);
+    s = s % 60;
+    document.getElementById('timer').textContent = m + ':' + (s < 10 ? '0' : '') + s;
+  }, 1000);
+  // contextBridge doesn't work with data: URLs, so use window action flags
+  // that the main process polls via executeJavaScript (same pattern as update banner).
+  window.__amicusToolbarAction = null;
+  document.getElementById('fold-btn').addEventListener('click', function() {
+    window.__amicusToolbarAction = 'fold';
+  });
+  document.getElementById('settings-btn').addEventListener('click', function() {
+    window.__amicusToolbarAction = 'open-settings';
+  });
+
+  // Update banner logic (data injected at build time, no IPC needed)
+  (function() {
+    var updateInfo = ${JSON.stringify(updateInfo)};
+    if (!updateInfo || !updateInfo.hasUpdate) { return; }
+
+    var banner = document.getElementById('update-banner');
+    var text = document.getElementById('update-text');
+    var btn = document.getElementById('update-btn');
+    var dismiss = document.getElementById('dismiss-btn');
+
+    text.textContent = 'v' + updateInfo.latest + ' available';
+    banner.style.display = 'flex';
+
+    // Notify main process to expand toolbar area
+    // Uses postMessage since preload contextBridge doesn't work with data: URLs
+    window.__amicusUpdateAction = null;
+    btn.addEventListener('click', function() {
+      btn.disabled = true;
+      btn.textContent = 'Updating...';
+      dismiss.style.display = 'none';
+      window.__amicusUpdateAction = 'perform-update';
+    });
+
+    dismiss.addEventListener('click', function() {
+      banner.style.display = 'none';
+      window.__amicusUpdateAction = 'dismiss';
+    });
+  })();
+</script>
+</body></html>`;
+}
+
+module.exports = { buildToolbarHTML, TOOLBAR_H, getBrandName };

package/electron/window-position.js

@@ -0,0 +1,35 @@
+/**
+ * Window Position Calculator
+ *
+ * Computes the (x, y) coordinates for the sidecar Electron window
+ * based on the display work area and desired position preference.
+ *
+ * Extracted as a pure function for testability (no Electron dependency).
+ */
+
+/**
+ * Compute window (x, y) position within a display work area.
+ *
+ * @param {{ x: number, y: number, width: number, height: number }} workArea
+ * @param {number} winW - Window width in pixels
+ * @param {number} winH - Window height in pixels
+ * @param {'right'|'left'|'center'|string} [position='right'] - Desired position
+ * @returns {{ x: number, y: number }}
+ */
+function computeWindowPosition(workArea, winW, winH, position) {
+  const { x: areaX, y: areaY, width: areaW } = workArea;
+
+  let x;
+  if (position === 'left') {
+    x = areaX;
+  } else if (position === 'center') {
+    x = Math.round(areaX + (areaW - winW) / 2);
+  } else {
+    // 'right' is the default for any unknown value
+    x = areaX + areaW - winW;
+  }
+
+  return { x, y: areaY };
+}
+
+module.exports = { computeWindowPosition };

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "amicus",
+  "version": "1.0.0",
+  "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "sidecar",
+    "multi-model",
+    "opencode",
+    "openrouter",
+    "parallel",
+    "llm",
+    "gemini",
+    "cowork",
+    "council",
+    "second-opinion",
+    "fanout"
+  ],
+  "author": "BourbonDog",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BourbonDog/amicus.git"
+  },
+  "bugs": "https://github.com/BourbonDog/amicus/issues",
+  "homepage": "https://github.com/BourbonDog/amicus#readme",
+  "bin": {
+    "amicus": "./bin/amicus.js",
+    "am": "./bin/amicus.js",
+    "sidecar": "./bin/amicus.js",
+    "claude-sidecar": "./bin/amicus.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    "./opencode-client": "./src/opencode-client.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "electron/",
+    "skill/",
+    "skills/",
+    "CHANGELOG.md",
+    "scripts/postinstall.js",
+    "scripts/setup-hooks.js"
+  ],
+  "scripts": {
+    "start": "node --experimental-top-level-await --experimental-vm-modules bin/amicus.js",
+    "test": "jest",
+    "test:integration": "jest --testPathIgnorePatterns='\\.worktrees/' --testMatch='**/tests/**/*.integration.test.js'",
+    "test:all": "jest --testPathIgnorePatterns='/node_modules/' --testPathIgnorePatterns='\\.worktrees/' && node scripts/mark-test-passed.js",
+    "test:e2e:mcp": "jest tests/mcp-repomix-e2e.integration.test.js --testTimeout=180000 --forceExit",
+    "posttest": "node scripts/mark-test-passed.js",
+    "lint": "eslint src/",
+    "postinstall": "node scripts/postinstall.js",
+    "test:thinking": "node scripts/benchmark-thinking.js",
+    "test:thinking:quick": "MODELS=gemini node scripts/benchmark-thinking.js",
+    "refresh-models": "node bin/amicus.js models --refresh",
+    "models:info": "node bin/amicus.js models",
+    "models:check": "node bin/amicus.js models --check",
+    "generate-icon": "node scripts/generate-icon.js",
+    "generate-docs": "node scripts/generate-docs.js",
+    "generate-docs:check": "node scripts/generate-docs.js --check",
+    "validate-docs": "node scripts/validate-docs.js --full",
+    "prepare": "node scripts/setup-hooks.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@opencode-ai/sdk": "^1.1.36",
+    "dotenv": "^17.2.3",
+    "opencode-ai": "^1.2.20",
+    "tiktoken": "^1.0.0",
+    "update-notifier": "^7.3.1",
+    "zod": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "electron": "^28.0.0"
+  },
+  "devDependencies": {
+    "chrome-remote-interface": "^0.33.3",
+    "eslint": "^8.0.0",
+    "husky": "^9.1.7",
+    "jest": "^29.0.0",
+    "lint-staged": "^16.3.2",
+    "puppeteer": "^24.36.0",
+    "sharp": "^0.33.5",
+    "ws": "^8.19.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "lint-staged": {
+    "src/**/*.js": [
+      "eslint --fix"
+    ]
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script for amicus
+ *
+ * 1. Copies SKILL.md to ~/.claude/skills/sidecar/
+ * 2. Registers MCP server in Claude Code (~/.claude.json)
+ * 3. Registers MCP server in Claude Desktop/Cowork config
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+const SKILL_SOURCE = path.join(__dirname, '..', 'skill', 'SKILL.md');
+const COUNCIL_SOURCE_DIR = path.join(__dirname, '..', 'skills', 'second-opinion');
+
+/** Council files + per-file install semantics: SKILL/COUNCIL-DESIGN are product code
+ * (overwrite on update); MODEL-NOTES is user data — its reviewer-reliability table evolves
+ * per-run, so it is seeded once and never clobbered. */
+const COUNCIL_FILES = [
+  { file: 'SKILL.md', mode: 'overwrite' },
+  { file: 'COUNCIL-DESIGN.md', mode: 'overwrite' },
+  { file: 'MODEL-NOTES.md', mode: 'if-missing' },
+];
+
+function skillsRoot() {
+  return path.join(os.homedir(), '.claude', 'skills');
+}
+
+const MCP_CONFIG = { command: 'npx', args: ['-y', 'amicus@latest', 'mcp'] };
+
+/**
+ * Add or update an MCP server in a JSON config file.
+ * Always overwrites the entry to ensure upgrades apply the latest config.
+ *
+ * @param {string} configPath - Path to the JSON config file
+ * @param {string} name - MCP server name
+ * @param {object} config - MCP server config object
+ * @returns {string} 'added', 'updated', or 'unchanged'
+ */
+function addMcpToConfigFile(configPath, name, config) {
+  let existing = {};
+  try {
+    existing = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch {
+    // File doesn't exist or invalid JSON — start fresh
+  }
+
+  if (!existing.mcpServers) { existing.mcpServers = {}; }
+
+  const prev = existing.mcpServers[name];
+  const status = !prev ? 'added' : JSON.stringify(prev) !== JSON.stringify(config) ? 'updated' : 'unchanged';
+
+  existing.mcpServers[name] = config;
+  if (status !== 'unchanged') {
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); }
+    fs.writeFileSync(configPath, JSON.stringify(existing, null, 2), { mode: 0o600 });
+  }
+  return status;
+}
+
+/** Install the chat skill to ~/.claude/skills/sidecar/ */
+function installSkill() {
+  try {
+    const destDir = path.join(skillsRoot(), 'sidecar');
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.copyFileSync(SKILL_SOURCE, path.join(destDir, 'SKILL.md'));
+    console.log('[amicus] Chat skill installed to ~/.claude/skills/sidecar/');
+  } catch (err) {
+    console.error(`[amicus] Warning: Could not install chat skill: ${err.message}`);
+  }
+}
+
+/** Install the LLM Council skill to ~/.claude/skills/second-opinion/ */
+function installCouncilSkill(sourceDir = COUNCIL_SOURCE_DIR) {
+  const destDir = path.join(skillsRoot(), 'second-opinion');
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+  } catch (err) {
+    console.error(`[amicus] Warning: Could not create council skill dir: ${err.message}`);
+    return;
+  }
+  let failed = 0;
+  for (const { file, mode } of COUNCIL_FILES) {
+    try {
+      const dest = path.join(destDir, file);
+      if (mode === 'if-missing' && fs.existsSync(dest)) { continue; }
+      fs.copyFileSync(path.join(sourceDir, file), dest);
+    } catch (err) {
+      failed++;
+      console.error(`[amicus] Warning: Could not install council file ${file}: ${err.message}`);
+    }
+  }
+  if (failed === COUNCIL_FILES.length) {
+    console.error('[amicus] Warning: Council skill NOT installed (all files failed — see warnings above).');
+  } else if (failed > 0) {
+    console.log(`[amicus] Council skill partially installed (${failed}/${COUNCIL_FILES.length} files failed — see warnings above).`);
+  } else {
+    console.log('[amicus] Council skill installed to ~/.claude/skills/second-opinion/');
+  }
+}
+
+/** Register MCP server in Claude Code config */
+function registerClaudeCode() {
+  // Try the CLI first
+  try {
+    const mcpJson = JSON.stringify(MCP_CONFIG);
+    execFileSync('claude', ['mcp', 'add-json', 'amicus', mcpJson, '--scope', 'user'], {
+      stdio: 'pipe',
+      timeout: 10000,
+    });
+    console.log('[amicus] MCP registered in Claude Code (via CLI).');
+
+    // DEPRECATED(amicus-shim): also register 'sidecar' so existing clients that
+    // reference the old server name keep resolving. Remove in next major.
+    try {
+      execFileSync('claude', ['mcp', 'add-json', 'sidecar', mcpJson, '--scope', 'user'], {
+        stdio: 'pipe',
+        timeout: 10000,
+      });
+    } catch {
+      // Best-effort; ignore failures for the shim registration
+    }
+
+    return;
+  } catch {
+    // CLI not available or failed — fall back to file edit
+  }
+
+  // Fallback: direct file edit
+  const claudeConfigPath = path.join(os.homedir(), '.claude.json');
+  const status = addMcpToConfigFile(claudeConfigPath, 'amicus', MCP_CONFIG);
+  if (status === 'added') {
+    console.log('[amicus] MCP registered in Claude Code (~/.claude.json).');
+  } else if (status === 'updated') {
+    console.log('[amicus] MCP config updated in Claude Code (~/.claude.json).');
+  } else {
+    console.log('[amicus] MCP already registered in Claude Code.');
+  }
+
+  // DEPRECATED(amicus-shim): also register 'sidecar' entry so existing clients
+  // that reference the old server name keep resolving. Remove in next major.
+  addMcpToConfigFile(claudeConfigPath, 'sidecar', MCP_CONFIG);
+}
+
+/** Register MCP server in Claude Desktop / Cowork config */
+function registerClaudeDesktop() {
+  let configDir;
+  if (process.platform === 'darwin') {
+    configDir = path.join(os.homedir(), 'Library', 'Application Support', 'Claude');
+  } else if (process.platform === 'win32') {
+    configDir = path.join(process.env.APPDATA || '', 'Claude');
+  } else {
+    configDir = path.join(os.homedir(), '.config', 'claude');
+  }
+
+  const configPath = path.join(configDir, 'claude_desktop_config.json');
+  const status = addMcpToConfigFile(configPath, 'amicus', MCP_CONFIG);
+  if (status === 'added') {
+    console.log('[amicus] MCP registered in Claude Desktop.');
+  } else if (status === 'updated') {
+    console.log('[amicus] MCP config updated in Claude Desktop.');
+  } else {
+    console.log('[amicus] MCP already registered in Claude Desktop.');
+  }
+
+  // DEPRECATED(amicus-shim): also register 'sidecar' entry so existing clients
+  // that reference the old server name keep resolving. Remove in next major.
+  addMcpToConfigFile(configPath, 'sidecar', MCP_CONFIG);
+}
+
+function main() {
+  console.log('[amicus] Installing...');
+  installSkill();
+  installCouncilSkill();
+  registerClaudeCode();
+  registerClaudeDesktop();
+
+  console.log('');
+  console.log('[amicus] Setup:');
+  console.log('  - Configure API: Run `amicus setup` or set API keys directly');
+  console.log('  - API keys: OPENROUTER_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, OPENAI_API_KEY, etc.');
+}
+
+// Only run main when executed directly (not when required for testing)
+if (require.main === module) {
+  main();
+}
+
+module.exports = { addMcpToConfigFile, installSkill, installCouncilSkill, COUNCIL_FILES };

package/scripts/setup-hooks.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+/**
+ * Configure git to run the version-controlled hooks in .husky/.
+ *
+ * Replaces husky's install step, which pointed core.hooksPath at the
+ * generated, gitignored .husky/_ shim directory. That directory only
+ * exists where husky's prepare actually ran, so hooks silently never
+ * fired in linked git worktrees (relative core.hooksPath resolves against
+ * each worktree's root, and .husky/_ is never checked out there). The
+ * committed .husky/ directory exists in every checkout, so pointing
+ * core.hooksPath at it makes hooks fire in the main clone and in every
+ * worktree with no per-worktree setup.
+ *
+ * Runs automatically via npm's "prepare" lifecycle. If you install with
+ * --ignore-scripts (recommended for this repo), run it once by hand:
+ *
+ *   node scripts/setup-hooks.js
+ *
+ * Safe to run anywhere: exits 0 outside a git checkout (npm tarball
+ * installs, exported archives) and never fails the install.
+ */
+
+const { execFileSync } = require('node:child_process');
+
+function git(...args) {
+  return execFileSync('git', args, { encoding: 'utf-8' }).trim();
+}
+
+try {
+  git('rev-parse', '--git-dir');
+} catch {
+  process.exit(0); // not a git checkout — nothing to configure
+}
+
+try {
+  git('config', 'core.hooksPath', '.husky');
+  console.log('setup-hooks: core.hooksPath -> .husky (applies to all worktrees of this clone)');
+} catch (err) {
+  console.warn(`setup-hooks: could not set core.hooksPath: ${err.message}`);
+  process.exit(0); // never break npm install over hook setup
+}