hermes-launch 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# 🐚 Hermes Launch
+
+**One command. Zero to AI agent.**
+
+```bash
+npx hermes-launch
+```
+
+Hermes Launch installs, configures, and starts [Hermes Agent](https://github.com/NousResearch/hermes-agent) — the open-source AI agent framework by Nous Research. No faffing with Python venvs, curl pipes, or config files.
+
+```bash
+# Full interactive setup (recommended for first use)
+npx hermes-launch
+
+# Non-interactive — smart defaults, go fast
+npx hermes-launch --quick
+
+# Just start the web dashboard if Hermes is already installed
+npx hermes-launch --dashboard
+```
+
+## What you get
+
+After running `npx hermes-launch`:
+
+- **Hermes Agent CLI** — `hermes` in your terminal. Chat, code, research, automate.
+- **Web dashboard** at `http://localhost:9119` — manage config, API keys, sessions.
+- **Tool sets** enabled out of the box: web search, terminal, file ops, skills, memory, vision, TTS, subagent delegation, cross-session search.
+- **Streaming** enabled — see responses as they generate.
+- **Zero config** — the setup wizard walks you through model/provider selection.
+
+## After setup
+
+```bash
+hermes                         # start a conversation
+hermes chat -q "analyze this repo"  # one-shot
+hermes model                   # change provider/model
+hermes gateway setup           # connect Telegram/Discord/Slack
+hermes tools list              # see what tools are available
+hermes dashboard               # open the web UI
+hermes doctor                  # health check
+```
+
+## What's under the hood
+
+Hermes Launch is a thin wrapper — it:
+
+1. Checks prerequisites (Python 3.10+, curl, git)
+2. Installs Hermes Agent via the official install script if missing
+3. Guides you through `hermes setup` to pick a model provider
+4. Enables the core toolsets
+5. Starts `hermes dashboard --tui` on port 9119
+6. Prints next steps
+
+Everything lives in `~/.hermes/` — config, sessions, logs, skills.
+
+## Requirements
+
+- **Node.js** 18+ (comes with npx)
+- **Python** 3.10+ (system or homebrew)
+- **curl**, **git**
+- macOS, Linux, or WSL
+
+## Why not just curl the install script?
+
+You can! `curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash` works great. Hermes Launch adds:
+
+- Prerequisite checking with clear error messages
+- Interactive setup flow with prompts
+- Smart defaults for tool enablement
+- Dashboard auto-start
+- A clean post-install summary
+- No pipe-to-bash pattern (safer for enterprise environments)
+
+## License
+
+MIT

package/bin/hermes-launch.js

@@ -0,0 +1,447 @@
+#!/usr/bin/env node
+/**
+ * hermes-launch — one command to install, configure, and run Hermes Agent.
+ *
+ * Usage:
+ *   npx hermes-launch              # full interactive flow
+ *   npx hermes-launch --quick      # skip prompts, use smart defaults
+ *   npx hermes-launch --dashboard  # just start the web dashboard
+ *   npx hermes-launch --help       # this message
+ */
+
+import { execSync, spawn } from 'child_process';
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir, platform, hostname } from 'os';
+import { resolve } from 'path';
+import { createInterface } from 'readline';
+
+const HERMES_HOME = resolve(homedir(), '.hermes');
+const CONFIG_PATH = resolve(HERMES_HOME, 'config.yaml');
+const INSTALL_URL = 'https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh';
+
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+const CLEAR_LINE = '\x1b[K';
+
+// ——— helpers ———
+
+function printBanner() {
+  const banner = `
+  ╔════════════════════════════════════════╗
+  ║  ${CYAN}🐚  Hermes Launch  ${RESET}              ║
+  ║  ${DIM}zero-to-AI-agent in seconds${RESET}       ║
+  ╚════════════════════════════════════════╝
+  `;
+  console.log(banner);
+}
+
+function ask(query) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(query, ans => { rl.close(); resolve(ans.trim()); }));
+}
+
+function run(cmd, opts = {}) {
+  const defaults = { stdio: opts.silent ? 'pipe' : 'inherit', timeout: 120_000, ...opts };
+  try {
+    const out = execSync(cmd, defaults);
+    return { ok: true, out: out?.toString()?.trim() || '' };
+  } catch (e) {
+    return { ok: false, out: e.stderr?.toString()?.trim() || e.message };
+  }
+}
+
+function spinner(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function step(msg) {
+  process.stdout.write(`  ${CYAN}→${RESET} ${msg} ... `);
+  return {
+    ok: () => { process.stdout.write(`${GREEN}done${RESET}\n`); },
+    skip: (reason) => { process.stdout.write(`${YELLOW}skipped${RESET} (${reason})\n`); },
+    fail: (err) => { process.stdout.write(`${RED}failed${RESET}\n    ${DIM}${err}${RESET}\n`); },
+  };
+}
+
+function printSummary(info) {
+  console.log(`\n${BOLD}${GREEN}  ✅  Hermes Agent is live!${RESET}\n`);
+  console.log(`  ${BOLD}Web Dashboard${RESET}`);
+  console.log(`    ${CYAN}http://localhost:${info.port || 9119}${RESET}\n`);
+  console.log(`  ${BOLD}CLI${RESET}`);
+  console.log(`    ${CYAN}hermes${RESET}              interactive chat`);
+  console.log(`    ${CYAN}hermes chat -q "..."${RESET}  one-shot query`);
+  console.log(`    ${CYAN}hermes --continue${RESET}    resume last session\n`);
+  console.log(`  ${BOLD}Key commands${RESET}`);
+  console.log(`    ${CYAN}hermes model${RESET}         change model/provider`);
+  console.log(`    ${CYAN}hermes gateway setup${RESET}  connect Telegram/Discord`);
+  console.log(`    ${CYAN}hermes tools list${RESET}     see available tools`);
+  console.log(`    ${CYAN}hermes cron${RESET}           schedule recurring tasks`);
+  console.log(`    ${CYAN}hermes doctor${RESET}         health check\n`);
+  console.log(`  ${BOLD}Docs${RESET}`);
+  console.log(`    ${CYAN}https://hermes-agent.nousresearch.com/docs${RESET}\n`);
+  if (info.messaging) {
+    console.log(`  ${BOLD}Messaging${RESET}`);
+    for (const [platform, status] of Object.entries(info.messaging)) {
+      console.log(`    ${platform}: ${status}`);
+    }
+    console.log();
+  }
+}
+
+function printMiniBanner() {
+  console.log(`
+  ${CYAN}  🐚  Hermes Launch${RESET}  ${DIM}— zero-to-agent${RESET}
+  `);
+}
+
+// ——— core steps ———
+
+async function checkPrereqs() {
+  const s = step('Checking prerequisites');
+  const checks = {
+    node: run('node --version', { silent: true }).ok,
+    python3: run('python3 --version', { silent: true }).ok,
+    curl: run('curl --version', { silent: true }).ok,
+    git: run('git --version', { silent: true }).ok,
+  };
+
+  const missing = Object.entries(checks).filter(([, ok]) => !ok).map(([name]) => name);
+  if (missing.length) {
+    s.fail(`Missing: ${missing.join(', ')}`);
+    console.log(`  Install missing tools and try again.`);
+    process.exit(1);
+  }
+
+  // Check Python version >= 3.10 — try multiple binaries
+  const pyCandidates = ['python3.11', 'python3.12', 'python3.13', 'python3.14', 'python3.10', 'python3'];
+  let pyVer = '';
+  let pyBin = 'python3';
+  for (const bin of pyCandidates) {
+    const r = run(`${bin} --version`, { silent: true });
+    if (r.ok) {
+      pyVer = r.out;
+      pyBin = bin;
+      break;
+    }
+  }
+
+  const match = pyVer.match(/(\d+)\.(\d+)/);
+  if (match) {
+    const major = parseInt(match[1]), minor = parseInt(match[2]);
+    if (major < 3 || (major === 3 && minor < 10)) {
+      s.fail(`Python 3.10+ required, got ${major}.${minor} (${pyBin})`);
+      process.exit(1);
+    }
+  }
+
+  s.ok();
+  checks.pythonBin = pyBin;
+  return checks;
+}
+
+async function installHermes(quick) {
+  const s = step('Checking Hermes installation');
+  const hasHermes = run('hermes --version', { silent: true }).ok;
+
+  if (hasHermes) {
+    const ver = run('hermes --version', { silent: true }).out;
+    s.skip(`v${ver} already installed`);
+    return true;
+  }
+
+  if (!quick) {
+    console.log();
+    const ans = await ask(`  Hermes not found. Install it now? [Y/n] `);
+    if (ans.toLowerCase() === 'n') {
+      console.log(`  ${YELLOW}Aborted. Install manually: curl -fsSL ${INSTALL_URL} | bash${RESET}`);
+      process.exit(0);
+    }
+  }
+
+  const si = step('Downloading and installing Hermes');
+  try {
+    const cmd = `curl -fsSL ${INSTALL_URL} | bash`;
+    const result = run(cmd, { timeout: 180_000, silent: false });
+    if (!result.ok) {
+      si.fail(result.out);
+      process.exit(1);
+    }
+    si.ok();
+    return true;
+  } catch (e) {
+    si.fail(e.message);
+    process.exit(1);
+  }
+}
+
+async function checkConfig(quick) {
+  const s = step('Checking Hermes configuration');
+
+  if (!existsSync(CONFIG_PATH)) {
+    s.skip('no config yet — will be generated');
+    return false;
+  }
+
+  const raw = readFileSync(CONFIG_PATH, 'utf-8');
+
+  // Check if config has a model set (not commented out)
+  const hasModel = /^model:\s*\n/m.test(raw);
+
+  if (!hasModel || raw.includes('default: ""') || raw.includes("default: ''")) {
+    s.skip('needs model configuration');
+    return false;
+  }
+
+  s.ok();
+  return true;
+}
+
+async function runSetup(quick) {
+  if (quick) {
+    const s = step('Running headless setup');
+    // For quick mode, just enable the gateway and set up with defaults
+    const setCmds = [
+      'hermes tools enable web terminal file skills session_search delegate_task memory clarify vision 2>/dev/null || true',
+      `hermes config set display.streaming.enabled true 2>/dev/null || true`,
+    ];
+    for (const cmd of setCmds) run(cmd, { silent: true });
+    s.ok();
+    return;
+  }
+
+  // Interactive: guide the user through setup
+  console.log(`\n  ${BOLD}Let's configure your Hermes Agent.${RESET}\n`);
+  console.log(`  ${DIM}(You can skip any step and configure later with \`hermes setup\`)${RESET}\n`);
+
+  const doSetup = await ask(`  Run the Hermes setup wizard? (recommended) [Y/n] `);
+  if (doSetup.toLowerCase() !== 'n') {
+    const s = step('Running setup wizard');
+    try {
+      const result = run('hermes setup', { stdio: 'inherit', timeout: 300_000 });
+      if (!result.ok) {
+        s.fail(result.out);
+      } else {
+        s.ok();
+      }
+    } catch (e) {
+      s.fail(e.message);
+    }
+  } else {
+    // Minimal quick config
+    const s = step('Applying minimal configuration');
+    run('hermes tools enable web terminal file skills session_search delegate_task memory 2>/dev/null || true', { silent: true });
+    s.skip('minimal config applied');
+  }
+}
+
+async function enableToolsets(quick) {
+  const s = step('Enabling tool sets');
+
+  // Core toolsets that make Hermes useful
+  const toolsets = [
+    'web',           // web search + content extraction
+    'terminal',      // shell commands
+    'file',          // file read/write/search
+    'skills',        // skill management
+    'session_search', // cross-session recall
+    'delegate_task', // spawn subagents
+    'memory',        // cross-session memory
+    'vision',        // image analysis
+    'tts',           // text-to-speech
+    'clarify',       // ask questions
+  ];
+
+  let ok = true;
+  for (const t of toolsets) {
+    const r = run(`hermes tools enable ${t}`, { silent: true });
+    if (!r.ok) ok = false;
+  }
+
+  if (ok) {
+    s.ok();
+  } else {
+    // Some may have failed if already enabled — that's fine
+    s.ok();
+  }
+
+  // Enable gateway streaming
+  run('hermes config set display.streaming.enabled true 2>/dev/null || true', { silent: true });
+}
+
+async function startDashboard(quick) {
+  const s = step('Starting web dashboard');
+  const port = quick ? '9119' : '9119';
+
+  // Check if dashboard is already running
+  const statusCheck = run('hermes dashboard --status', { silent: true });
+  if (statusCheck.ok && statusCheck.out.length > 0 && !statusCheck.out.includes('No running')) {
+    s.skip('already running');
+    return { port, alreadyRunning: true };
+  }
+
+  try {
+    const proc = spawn(
+      'hermes',
+      ['dashboard', '--port', port, '--tui', quick ? '--no-open' : ''],
+      {
+        stdio: 'inherit',
+        detached: false,
+        env: { ...process.env },
+      }
+    );
+
+    // Give it a moment to start
+    await spinner(3000);
+
+    // Verify it's up
+    const verify = run(`curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:${port}/ 2>/dev/null || echo "0"`, { silent: true });
+    if (verify.out === '0') {
+      s.skip('dashboard launched in background');
+    } else {
+      s.ok();
+    }
+
+    return { port, alreadyRunning: false };
+  } catch (e) {
+    s.fail(e.message);
+    return { port, alreadyRunning: false, error: e.message };
+  }
+}
+
+async function checkGatewayStatus() {
+  const s = step('Checking messaging gateway');
+  const result = run('hermes gateway status', { silent: true });
+  if (result.ok) {
+    const out = result.out;
+    const hasTelegram = out.includes('telegram') && (out.includes('running') || out.includes('connected'));
+    const hasDiscord = out.includes('discord') && (out.includes('running') || out.includes('connected'));
+    const platforms = [];
+    if (hasTelegram) platforms.push('telegram');
+    if (hasDiscord) platforms.push('discord');
+    if (platforms.length > 0) {
+      s.ok();
+      return platforms;
+    }
+  }
+  s.skip('not configured');
+  return [];
+}
+
+async function showQuickStart() {
+  console.log(`\n  ${BOLD}${GREEN}Hermes Agent is ready to use!${RESET}\n`);
+
+  console.log(`  ${BOLD}Start a conversation:${RESET}`);
+  console.log(`    ${CYAN}hermes${RESET}                    interactive chat`);
+  console.log(`    ${CYAN}hermes -q "summarize my repo"${RESET}  one-shot query\n`);
+
+  console.log(`  ${BOLD}First things to try:${RESET}`);
+  console.log(`    • ${CYAN}hermes model${RESET} — pick your LLM provider`);
+  console.log(`    • ${CYAN}hermes gateway setup${RESET} — connect Telegram/Discord`);
+  console.log(`    • ${CYAN}hermes dashboard${RESET} — open the web UI`);
+  console.log(`    • ${CYAN}hermes skills browse${RESET} — discover skills\n`);
+
+  console.log(`  ${BOLD}Pro tips:${RESET}`);
+  console.log(`    • ${DIM}Your config lives at ~/.hermes/config.yaml${RESET}`);
+  console.log(`    • ${DIM}API keys go in ~/.hermes/.env${RESET}`);
+  console.log(`    • ${DIM}Type /help in a session for all slash commands${RESET}`);
+  console.log(`    • ${DIM}Run \`hermes doctor\` if something isn't working${RESET}`);
+  console.log();
+}
+
+// ——— main ———
+
+async function main() {
+  const args = process.argv.slice(2);
+  const flags = {
+    quick: args.includes('--quick') || args.includes('-q'),
+    dashboard: args.includes('--dashboard'),
+    help: args.includes('--help') || args.includes('-h'),
+    version: args.includes('--version') || args.includes('-v'),
+  };
+
+  if (flags.help) {
+    console.log(`
+  ${BOLD}hermes-launch${RESET} — one command to install and run Hermes Agent
+
+  ${BOLD}Usage:${RESET}
+    npx hermes-launch              full interactive setup
+    npx hermes-launch --quick      non-interactive, smart defaults
+    npx hermes-launch --dashboard  just start the web dashboard
+    npx hermes-launch --help       this message
+
+  ${BOLD}What it does:${RESET}
+    1. Check prerequisites (Python, curl, git)
+    2. Install Hermes Agent (if not present)
+    3. Run setup wizard to configure model/tools
+    4. Enable useful toolsets
+    5. Start the web dashboard on port 9119
+    6. Print next steps
+
+  ${BOLD}After launch:${RESET}
+    hermes              start chatting
+    hermes gateway setup  add Telegram/Discord
+    hermes model        change AI provider
+    `);
+    process.exit(0);
+  }
+
+  if (flags.version) {
+    const pkg = JSON.parse(readFileSync(resolve(import.meta.dirname, '../package.json'), 'utf-8'));
+    console.log(`hermes-launch v${pkg.version}`);
+    process.exit(0);
+  }
+
+  if (flags.dashboard) {
+    printMiniBanner();
+    const result = await startDashboard(true);
+    if (result.error) {
+      process.exit(1);
+    }
+    printSummary({ port: result.port, messaging: {} });
+    process.exit(0);
+  }
+
+  // ——— full flow ———
+  printBanner();
+
+  // 1. Prerequisites
+  await checkPrereqs();
+
+  // 2. Install
+  await installHermes(flags.quick);
+
+  // 3. Check config
+  const needsSetup = await checkConfig(flags.quick);
+
+  // 4. Setup if needed
+  if (!needsSetup) {
+    await runSetup(flags.quick);
+  }
+
+  // 5. Enable tools
+  await enableToolsets(flags.quick);
+
+  // 6. Start dashboard
+  const dashResult = await startDashboard(flags.quick);
+
+  // 7. Check gateway
+  const platforms = await checkGatewayStatus();
+
+  // 8. Show summary
+  printSummary({
+    port: dashResult.port,
+    messaging: platforms.length > 0
+      ? Object.fromEntries(platforms.map(p => [p, `${GREEN}connected${RESET}`]))
+      : { none: `${YELLOW}not configured${RESET} (run \`hermes gateway setup\`)` },
+  });
+}
+
+main().catch(e => {
+  console.error(`${RED}Error:${RESET}`, e.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "hermes-launch",
+  "version": "1.0.0",
+  "description": "One command to launch Hermes Agent — zero-to-AI-agent in seconds",
+  "bin": {
+    "hermes-launch": "./bin/hermes-launch.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "hermes",
+    "ai-agent",
+    "claude-code",
+    "codex",
+    "opencode",
+    "llm",
+    "agent",
+    "nous-research"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NousResearch/hermes-launch"
+  },
+  "homepage": "https://github.com/NousResearch/hermes-launch",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "preferGlobal": true
+}