agent-hub-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# AGENT HUB
+
+Terminal hub to discover and launch all your AI coding CLIs from one place.
+
+[![Agent Hub demo preview](./AgentHub-preview.gif)](./AgentHub.mp4)
+
+Full demo video: [AgentHub.mp4](./AgentHub.mp4)
+
+## What it is
+
+AGENT HUB is an open-source Node.js CLI that scans your machine for installed AI coding tools and gives you one terminal entry point to launch them.
+
+Instead of remembering separate commands for tools like `codex`, `claude`, `gemini`, `opencode`, `aider`, and custom wrappers, you open one interface and jump into the tool you want.
+
+## What it does
+
+- Scans the local machine for supported AI CLIs.
+- Shows only tools that are actually installed.
+- Lets you launch a tool by menu, number, or id.
+- Supports custom tools through `.agent-hub.json`.
+- Works as a lightweight terminal switchboard, not as a chatbot.
+
+## Demo
+
+The GIF above is a preview. Click it to open the full video.
+
+## Installation
+
+Local project usage:
+
+```bash
+npm install
+npm start
+```
+
+Global installation:
+
+```bash
+npm install -g .
+agent-hub
+```
+
+## Commands
+
+```bash
+agent-hub
+agent-hub scan
+agent-hub scan --json
+agent-hub scan --all
+agent-hub list
+agent-hub run codex
+agent-hub --theme neon-light
+```
+
+## Supported tools
+
+Built-in detection currently includes:
+
+- `claude`
+- `codex`
+- `gemini`
+- `opencode`
+- `aider`
+- `goose`
+
+## Custom tools
+
+Create a `.agent-hub.json` in the project directory or in your home directory:
+
+```json
+{
+  "tools": [
+    {
+      "id": "cursor-agent",
+      "name": "Cursor Agent",
+      "command": "cursor-agent",
+      "description": "Cursor terminal agent"
+    },
+    {
+      "id": "local-wrapper",
+      "name": "My Wrapper",
+      "command": ".\\scripts\\my-wrapper.cmd",
+      "args": ["--fast"]
+    }
+  ]
+}
+```
+
+Supported fields:
+
+- `id`
+- `name`
+- `command`
+- `args`
+- `description`
+- `binaryNames`
+- `knownPaths`
+
+## Development
+
+Run checks:
+
+```bash
+npm run check
+```
+
+Run a local scan:
+
+```bash
+npm start -- scan
+```
+
+## Notes
+
+- By default, the dashboard shows only installed tools.
+- Use `agent-hub scan --all` to inspect missing known tools too.
+- This version launches one interactive CLI at a time and returns to the dashboard when the process exits.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agent-hub-cli",
+  "version": "1.0.0",
+  "description": "Terminal hub to discover and launch all your AI coding CLIs from one place.",
+  "type": "module",
+  "bin": {
+    "agent-hub": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "check": "node --test"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cli",
+    "ai",
+    "terminal",
+    "claude",
+    "codex",
+    "developer-tools",
+    "nodejs",
+    "open-source"
+  ],
+  "homepage": "https://github.com/schenoneedoardo/AiFacilityCli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schenoneedoardo/AiFacilityCli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/schenoneedoardo/AiFacilityCli/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+
+import { runCli } from "./lib/cli.js";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

package/src/lib/cli.js

