heyhank 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The Vibe Company
+
+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

@@ -1,26 +1,37 @@
-# HeyHank
+<p align="center">
+  <img src="public/logo.svg" alt="HeyHank" width="80" />
+</p>
 
-Self-hosted web UI for running Claude Code and Codex agents. Multi-session management with streaming, tool call visibility, and permission control.
+<h1 align="center">HeyHank</h1>
+<p align="center"><strong>Self-hosted web UI for running Claude Code and Codex agents.</strong></p>
+<p align="center">Multi-session management with streaming, tool call visibility, and permission control.</p>
 
-## Install
+<p align="center">
+  <a href="https://www.npmjs.com/package/heyhank"><img src="https://img.shields.io/npm/v/heyhank.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/heyhank"><img src="https://img.shields.io/npm/dm/heyhank.svg" alt="npm downloads" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /></a>
+</p>
+
+## Quick Start
+
+**Requirements:** [Bun](https://bun.sh) v1.0+ and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and/or [Codex](https://github.com/openai/codex) CLI.
 
 ```bash
 bunx heyhank
 ```
 
-Requires [Bun](https://bun.sh) v1.0+.
+Open [http://localhost:3456](http://localhost:3456).
 
-## Usage
+### Install Globally
 
 ```bash
-# Start the server
-heyhank serve
+bun install -g heyhank
 
-# Install as background service
+# Register as a background service (launchd on macOS, systemd on Linux)
 heyhank install
 
-# Check status
-heyhank status
+# Start the service
+heyhank start
 ```
 
 ## Features
@@ -30,11 +41,73 @@ heyhank status
 - **Scheduled Agents** — Cron-based agent automation
 - **Media Generation** — Image (Imagen 4) and video (Veo 3.1) generation
 - **Social Media** — Multi-backend posting (Postiz, Buffer, Ayrshare)
+- **Email Integration** — Multi-account IMAP/SMTP email via UI and voice
 - **Telephony** — Voice calls via FreeSWITCH SIP integration
+- **Personal Assistant** — Todos, notes, and reminders managed by voice or UI
 - **Federation** — Connect multiple HeyHank instances across machines
 - **Tailscale Funnel** — Public HTTPS access without port forwarding
 - **PWA** — Installable on mobile and desktop
 
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `heyhank` | Start server in foreground (default) |
+| `heyhank serve` | Start server in foreground (explicit) |
+| `heyhank install` | Register as a background service (launchd/systemd) |
+| `heyhank start` | Start the background service |
+| `heyhank stop` | Stop the background service |
+| `heyhank restart` | Restart the background service |
+| `heyhank uninstall` | Remove the background service |
+| `heyhank status` | Show service status |
+| `heyhank logs` | Tail service log files |
+
+**Options:** `--port <n>` overrides the default port (3456).
+
+## Architecture
+
+```
+Browser (React)
+  <-> ws://localhost:3456/ws/browser/:session
+HeyHank Server (Bun + Hono)
+  <-> ws://localhost:3456/ws/cli/:session
+Claude Code / Codex CLI
+```
+
+The server bridges the CLI's `--sdk-url` WebSocket (NDJSON) to a browser-friendly WebSocket.
+
+## Authentication
+
+The server auto-generates an auth token on first start, stored at `~/.heyhank/auth.json`.
+
+```bash
+# Show the current token
+bun run generate-token
+
+# Force-regenerate a new token
+bun run generate-token --force
+```
+
+Or set via environment variable:
+
+```bash
+HEYHANK_AUTH_TOKEN="my-secret-token" bunx heyhank
+```
+
+## Development
+
+```bash
+bun install
+bun run dev
+```
+
+Checks:
+
+```bash
+bun run typecheck
+bun run test
+```
+
 ## License
 
 MIT

package/bin/cli.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 
 // Package root so the server can find dist/ regardless of CWD
 const __dirname = dirname(fileURLToPath(import.meta.url));
-process.env.__COMPANION_PACKAGE_ROOT = resolve(__dirname, "..");
+process.env.__HEYHANK_PACKAGE_ROOT = resolve(__dirname, "..");
 
 const command = process.argv[2];
 
@@ -25,7 +25,7 @@ Server commands:
   stop        Stop the background service
   restart     Restart the background service
   uninstall   Remove the background service
-  status      Show service status (or use 'companion status' when server is running)
+  status      Show service status (or use 'heyhank status' when server is running)
   logs        Tail service log files
   help        Show this help message
 
@@ -35,7 +35,7 @@ Management commands (requires running server):
   cron        Manage scheduled jobs (list, get, create, update, delete, toggle, run)
   skills      Manage Claude Code skills (list, get, create, update, delete)
   settings    Manage settings (get, set)
-  assistant   Manage the Companion Assistant (status, launch, stop, config)
+  assistant   Manage the HeyHank Assistant (status, launch, stop, config)
 
 Options:
   --port <n>  Override the default port (default: 3456)
@@ -105,13 +105,13 @@ switch (command) {
       const { status } = await import("../server/service.js");
       const result = await status();
       if (!result.installed) {
-        console.log("The Companion is not installed as a service.");
-        console.log("Run: companion install");
+        console.log("HeyHank is not installed as a service.");
+        console.log("Run: heyhank install");
       } else if (result.running) {
-        console.log(`The Companion is running (PID: ${result.pid})`);
+        console.log(`HeyHank is running (PID: ${result.pid})`);
         console.log(`  URL: http://localhost:${result.port}`);
       } else {
-        console.log("The Companion is installed but not running.");
+        console.log("HeyHank is installed but not running.");
         console.log("Check logs at ~/.heyhank/logs/");
       }
     }

package/bin/ctl.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 /**
- * CLI handler module for `companion` management subcommands.
- * Each subcommand maps 1:1 to a Companion REST API endpoint.
+ * CLI handler module for `heyhank` management subcommands.
+ * Each subcommand maps 1:1 to a HeyHank REST API endpoint.
  * All output is JSON to stdout for easy parsing by both humans and AI agents.
  */
 
@@ -13,7 +13,7 @@ function getPort(argv: string[]): number {
     const p = Number(argv[idx + 1]);
     if (!Number.isNaN(p) && p > 0) return p;
   }
-  return Number(process.env.COMPANION_PORT) || DEFAULT_PORT;
+  return Number(process.env.HEYHANK_PORT || process.env.COMPANION_PORT) || DEFAULT_PORT;
 }
 
 function getBase(argv: string[]): string {
@@ -175,7 +175,7 @@ async function handleSessions(base: string, args: string[]): Promise<void> {
     }
     case "get": {
       const id = rest[0];
-      if (!id) err("Usage: companion sessions get <sessionId>");
+      if (!id) err("Usage: heyhank sessions get <sessionId>");
       out(await apiGet(base, `/sessions/${encodeURIComponent(id)}`));
       break;
     }
@@ -195,33 +195,33 @@ async function handleSessions(base: string, args: string[]): Promise<void> {
     }
     case "kill": {
       const id = rest[0];
-      if (!id) err("Usage: companion sessions kill <sessionId>");
+      if (!id) err("Usage: heyhank sessions kill <sessionId>");
       out(await apiPost(base, `/sessions/${encodeURIComponent(id)}/kill`));
       break;
     }
     case "relaunch": {
       const id = rest[0];
-      if (!id) err("Usage: companion sessions relaunch <sessionId>");
+      if (!id) err("Usage: heyhank sessions relaunch <sessionId>");
       out(await apiPost(base, `/sessions/${encodeURIComponent(id)}/relaunch`));
       break;
     }
     case "archive": {
       const id = rest[0];
-      if (!id) err("Usage: companion sessions archive <sessionId>");
+      if (!id) err("Usage: heyhank sessions archive <sessionId>");
       out(await apiPost(base, `/sessions/${encodeURIComponent(id)}/archive`));
       break;
     }
     case "rename": {
       const id = rest[0];
       const name = rest.slice(1).join(" ");
-      if (!id || !name) err("Usage: companion sessions rename <sessionId> <name>");
+      if (!id || !name) err("Usage: heyhank sessions rename <sessionId> <name>");
       out(await apiPatch(base, `/sessions/${encodeURIComponent(id)}/name`, { name }));
       break;
     }
     case "send-message": {
       const id = rest[0];
       const content = rest.slice(1).join(" ");
-      if (!id || !content) err("Usage: companion sessions send-message <sessionId> <message>");
+      if (!id || !content) err("Usage: heyhank sessions send-message <sessionId> <message>");
       out(await apiPost(base, `/sessions/${encodeURIComponent(id)}/message`, { content }));
       break;
     }
@@ -241,20 +241,20 @@ async function handleEnvs(base: string, args: string[]): Promise<void> {
     }
     case "get": {
       const slug = rest[0];
-      if (!slug) err("Usage: companion envs get <slug>");
+      if (!slug) err("Usage: heyhank envs get <slug>");
       out(await apiGet(base, `/envs/${encodeURIComponent(slug)}`));
       break;
     }
     case "create": {
       const flags = parseFlags(rest);
       const vars = parseVars(rest);
-      if (!flags.name) err("Usage: companion envs create --name <name> [--var KEY=VALUE ...]");
+      if (!flags.name) err("Usage: heyhank envs create --name <name> [--var KEY=VALUE ...]");
       out(await apiPost(base, "/envs", { name: flags.name, variables: vars }));
       break;
     }
     case "update": {
       const slug = rest[0];
-      if (!slug) err("Usage: companion envs update <slug> [--name <name>] [--var KEY=VALUE ...]");
+      if (!slug) err("Usage: heyhank envs update <slug> [--name <name>] [--var KEY=VALUE ...]");
       const flagArgs = rest.slice(1);
       const flags = parseFlags(flagArgs);
       const vars = parseVars(flagArgs);
@@ -266,7 +266,7 @@ async function handleEnvs(base: string, args: string[]): Promise<void> {
     }
     case "delete": {
       const slug = rest[0];
-      if (!slug) err("Usage: companion envs delete <slug>");
+      if (!slug) err("Usage: heyhank envs delete <slug>");
       out(await apiDelete(base, `/envs/${encodeURIComponent(slug)}`));
       break;
     }
@@ -286,14 +286,14 @@ async function handleCron(base: string, args: string[]): Promise<void> {
     }
     case "get": {
       const id = rest[0];
-      if (!id) err("Usage: companion cron get <jobId>");
+      if (!id) err("Usage: heyhank cron get <jobId>");
       out(await apiGet(base, `/cron/jobs/${encodeURIComponent(id)}`));
       break;
     }
     case "create": {
       const flags = parseFlags(rest);
       if (!flags.name || !flags.schedule || !flags.prompt)
-        err("Usage: companion cron create --name <name> --schedule <cron|datetime> --prompt <prompt> [--cwd <path>] [--model <model>] [--env <slug>] [--recurring] [--backend <type>] [--permission-mode <mode>]");
+        err("Usage: heyhank cron create --name <name> --schedule <cron|datetime> --prompt <prompt> [--cwd <path>] [--model <model>] [--env <slug>] [--recurring] [--backend <type>] [--permission-mode <mode>]");
       const body: Record<string, unknown> = {
         name: flags.name,
         schedule: flags.schedule,
@@ -312,7 +312,7 @@ async function handleCron(base: string, args: string[]): Promise<void> {
     }
     case "update": {
       const id = rest[0];
-      if (!id) err("Usage: companion cron update <jobId> [--name <n>] [--schedule <s>] [--prompt <p>] ...");
+      if (!id) err("Usage: heyhank cron update <jobId> [--name <n>] [--schedule <s>] [--prompt <p>] ...");
       const flagArgs = rest.slice(1);
       const flags = parseFlags(flagArgs);
       const body: Record<string, unknown> = {};
@@ -330,25 +330,25 @@ async function handleCron(base: string, args: string[]): Promise<void> {
     }
     case "delete": {
       const id = rest[0];
-      if (!id) err("Usage: companion cron delete <jobId>");
+      if (!id) err("Usage: heyhank cron delete <jobId>");
       out(await apiDelete(base, `/cron/jobs/${encodeURIComponent(id)}`));
       break;
     }
     case "toggle": {
       const id = rest[0];
-      if (!id) err("Usage: companion cron toggle <jobId>");
+      if (!id) err("Usage: heyhank cron toggle <jobId>");
       out(await apiPost(base, `/cron/jobs/${encodeURIComponent(id)}/toggle`));
       break;
     }
     case "run": {
       const id = rest[0];
-      if (!id) err("Usage: companion cron run <jobId>");
+      if (!id) err("Usage: heyhank cron run <jobId>");
       out(await apiPost(base, `/cron/jobs/${encodeURIComponent(id)}/run`));
       break;
     }
     case "executions": {
       const id = rest[0];
-      if (!id) err("Usage: companion cron executions <jobId>");
+      if (!id) err("Usage: heyhank cron executions <jobId>");
       out(await apiGet(base, `/cron/jobs/${encodeURIComponent(id)}/executions`));
       break;
     }
@@ -370,7 +370,7 @@ async function handleSettings(base: string, args: string[]): Promise<void> {
       const body: Record<string, unknown> = {};
       if (flags["anthropic-key"]) body.anthropicApiKey = flags["anthropic-key"];
       if (flags["anthropic-model"]) body.anthropicModel = flags["anthropic-model"];
-      if (Object.keys(body).length === 0) err("Usage: companion settings set --anthropic-key <key> or --anthropic-model <model>");
+      if (Object.keys(body).length === 0) err("Usage: heyhank settings set --anthropic-key <key> or --anthropic-model <model>");
       out(await apiPut(base, "/settings", body));
       break;
     }
@@ -425,13 +425,13 @@ async function handleSkills(base: string, args: string[]): Promise<void> {
     }
     case "get": {
       const slug = rest[0];
-      if (!slug) err("Usage: companion skills get <slug>");
+      if (!slug) err("Usage: heyhank skills get <slug>");
       out(await apiGet(base, `/skills/${encodeURIComponent(slug)}`));
       break;
     }
     case "create": {
       const flags = parseFlags(rest);
-      if (!flags.name) err("Usage: companion skills create --name <name> [--description <desc>] [--content <markdown>]");
+      if (!flags.name) err("Usage: heyhank skills create --name <name> [--description <desc>] [--content <markdown>]");
       const body: Record<string, unknown> = { name: flags.name };
       if (flags.description) body.description = flags.description;
       if (flags.content) body.content = flags.content;
@@ -440,15 +440,15 @@ async function handleSkills(base: string, args: string[]): Promise<void> {
     }
     case "update": {
       const slug = rest[0];
-      if (!slug) err("Usage: companion skills update <slug> --content <markdown>");
+      if (!slug) err("Usage: heyhank skills update <slug> --content <markdown>");
       const flags = parseFlags(rest.slice(1));
-      if (!flags.content) err("Usage: companion skills update <slug> --content <full SKILL.md content>");
+      if (!flags.content) err("Usage: heyhank skills update <slug> --content <full SKILL.md content>");
       out(await apiPut(base, `/skills/${encodeURIComponent(slug)}`, { content: flags.content }));
       break;
     }
     case "delete": {
       const slug = rest[0];
-      if (!slug) err("Usage: companion skills delete <slug>");
+      if (!slug) err("Usage: heyhank skills delete <slug>");
       out(await apiDelete(base, `/skills/${encodeURIComponent(slug)}`));
       break;
     }
@@ -463,18 +463,18 @@ function printCtlUsage(): void {
   console.log(`
 Management commands:
 
-  companion status                        Overall Companion status
-  companion sessions <subcommand>         Manage sessions
-  companion envs <subcommand>             Manage environment profiles
-  companion cron <subcommand>             Manage scheduled jobs
-  companion skills <subcommand>           Manage Claude Code skills
-  companion settings <subcommand>         Manage settings
-  companion assistant <subcommand>        Manage the Companion Assistant
+  heyhank status                        Overall HeyHank status
+  heyhank sessions <subcommand>         Manage sessions
+  heyhank envs <subcommand>             Manage environment profiles
+  heyhank cron <subcommand>             Manage scheduled jobs
+  heyhank skills <subcommand>           Manage Claude Code skills
+  heyhank settings <subcommand>         Manage settings
+  heyhank assistant <subcommand>        Manage the HeyHank Assistant
 
 Global options:
-  --port <n>    Override the Companion API port (default: 3456, or COMPANION_PORT env)
+  --port <n>    Override the HeyHank API port (default: 3456, or HEYHANK_PORT env)
 
-Run 'companion <command>' without subcommand for available subcommands.
+Run 'heyhank <command>' without subcommand for available subcommands.
 `);
 }
 
@@ -488,27 +488,27 @@ export async function handleCtlCommand(command: string, rawArgv: string[]): Prom
         await handleStatus(base);
         break;
       case "sessions":
-        if (argv.length === 0) err("Usage: companion sessions <list|get|create|kill|relaunch|archive|rename|send-message>");
+        if (argv.length === 0) err("Usage: heyhank sessions <list|get|create|kill|relaunch|archive|rename|send-message>");
         await handleSessions(base, argv);
         break;
       case "envs":
-        if (argv.length === 0) err("Usage: companion envs <list|get|create|update|delete>");
+        if (argv.length === 0) err("Usage: heyhank envs <list|get|create|update|delete>");
         await handleEnvs(base, argv);
         break;
       case "cron":
-        if (argv.length === 0) err("Usage: companion cron <list|get|create|update|delete|toggle|run|executions>");
+        if (argv.length === 0) err("Usage: heyhank cron <list|get|create|update|delete|toggle|run|executions>");
         await handleCron(base, argv);
         break;
       case "settings":
-        if (argv.length === 0) err("Usage: companion settings <get|set>");
+        if (argv.length === 0) err("Usage: heyhank settings <get|set>");
         await handleSettings(base, argv);
         break;
       case "skills":
-        if (argv.length === 0) err("Usage: companion skills <list|get|create|update|delete>");
+        if (argv.length === 0) err("Usage: heyhank skills <list|get|create|update|delete>");
         await handleSkills(base, argv);
         break;
       case "assistant":
-        if (argv.length === 0) err("Usage: companion assistant <status|launch|stop|config>");
+        if (argv.length === 0) err("Usage: heyhank assistant <status|launch|stop|config>");
         await handleAssistant(base, argv);
         break;
       case "ctl-help":
@@ -521,7 +521,7 @@ export async function handleCtlCommand(command: string, rawArgv: string[]): Prom
     const message = e instanceof Error ? e.message : String(e);
     // Check if it's a connection error
     if (message.includes("ECONNREFUSED") || message.includes("fetch failed")) {
-      err(`Cannot connect to The Companion at ${base}. Is the server running?`);
+      err(`Cannot connect to HeyHank at ${base}. Is the server running?`);
     }
     err(message);
   }