@@ -0,0 +1,179 @@
+import process from "node:process";
+
+import { detectTools, getAvailableTools, serializeTools } from "./detect.js";
+import {
+  installTool,
+  launchTool,
+  normalizeThemeName,
+  printScanTable,
+  promptForToolSelection,
+} from "./terminal.js";
+
+export async function runCli(argv) {
+  const { command, rest, theme } = parseArguments(argv);
+
+  if (!command || command === "menu") {
+    await openInteractiveMenu({ theme });
+    return;
+  }
+
+  if (command === "scan") {
+    const includeMissing = rest.includes("--all");
+    const tools = selectDisplayedTools(detectTools(), { includeMissing });
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(serializeTools(tools), null, 2));
+      return;
+    }
+
+    printScanTable(tools, { showActions: false, theme });
+    return;
+  }
+
+  if (command === "run") {
+    const toolId = rest[0];
+    if (!toolId) {
+      throw new Error("Missing tool id. Use `agent-hub scan` to list available ids.");
+    }
+
+    const tools = getAvailableTools(detectTools());
+    const tool = tools.find((entry) => entry.id === toolId);
+    if (!tool) {
+      throw new Error(`Tool "${toolId}" is not installed on this machine. Use \`agent-hub scan\` first.`);
+    }
+
+    await launchTool(tool, { theme });
+    return;
+  }
+
+  if (command === "list") {
+    printScanTable(getAvailableTools(detectTools()), { showActions: false, theme });
+    return;
+  }
+
+  if (command === "install") {
+    const toolId = rest[0];
+    if (!toolId) {
+      throw new Error("Missing tool id. Use `agent-hub scan --all` to see installable tools.");
+    }
+
+    const allTools = detectTools();
+    const tool = allTools.find((entry) => entry.id === toolId);
+    if (!tool) {
+      throw new Error(`Unknown tool "${toolId}".`);
+    }
+
+    if (tool.available) {
+      console.log(`${tool.name} is already installed.`);
+      return;
+    }
+
+    if (!tool.installCommand) {
+      throw new Error(`No install command defined for "${toolId}".`);
+    }
+
+    await installTool(tool, { theme });
+    return;
+  }
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  throw new Error(
+    `Unknown command "${command}". Use \`agent-hub help\` to see the supported commands.`,
+  );
+}
+
+async function openInteractiveMenu(options = {}) {
+  // Use ALL tools (installed + installable) so the user can install from the menu
+  let tools = detectTools();
+
+  while (true) {
+    printScanTable(tools, { theme: options.theme });
+
+    const selected = await promptForToolSelection(tools, { theme: options.theme });
+    if (selected === null) {
+      return;
+    }
+
+    if (selected === "rescan") {
+      tools = detectTools();
+      continue;
+    }
+
+    if (selected.available) {
+      await launchTool(selected, { theme: options.theme });
+    } else {
+      await installTool(selected, { theme: options.theme });
+    }
+
+    // Rescan after launch or install so status is up to date
+    tools = detectTools();
+  }
+}
+
+function selectDisplayedTools(tools, options = {}) {
+  if (options.includeMissing) {
+    return tools;
+  }
+
+  return getAvailableTools(tools);
+}
+
+function printHelp() {
+  const lines = [
+    "agent-hub",
+    "",
+    "Usage:",
+    "  agent-hub                Open the interactive menu (installed + installable tools)",
+    "  agent-hub scan           Scan and print only the installed tools",
+    "  agent-hub scan --json    Scan and print only the installed tools as JSON",
+    "  agent-hub scan --all     Include missing known tools",
+    "  agent-hub list           Alias of scan",
+    "  agent-hub run <id>       Launch a specific installed tool directly",
+    "  agent-hub install <id>   Install a specific tool by id",
+    "  agent-hub --theme vscode",
+    "  agent-hub --theme cyber",
+    "  agent-hub --theme neon-dark",
+    "  agent-hub --theme neon-light",
+    "",
+    "The menu shows installed tools (launch) and installable tools (install on select).",
+    "After launch or install the menu rescans automatically.",
+    "Configuration files supported:",
+    "  .agent-hub.json in the current directory",
+    `  .agent-hub.json in ${process.env.USERPROFILE ?? process.env.HOME ?? "~"}`,
+  ];
+
+  console.log(lines.join("\n"));
+}
+
+function parseArguments(argv) {
+  const positional = [];
+  let theme = normalizeThemeName();
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+
+    if (value === "--theme") {
+      const next = argv[index + 1];
+      if (!next) {
+        throw new Error("Missing value for --theme. Use `vscode`, `cyber`, `neon-dark` or `neon-light`.");
+      }
+
+      theme = normalizeThemeName(next);
+      index += 1;
+      continue;
+    }
+
+    if (value.startsWith("--theme=")) {
+      theme = normalizeThemeName(value.slice("--theme=".length));
+      continue;
+    }
+
+    positional.push(value);
+  }
+
+  const [command, ...rest] = positional;
+  return { command, rest, theme };
+}

package/src/lib/config.js

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CONFIG_NAME = ".agent-hub.json";
+
+export function loadUserTools() {
+  const configFiles = [
+    path.join(process.cwd(), CONFIG_NAME),
+    path.join(os.homedir(), CONFIG_NAME),
+  ];
+
+  const tools = [];
+
+  for (const filePath of configFiles) {
+    if (!fs.existsSync(filePath)) {
+      continue;
+    }
+
+    const parsed = readJson(filePath);
+    if (!parsed || !Array.isArray(parsed.tools)) {
+      continue;
+    }
+
+    for (const entry of parsed.tools) {
+      const tool = normalizeToolEntry(entry, path.dirname(filePath));
+      if (tool) {
+        tools.push(tool);
+      }
+    }
+  }
+
+  return tools;
+}
+
+function readJson(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeToolEntry(entry, baseDir) {
+  if (!entry || typeof entry !== "object") {
+    return null;
+  }
+
+  const id = sanitizeString(entry.id);
+  const name = sanitizeString(entry.name);
+  const command = sanitizeString(entry.command);
+  const description = sanitizeString(entry.description) ?? "User-defined tool";
+  const args = Array.isArray(entry.args)
+    ? entry.args.filter((value) => typeof value === "string")
+    : [];
+
+  if (!id || !name || !command) {
+    return null;
+  }
+
+  return {
+    id,
+    name,
+    command,
+    args,
+    description,
+    binaryNames: normalizeBinaryNames(entry.binaryNames, command),
+    knownPaths: normalizeKnownPaths(entry.knownPaths, baseDir),
+    baseDir,
+    source: "config",
+  };
+}
+
+function normalizeBinaryNames(binaryNames, command) {
+  if (!Array.isArray(binaryNames)) {
+    return [path.basename(command)];
+  }
+
+  const names = binaryNames.filter((value) => typeof value === "string" && value.trim());
+  return names.length > 0 ? names : [path.basename(command)];
+}
+
+function normalizeKnownPaths(knownPaths, baseDir) {
+  if (!Array.isArray(knownPaths)) {
+    return [];
+  }
+
+  return knownPaths
+    .filter((value) => typeof value === "string" && value.trim())
+    .map((value) => {
+      if (path.isAbsolute(value)) {
+        return value;
+      }
+
+      return path.resolve(baseDir, value);
+    });
+}
+
+function sanitizeString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}

package/src/lib/detect.js

@@ -0,0 +1,156 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { loadUserTools } from "./config.js";
+import { KNOWN_TOOLS } from "./registry.js";
+
+export function detectTools(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const searchDirs = buildSearchDirectories(env, platform);
+  const definitions = mergeDefinitions(KNOWN_TOOLS, loadUserTools());
+
+  return definitions.map((tool) => detectTool(tool, { platform, searchDirs }));
+}
+
+export function getAvailableTools(tools) {
+  return tools.filter((tool) => tool.available);
+}
+
+export function serializeTools(tools) {
+  return tools.map((tool) => ({
+    id: tool.id,
+    name: tool.name,
+    description: tool.description,
+    available: tool.available,
+    resolvedPath: tool.resolvedPath,
+    command: tool.command,
+    args: tool.args,
+  }));
+}
+
+export function buildSearchDirectories(env, platform) {
+  const pathValue = env.PATH ?? "";
+  const pathDirs = pathValue
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  const platformDirs =
+    platform === "win32" ? buildWindowsDirectories(env) : buildUnixDirectories();
+
+  return uniqueStrings([...pathDirs, ...platformDirs]);
+}
+
+export function resolveBinary(binaryNames, searchDirs, options = {}) {
+  const exists = options.exists ?? fs.existsSync;
+
+  for (const binaryName of uniqueStrings(binaryNames)) {
+    if (path.isAbsolute(binaryName) && exists(binaryName)) {
+      return binaryName;
+    }
+  }
+
+  for (const directory of searchDirs) {
+    for (const binaryName of uniqueStrings(binaryNames)) {
+      const candidate = path.join(directory, binaryName);
+      if (exists(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  return null;
+}
+
+function detectTool(tool, context) {
+  const binaryNames = buildBinaryNames(tool, context.platform);
+  const directCommand = resolveDirectCommand(tool.command, tool.baseDir);
+  const absoluteCandidates = uniqueStrings([
+    ...tool.knownPaths,
+    ...(directCommand ? [directCommand] : []),
+  ]);
+  const resolvedPath =
+    resolveBinary(absoluteCandidates, [], { exists: fs.existsSync }) ??
+    resolveBinary(binaryNames, context.searchDirs, { exists: fs.existsSync });
+
+  return {
+    ...tool,
+    available: Boolean(resolvedPath),
+    resolvedPath,
+    launchCommand: resolvedPath ?? tool.command,
+  };
+}
+
+function mergeDefinitions(builtInTools, userTools) {
+  const definitions = new Map();
+
+  for (const tool of [...builtInTools, ...userTools]) {
+    definitions.set(tool.id, tool);
+  }
+
+  return [...definitions.values()].sort((left, right) =>
+    left.name.localeCompare(right.name),
+  );
+}
+
+export function buildBinaryNames(tool, platform) {
+  const orderedNames = [];
+
+  for (const entry of tool.binaryNames ?? [tool.command]) {
+    if (platform === "win32" && !path.extname(entry)) {
+      orderedNames.push(`${entry}.cmd`, `${entry}.exe`, `${entry}.bat`, entry);
+      continue;
+    }
+
+    orderedNames.push(entry);
+  }
+
+  return uniqueStrings(orderedNames);
+}
+
+function resolveDirectCommand(command, baseDir = process.cwd()) {
+  if (path.isAbsolute(command)) {
+    return command;
+  }
+
+  if (command.includes("/") || command.includes("\\")) {
+    return path.resolve(baseDir, command);
+  }
+
+  return null;
+}
+
+function buildWindowsDirectories(env) {
+  return [
+    joinIfDefined(env.APPDATA, "npm"),
+    joinIfDefined(env.LOCALAPPDATA, "Microsoft", "WindowsApps"),
+    joinIfDefined(env.LOCALAPPDATA, "Programs"),
+    joinIfDefined(env.ProgramFiles, "nodejs"),
+    joinIfDefined(env["ProgramFiles(x86)"], "nodejs"),
+    joinIfDefined(env.USERPROFILE, "scoop", "shims"),
+    joinIfDefined(env.ChocolateyInstall, "bin"),
+  ].filter(Boolean);
+}
+
+function buildUnixDirectories() {
+  return [
+    "/usr/local/bin",
+    "/usr/bin",
+    "/opt/homebrew/bin",
+    "/home/linuxbrew/.linuxbrew/bin",
+  ];
+}
+
+function joinIfDefined(...parts) {
+  if (parts.some((value) => !value)) {
+    return null;
+  }
+
+  return path.join(...parts);
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.trim()))];
+}

package/src/lib/registry.js

@@ -0,0 +1,74 @@
+export const KNOWN_TOOLS = [
+  {
+    id: "aider",
+    name: "Aider",
+    command: "aider",
+    args: [],
+    description: "AI pair programming in your terminal",
+    binaryNames: ["aider"],
+    knownPaths: [],
+    source: "built-in",
+    installCommand: "pip install aider-chat",
+    installMethod: "pip",
+  },
+  {
+    id: "claude",
+    name: "Claude Code",
+    command: "claude",
+    args: [],
+    description: "Anthropic Claude Code CLI",
+    binaryNames: ["claude"],
+    knownPaths: [],
+    source: "built-in",
+    installCommand: "npm install -g @anthropic-ai/claude-code",
+    installMethod: "npm",
+  },
+  {
+    id: "codex",
+    name: "Codex",
+    command: "codex",
+    args: [],
+    description: "OpenAI Codex CLI",
+    binaryNames: ["codex"],
+    knownPaths: [],
+    source: "built-in",
+    installCommand: "npm install -g @openai/codex",
+    installMethod: "npm",
+  },
+  {
+    id: "gemini",
+    name: "Gemini CLI",
+    command: "gemini",
+    args: [],
+    description: "Google Gemini CLI",
+    binaryNames: ["gemini"],
+    knownPaths: [],
+    source: "built-in",
+    installCommand: "npm install -g @google/gemini-cli",
+    installMethod: "npm",
+  },
+  {
+    id: "goose",
+    name: "Goose",
+    command: "goose",
+    args: [],
+    description: "Block Goose — open source AI agent",
+    binaryNames: ["goose"],
+    knownPaths: [],
+    source: "built-in",
+    installCommand: "winget install Block.Goose",
+    installMethod: "winget",
+  },
+  {
+    id: "opencode",
+    name: "OpenCode",
+    command: "opencode",
+    args: [],
+    description: "OpenCode — open source AI coding agent",
+    binaryNames: ["opencode"],
+    knownPaths: [],
+    source: "built-in",
+    installCommand: "npm install -g opencode",
+    installMethod: "npm",
+  },
+];

package/src/lib/terminal.js

@@ -0,0 +1,607 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import readline from "node:readline/promises";
+import process from "node:process";
+
+const require = createRequire(import.meta.url);
+const { version: APP_VERSION } = require("../../package.json");
+
+const APP_BRAND = "agent-hub";
+const APP_WORDMARK = "AGENT HUB";
+const APP_COMMAND = "agent-hub";
+
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  black: "\x1b[30m",
+  gray: "\x1b[90m",
+  white: "\x1b[97m",
+  green: "\x1b[92m",
+  cyan: "\x1b[96m",
+  blue: "\x1b[94m",
+  magenta: "\x1b[95m",
+  yellow: "\x1b[93m",
+  red: "\x1b[91m",
+  bgBlack: "\x1b[40m",
+  bgWhite: "\x1b[107m",
+  bgGreen: "\x1b[102m",
+  bgCyan: "\x1b[106m",
+  bgBlue: "\x1b[44m",
+  bgYellow: "\x1b[43m",
+};
+
+// Unicode box-drawing characters
+const BOX = {
+  tl: "╔", tr: "╗", bl: "╚", br: "╝",
+  h: "═", v: "║",
+  ml: "╠", mr: "╣",
+};
+
+const THEMES = {
+  "vscode": {
+    name: "vscode",
+    logoTop: [ANSI.blue],
+    logoBottom: [ANSI.bold, ANSI.blue],
+    wordmark: [ANSI.bold, ANSI.blue],
+    headline: [ANSI.bold, ANSI.white],
+    subtext: [ANSI.white],
+    border: [ANSI.blue],
+    sep: [ANSI.blue],
+    chip: [ANSI.bold, ANSI.white, ANSI.bgBlue],
+    token: [ANSI.bold, ANSI.blue],
+    prompt: [ANSI.bold, ANSI.blue],
+    footer: [ANSI.white],
+    tip: [ANSI.bold, ANSI.cyan],
+    accent: [ANSI.bold, ANSI.blue],
+    key: [ANSI.bold, ANSI.white, ANSI.bgBlue],
+    missing: [ANSI.dim, ANSI.white],
+    installBadge: [ANSI.bold, ANSI.black, ANSI.bgYellow],
+  },
+  "cyber": {
+    name: "cyber",
+    logoTop: [ANSI.bold, ANSI.blue],
+    logoBottom: [ANSI.bold, ANSI.cyan],
+    wordmark: [ANSI.bold, ANSI.cyan],
+    headline: [ANSI.bold, ANSI.white],
+    subtext: [ANSI.dim, ANSI.gray],
+    border: [ANSI.bold, ANSI.cyan],
+    sep: [ANSI.dim, ANSI.cyan],
+    chip: [ANSI.bold, ANSI.black, ANSI.bgCyan],
+    token: [ANSI.bold, ANSI.cyan],
+    prompt: [ANSI.bold, ANSI.cyan],
+    footer: [ANSI.dim, ANSI.gray],
+    tip: [ANSI.bold, ANSI.yellow],
+    accent: [ANSI.bold, ANSI.blue],
+    key: [ANSI.bold, ANSI.black, ANSI.bgCyan],
+    missing: [ANSI.dim, ANSI.gray],
+    installBadge: [ANSI.bold, ANSI.black, ANSI.bgYellow],
+  },
+  "neon-dark": {
+    name: "neon-dark",
+    logoTop: [ANSI.bold, ANSI.gray],
+    logoBottom: [ANSI.bold, ANSI.green],
+    wordmark: [ANSI.bold, ANSI.green],
+    headline: [ANSI.bold, ANSI.white],
+    subtext: [ANSI.dim, ANSI.gray],
+    border: [ANSI.bold, ANSI.green],
+    sep: [ANSI.dim, ANSI.green],
+    chip: [ANSI.bold, ANSI.black, ANSI.bgGreen],
+    token: [ANSI.bold, ANSI.green],
+    prompt: [ANSI.bold, ANSI.green],
+    footer: [ANSI.dim, ANSI.gray],
+    tip: [ANSI.bold, ANSI.yellow],
+    accent: [ANSI.bold, ANSI.green],
+    key: [ANSI.bold, ANSI.black, ANSI.bgGreen],
+    missing: [ANSI.dim, ANSI.gray],
+    installBadge: [ANSI.bold, ANSI.black, ANSI.bgYellow],
+  },
+  "neon-light": {
+    name: "neon-light",
+    logoTop: [ANSI.bold, ANSI.white],
+    logoBottom: [ANSI.bold, ANSI.green],
+    wordmark: [ANSI.bold, ANSI.white],
+    headline: [ANSI.bold, ANSI.black, ANSI.bgWhite],
+    subtext: [ANSI.bold, ANSI.white],
+    border: [ANSI.bold, ANSI.white],
+    sep: [ANSI.dim, ANSI.white],
+    chip: [ANSI.bold, ANSI.black, ANSI.bgGreen],
+    token: [ANSI.bold, ANSI.white],
+    prompt: [ANSI.bold, ANSI.green],
+    footer: [ANSI.bold, ANSI.white],
+    tip: [ANSI.bold, ANSI.green],
+    accent: [ANSI.bold, ANSI.green],
+    key: [ANSI.bold, ANSI.black, ANSI.bgGreen],
+    missing: [ANSI.dim, ANSI.white],
+    installBadge: [ANSI.bold, ANSI.black, ANSI.bgYellow],
+  },
+};
+
+const TOOL_COLORS = {
+  aider: [ANSI.bold, ANSI.green],
+  claude: [ANSI.bold, ANSI.magenta],
+  codex: [ANSI.bold, ANSI.blue],
+  gemini: [ANSI.bold, ANSI.cyan],
+  goose: [ANSI.bold, ANSI.yellow],
+  opencode: [ANSI.bold, ANSI.white],
+};
+
+const LOGO_LINES = [
+  "    _    ____ _____ _   _ _____   _   _ _   _ ____  ",
+  "   / \\  / ___| ____| \\ | |_   _| | | | | | | | __ ) ",
+  "  / _ \\| |  _|  _| |  \\| | | |   | |_| | | | |  _ \\ ",
+  " / ___ \\ |_| | |___| |\\  | | |   |  _  | |_| | |_) |",
+  "/_/   \\_\\____|_____|_| \\_| |_|   |_| |_|\\___/|____/ ",
+];
+
+export function normalizeThemeName(value = "vscode") {
+  return Object.hasOwn(THEMES, value) ? value : "vscode";
+}
+
+export function printScanTable(tools, options = {}) {
+  const showActions = options.showActions ?? true;
+  const theme = getTheme(options.theme);
+
+  if (showActions && process.stdout.isTTY) {
+    process.stdout.write("\x1Bc");
+  }
+
+  console.log(buildDashboard(tools, { showActions, theme }));
+}
+
+export async function promptForToolSelection(tools, options = {}) {
+  const theme = getTheme(options.theme);
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    while (true) {
+      const answer = (await rl.question(`  ${paint("›", ...theme.prompt)} `))
+        .trim()
+        .toLowerCase();
+
+      if (!answer || answer === "q" || answer === "quit") {
+        return null;
+      }
+
+      if (answer === "r" || answer === "rescan") {
+        return "rescan";
+      }
+
+      if (tools.length === 0) {
+        console.log(`  ${paint("!", ...theme.tip)} ${paint("No tools found. Press r to rescan or q to quit.", ...theme.subtext)}`);
+        continue;
+      }
+
+      const byIndex = Number.parseInt(answer, 10);
+      if (Number.isInteger(byIndex) && byIndex >= 1 && byIndex <= tools.length) {
+        return tools[byIndex - 1];
+      }
+
+      const byId = tools.find((tool) => tool.id.toLowerCase() === answer);
+      if (byId) {
+        return byId;
+      }
+
+      console.log(`  ${paint("?", ...theme.subtext)} ${paint("Unknown. Enter a number, tool id, r or q.", ...theme.subtext)}`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+export async function launchTool(tool, options = {}) {
+  const theme = getTheme(options.theme);
+
+  if (process.stdout.isTTY) {
+    process.stdout.write("\x1Bc");
+  }
+
+  const panelWidth = Math.min(Math.max((process.stdout.columns ?? 100) - 8, 54), 76);
+  console.log(buildLaunchPanel(tool, panelWidth, theme));
+  console.log("");
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(tool.launchCommand, tool.args, {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: "inherit",
+      shell: shouldUseShell(tool.launchCommand),
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        console.log(`\n  ${paint("◆", ...theme.accent)} ${paint(`${tool.name} terminated with signal ${signal}.`, ...theme.subtext)}`);
+      } else if (typeof code === "number" && code !== 0) {
+        console.log(`\n  ${paint("◆", ...theme.accent)} ${paint(`${tool.name} exited with code ${code}.`, ...theme.subtext)}`);
+      }
+
+      resolve();
+    });
+  });
+
+  console.log(`  ${paint("◆", ...theme.accent)} ${paint("Returned to AGENT HUB.", ...theme.subtext)}`);
+}
+
+export async function installTool(tool, options = {}) {
+  const theme = getTheme(options.theme);
+
+  if (process.stdout.isTTY) {
+    process.stdout.write("\x1Bc");
+  }
+
+  const panelWidth = Math.min(Math.max((process.stdout.columns ?? 100) - 8, 54), 76);
+  console.log(buildInstallPanel(tool, panelWidth, theme));
+  console.log("");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  let confirmed = false;
+  try {
+    const answer = (
+      await rl.question(
+        `  ${paint("Install now?", ...theme.prompt)} ${paint("[y/n]", ...theme.subtext)} `,
+      )
+    )
+      .trim()
+      .toLowerCase();
+    confirmed = answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+
+  if (!confirmed) {
+    console.log(`  ${paint("◆", ...theme.accent)} ${paint("Installation cancelled.", ...theme.subtext)}`);
+    return false;
+  }
+
+  console.log(`\n  ${paint("◆", ...theme.accent)} ${paint(`Running: ${tool.installCommand}`, ...theme.subtext)}`);
+  console.log("");
+
+  const parts = tool.installCommand.split(" ");
+  const cmd = parts[0];
+  const args = parts.slice(1);
+
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: "inherit",
+      shell: true,
+    });
+
+    child.on("error", (err) => {
+      console.log(`\n  ${paint("✗", ...theme.tip)} ${paint(`Install failed: ${err.message}`, ...theme.subtext)}`);
+      resolve(false);
+    });
+
+    child.on("exit", (code) => {
+      if (code === 0) {
+        console.log(`\n  ${paint("✓", ...theme.accent)} ${paint(`${tool.name} installed successfully.`, ...theme.subtext)}`);
+      } else {
+        console.log(`\n  ${paint("✗", ...theme.tip)} ${paint(`Install exited with code ${code}.`, ...theme.subtext)}`);
+      }
+      resolve(code === 0);
+    });
+  });
+}
+
+function getTheme(themeName) {
+  return THEMES[normalizeThemeName(themeName)];
+}
+
+function buildDashboard(tools, options) {
+  const terminalWidth = process.stdout.columns ?? 100;
+  const panelWidth = Math.min(Math.max(terminalWidth - 10, 54), 80);
+  const lines = [];
+
+  lines.push("");
+  lines.push(...centerLogo(terminalWidth, options.theme));
+  lines.push("");
+  lines.push(...centerBlock(buildPromptPanel(tools, panelWidth, options.theme, options.showActions), terminalWidth));
+  lines.push("");
+
+  if (options.showActions) {
+    lines.push(
+      centerText(
+        `${paint("◆", ...options.theme.tip)} ${paint("Tip:", ...options.theme.tip)} ${paint(
+          "add custom tools via .agent-hub.json",
+          ...options.theme.subtext,
+        )}`,
+        terminalWidth,
+      ),
+    );
+    lines.push("");
+  }
+
+  lines.push(buildFooter(terminalWidth, options.theme));
+
+  return lines.join("\n");
+}
+
+function buildPromptPanel(allTools, panelWidth, theme, showActions) {
+  const innerWidth = panelWidth - 4; // 2 border chars + 2 padding spaces
+  const borderH = BOX.h.repeat(panelWidth - 2);
+  const sepH = BOX.h.repeat(panelWidth - 2);
+
+  const V = paint(BOX.v, ...theme.border);
+  const row = (content) => `${V} ${content} ${V}`;
+  const innerSep = `${paint(BOX.ml, ...theme.border)}${paint(sepH, ...theme.sep)}${paint(BOX.mr, ...theme.border)}`;
+
+  // Header: AGENT HUB + version
+  const titleText = paint(APP_WORDMARK, ...theme.wordmark);
+  const versionText = paint(`v${APP_VERSION}`, ...theme.subtext);
+  const titleGap = Math.max(1, innerWidth - visibleLength(titleText) - visibleLength(versionText));
+  const headerLine = row(`${titleText}${" ".repeat(titleGap)}${versionText}`);
+  const subtitleLine = row(padVisible(` ${paint("terminal switchboard for AI coding CLIs", ...theme.subtext)}`, innerWidth));
+
+  // Split tools into installed / installable
+  const installedTools = allTools.filter((t) => t.available);
+  const missingTools = allTools.filter((t) => !t.available && t.installCommand);
+
+  // Installed section
+  const installedCount = installedTools.length;
+  const installedLabel =
+    installedCount === 0
+      ? paint("NO TOOLS INSTALLED", ...theme.tip)
+      : `${paint("INSTALLED", ...theme.headline)}  ${paint(`${installedCount} tool${installedCount === 1 ? "" : "s"} ready`, ...theme.subtext)}`;
+  const installedSectionLine = row(padVisible(` ${installedLabel}`, innerWidth));
+
+  const installedBodyLines = [];
+  if (installedTools.length === 0) {
+    installedBodyLines.push(row(" ".repeat(innerWidth)));
+    installedBodyLines.push(
+      row(
+        padVisible(
+          ` ${paint("No AI CLIs detected. Enter a number below to install one.", ...theme.subtext)}`,
+          innerWidth,
+        ),
+      ),
+    );
+    installedBodyLines.push(row(" ".repeat(innerWidth)));
+  } else {
+    installedBodyLines.push(row(" ".repeat(innerWidth)));
+    for (const gridRow of buildNumberedGrid(installedTools, allTools, theme, innerWidth - 1, true)) {
+      installedBodyLines.push(row(padVisible(` ${gridRow}`, innerWidth)));
+    }
+    installedBodyLines.push(row(" ".repeat(innerWidth)));
+  }
+
+  // Installable section (only when there are missing tools)
+  const installableLines = [];
+  if (missingTools.length > 0) {
+    const missingCount = missingTools.length;
+    const missingLabel = `${paint("INSTALLABLE", ...theme.installBadge)}  ${paint(`${missingCount} tool${missingCount === 1 ? "" : "s"} not installed`, ...theme.missing)}`;
+    installableLines.push(innerSep);
+    installableLines.push(row(padVisible(` ${missingLabel}`, innerWidth)));
+    installableLines.push(row(" ".repeat(innerWidth)));
+    for (const gridRow of buildNumberedGrid(missingTools, allTools, theme, innerWidth - 1, false)) {
+      installableLines.push(row(padVisible(` ${gridRow}`, innerWidth)));
+    }
+    installableLines.push(row(" ".repeat(innerWidth)));
+  }
+
+  // Action bar
+  const actionLines = [];
+  if (showActions) {
+    const keyHint = (key, label) =>
+      `${paint(` ${key} `, ...theme.key)} ${paint(label, ...theme.subtext)}`;
+    const dots = paint("  ·  ", ...theme.subtext);
+    const hintParts = [
+      keyHint("n", "select"),
+      keyHint("r", "rescan"),
+      keyHint("q", "quit"),
+    ];
+    actionLines.push(row(padVisible(` ${hintParts.join(dots)}`, innerWidth)));
+  } else {
+    actionLines.push(row(padVisible(` ${paint(`preview · ${theme.name}`, ...theme.subtext)}`, innerWidth)));
+  }
+
+  return [
+    `${paint(BOX.tl, ...theme.border)}${paint(borderH, ...theme.border)}${paint(BOX.tr, ...theme.border)}`,
+    headerLine,
+    subtitleLine,
+    innerSep,
+    installedSectionLine,
+    ...installedBodyLines,
+    ...installableLines,
+    innerSep,
+    ...actionLines,
+    `${paint(BOX.bl, ...theme.border)}${paint(borderH, ...theme.border)}${paint(BOX.br, ...theme.border)}`,
+  ];
+}
+
+// Builds a 2-column grid for a subset of tools, using global index for numbering.
+function buildNumberedGrid(subTools, allTools, theme, maxWidth, isInstalled) {
+  const colWidth = Math.floor(maxWidth / 2);
+  const tokens = subTools.map((tool) => {
+    const globalIndex = allTools.findIndex((t) => t.id === tool.id);
+    const num = String(globalIndex + 1).padStart(2, "0");
+
+    if (isInstalled) {
+      const dot = paint("●", ...getToolColor(tool));
+      const numBadge = paint(` ${num} `, ...theme.chip);
+      const nameStr = paint(tool.id, ...getToolColor(tool));
+      return `${dot} ${numBadge}  ${nameStr}`;
+    } else {
+      const dot = paint("○", ...theme.missing);
+      const numBadge = paint(` ${num} `, ...theme.installBadge);
+      const nameStr = paint(tool.id, ...theme.missing);
+      return `${dot} ${numBadge}  ${nameStr}`;
+    }
+  });
+
+  const rows = [];
+  for (let i = 0; i < tokens.length; i += 2) {
+    const left = tokens[i];
+    const right = tokens[i + 1];
+    if (right) {
+      rows.push(`${padVisible(left, colWidth)}  ${right}`);
+    } else {
+      rows.push(left);
+    }
+  }
+
+  return rows;
+}
+
+function buildLaunchPanel(tool, panelWidth, theme) {
+  const innerWidth = panelWidth - 4;
+  const borderH = BOX.h.repeat(panelWidth - 2);
+  const sepH = BOX.h.repeat(panelWidth - 2);
+
+  const V = paint(BOX.v, ...theme.border);
+  const row = (content) => `${V} ${content} ${V}`;
+  const innerSep = `${paint(BOX.ml, ...theme.border)}${paint(sepH, ...theme.sep)}${paint(BOX.mr, ...theme.border)}`;
+
+  const commandPath = truncateMiddle(tool.resolvedPath ?? tool.launchCommand ?? tool.command, innerWidth - 8);
+  const toolColor = getToolColor(tool);
+
+  const nameText = paint(tool.name, ...toolColor);
+  const idText = paint(`  ${tool.id}`, ...theme.subtext);
+  const headerLine = row(padVisible(` ${nameText}${idText}`, innerWidth));
+
+  const pathLine = row(padVisible(` ${paint("path", ...theme.prompt)}  ${paint(commandPath, ...theme.headline)}`, innerWidth));
+  const hintLine = row(padVisible(` ${paint("Exit the CLI to return to AGENT HUB", ...theme.subtext)}`, innerWidth));
+
+  const lines = [
+    `${paint(BOX.tl, ...theme.border)}${paint(borderH, ...theme.border)}${paint(BOX.tr, ...theme.border)}`,
+    headerLine,
+    innerSep,
+    pathLine,
+    hintLine,
+    `${paint(BOX.bl, ...theme.border)}${paint(borderH, ...theme.border)}${paint(BOX.br, ...theme.border)}`,
+  ];
+
+  return centerBlock(lines, process.stdout.columns ?? 100).join("\n");
+}
+
+function buildInstallPanel(tool, panelWidth, theme) {
+  const innerWidth = panelWidth - 4;
+  const borderH = BOX.h.repeat(panelWidth - 2);
+  const sepH = BOX.h.repeat(panelWidth - 2);
+
+  const V = paint(BOX.v, ...theme.border);
+  const row = (content) => `${V} ${content} ${V}`;
+  const innerSep = `${paint(BOX.ml, ...theme.border)}${paint(sepH, ...theme.sep)}${paint(BOX.mr, ...theme.border)}`;
+
+  const nameText = paint(tool.name, ...theme.wordmark);
+  const notInstalledText = paint("not installed", ...theme.missing);
+  const headerLine = row(padVisible(` ${nameText}  ${notInstalledText}`, innerWidth));
+
+  const cmdText = paint(tool.installCommand, ...theme.headline);
+  const cmdLine = row(padVisible(` ${paint("command", ...theme.prompt)}  ${cmdText}`, innerWidth));
+
+  const descLine = row(padVisible(` ${paint(tool.description, ...theme.subtext)}`, innerWidth));
+
+  const methodText = paint(`via ${tool.installMethod ?? "system"}`, ...theme.subtext);
+  const methodLine = row(padVisible(` ${methodText}`, innerWidth));
+
+  const lines = [
+    `${paint(BOX.tl, ...theme.border)}${paint(borderH, ...theme.border)}${paint(BOX.tr, ...theme.border)}`,
+    headerLine,
+    innerSep,
+    cmdLine,
+    descLine,
+    methodLine,
+    `${paint(BOX.bl, ...theme.border)}${paint(borderH, ...theme.border)}${paint(BOX.br, ...theme.border)}`,
+  ];
+
+  return centerBlock(lines, process.stdout.columns ?? 100).join("\n");
+}
+
+function centerLogo(terminalWidth, theme) {
+  return LOGO_LINES.map((line, index) => {
+    const style = index < 2 ? theme.logoTop : theme.logoBottom;
+    return centerText(paint(line, ...style), terminalWidth);
+  });
+}
+
+function centerBlock(lines, terminalWidth) {
+  return lines.map((line) => centerText(line, terminalWidth));
+}
+
+function centerText(text, terminalWidth) {
+  const padding = Math.max(0, Math.floor((terminalWidth - visibleLength(text)) / 2));
+  return `${" ".repeat(padding)}${text}`;
+}
+
+function buildFooter(terminalWidth, theme) {
+  const left = `${paint("◆", ...theme.accent)} ${paint(shrinkHomePath(process.cwd()), ...theme.footer)}`;
+  const right = `${paint(APP_COMMAND, ...theme.footer)} ${paint(`v${APP_VERSION}`, ...theme.subtext)}`;
+  const gap = Math.max(2, terminalWidth - visibleLength(left) - visibleLength(right));
+  return `${left}${" ".repeat(gap)}${right}`;
+}
+
+function visibleLength(text) {
+  return stripAnsi(text).length;
+}
+
+function padVisible(text, width) {
+  const padding = Math.max(0, width - visibleLength(text));
+  return `${text}${" ".repeat(padding)}`;
+}
+
+function stripAnsi(text) {
+  return text.replace(/\x1B\[[0-9;]*m/g, "");
+}
+
+function getToolColor(tool) {
+  return TOOL_COLORS[tool.id] ?? [ANSI.bold, ANSI.cyan];
+}
+
+function truncateMiddle(value, maxLength) {
+  if (value.length <= maxLength) {
+    return value;
+  }
+
+  const usable = maxLength - 3;
+  const left = Math.ceil(usable / 2);
+  const right = Math.floor(usable / 2);
+  return `${value.slice(0, left)}...${value.slice(value.length - right)}`;
+}
+
+function shrinkHomePath(value) {
+  const home = process.env.USERPROFILE ?? process.env.HOME;
+  if (home && value.startsWith(home)) {
+    return `~${value.slice(home.length)}`;
+  }
+
+  return value;
+}
+
+function paint(text, ...codes) {
+  if (!supportsColor()) {
+    return text;
+  }
+
+  return `${codes.join("")}${text}${ANSI.reset}`;
+}
+
+function supportsColor() {
+  if ("NO_COLOR" in process.env) {
+    return false;
+  }
+
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") {
+    return true;
+  }
+
+  return Boolean(process.stdout.isTTY);
+}
+
+function shouldUseShell(command) {
+  if (process.platform !== "win32") {
+    return false;
+  }
+
+  const extension = path.extname(command).toLowerCase();
+  return extension === ".cmd" || extension === ".bat";
+}