@calvin.magezi/agent-hq 0.5.0 → 0.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +66 -45
  2. package/bin/hq +97 -43
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -2,76 +2,97 @@
2
2
 
3
3
  > Local-first AI agent hub — Claude, Gemini & Discord, all from one command.
4
4
 
5
- ## Install
5
+ ## Quick Install
6
6
 
7
- ### via bunx / npx (zero-install)
8
7
  ```bash
9
- bunx agent-hq
10
- # or
11
- npx agent-hq
8
+ # Zero-install (auto-clones repo, installs Bun if needed)
9
+ npx @calvin.magezi/agent-hq
10
+
11
+ # Or with Bun (faster):
12
+ bunx @calvin.magezi/agent-hq
12
13
  ```
13
14
 
14
- ### via Homebrew
15
+ This will:
16
+ 1. Install Bun if not present
17
+ 2. Clone the agent-hq repo to `~/agent-hq`
18
+ 3. Run `hq init` to set up everything
19
+
20
+ ## From Source
21
+
15
22
  ```bash
16
- brew tap calvinmagezi/agent-hq
17
- brew install hq
23
+ git clone https://github.com/CalvinMagezi/agent-hq.git
24
+ cd agent-hq
25
+ bun install
26
+ bun scripts/hq.ts init
18
27
  ```
19
28
 
20
- ### Manual (inside the repo)
29
+ ## First-Time Setup
30
+
31
+ After installation, run the guided walkthrough:
32
+
21
33
  ```bash
22
- hq install-cli # symlinks scripts/hq.ts → ~/.local/bin/hq
34
+ hq quickstart
23
35
  ```
24
36
 
25
- ## First-time setup
37
+ Or set up step by step:
26
38
 
27
39
  ```bash
28
- # Interactive (asks questions)
29
- hq init
40
+ hq init # Full setup (vault, tools, services)
41
+ hq env # Configure API keys interactively
42
+ hq doctor # Verify everything works
43
+ ```
30
44
 
31
- # Unattended — safe for agent/CI execution
32
- hq init --non-interactive
45
+ ### API Keys
33
46
 
34
- # Custom vault location
35
- hq init --vault /path/to/my/vault --non-interactive
36
- ```
47
+ You need at least one of these to use AI chat:
48
+
49
+ | Key | Where to get it | Required? |
50
+ |-----|-----------------|-----------|
51
+ | `OPENROUTER_API_KEY` | [openrouter.ai/keys](https://openrouter.ai/keys) | Yes (or Gemini) |
52
+ | `GEMINI_API_KEY` | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | Optional |
53
+ | `DISCORD_BOT_TOKEN` | [discord.com/developers](https://discord.com/developers/applications) | Optional |
54
+
55
+ Run `hq env` to set these interactively.
37
56
 
38
- ## Commands
57
+ ## Essential Commands
39
58
 
40
59
  | Command | Description |
41
60
  |---------|-------------|
42
- | `hq` | Start interactive chat |
43
- | `hq init` | Full first-time setup |
44
- | `hq setup` | Scaffold vault only |
45
- | `hq status` | Service status |
46
- | `hq start [agent\|relay\|all]` | Start services |
47
- | `hq stop [agent\|relay\|all]` | Stop services |
48
- | `hq restart` | Restart everything |
49
- | `hq daemon start\|stop\|logs` | Background daemon |
50
- | `hq logs [target] [N]` | View logs |
51
- | `hq follow` | Live-tail logs |
61
+ | `hq` | Start chatting (default) |
62
+ | `hq quickstart` | Guided first-run walkthrough |
63
+ | `hq doctor` | Diagnose common issues |
64
+ | `hq env` | Set up API keys |
65
+ | `hq status` | Check what's running |
66
+ | `hq start all` | Start all services |
67
+ | `hq stop all` | Stop all services |
68
+ | `hq pwa` | Open the web dashboard |
69
+ | `hq vault open` | Open vault in Obsidian |
52
70
  | `hq health` | Full health check |
53
- | `hq ps` | All managed processes |
54
- | `hq install` | Install launchd daemons |
55
- | `hq coo status` | COO orchestrator status |
71
+ | `hq logs [target]` | View logs |
72
+ | `hq help` | Essential commands |
73
+ | `hq help --all` | All commands |
74
+ | `hq help --agent` | Quick reference for AI agents |
56
75
 
57
- ## Agent-installable
76
+ ## For AI Agents
58
77
 
59
- This CLI is designed to be fully installable by an AI agent:
78
+ The CLI is fully automatable:
60
79
 
61
80
  ```bash
62
- # Prerequisites: bun, git
63
- bunx agent-hq init --non-interactive \
64
- --vault ~/.agent-hq-vault
81
+ OPENROUTER_API_KEY=sk-or-... \
82
+ npx @calvin.magezi/agent-hq init --non-interactive
65
83
  ```
66
84
 
67
- The init command will:
68
- 1. Check prerequisites (bun, git)
69
- 2. Install dependencies
70
- 3. Scaffold the vault
71
- 4. Create `.env.local` templates
72
- 5. Install macOS launchd daemons
73
- 6. Add `hq` to your PATH
85
+ Run `hq help --agent` for the recommended command sequence.
86
+
87
+ ## What's Included
88
+
89
+ - **Vault**: An Obsidian-compatible folder of markdown files — your AI's knowledge base
90
+ - **HQ Agent**: Background worker that processes AI jobs
91
+ - **Discord Relay**: Multi-bot system for chatting via Discord
92
+ - **Web Dashboard**: PWA on localhost:4747 for monitoring
93
+ - **Terminal Chat**: `hq` starts an interactive REPL
94
+ - **Daemon**: Background workflows (memory consolidation, web digests, etc.)
74
95
 
75
96
  ## License
76
97
 
77
- MIT © Calvin Magezi
98
+ MIT
package/bin/hq CHANGED
@@ -1,26 +1,68 @@
1
- #!/usr/bin/env bun
1
+ #!/usr/bin/env node
2
2
  /**
3
3
  * agent-hq entry point
4
4
  *
5
- * When installed via `bunx agent-hq` or `npx agent-hq`:
6
- * - If run from inside the monorepo, delegates to scripts/hq.ts
7
- * - Otherwise, bootstraps the installation with `hq init`
5
+ * When installed via `npx @calvin.magezi/agent-hq` or `bunx @calvin.magezi/agent-hq`:
6
+ * - If run from inside the monorepo, delegates to scripts/hq.ts via Bun
7
+ * - Otherwise, bootstraps the installation (clone + hq init)
8
8
  *
9
- * Install globally: bunx agent-hq install-cli
10
- * Homebrew: brew install calvinmagezi/agent-hq/hq
9
+ * Works with Node.js (no Bun required) — auto-installs Bun if missing.
11
10
  */
12
11
 
13
- import * as fs from "fs";
14
- import * as path from "path";
15
- import { spawnSync } from "child_process";
12
+ const fs = require("fs");
13
+ const path = require("path");
14
+ const { spawnSync, execSync } = require("child_process");
16
15
 
17
- // ── Locate the monorepo root ──────────────────────────────────────────────────
16
+ // ── Helpers ─────────────────────────────────────────────────────────────────
18
17
 
19
- function findRepoRoot(start: string): string | null {
18
+ function hasBun() {
19
+ try {
20
+ const r = spawnSync("bun", ["--version"], { stdio: "pipe" });
21
+ return r.status === 0;
22
+ } catch { return false; }
23
+ }
24
+
25
+ function installBun() {
26
+ console.log("\n Bun is required but not installed. Installing Bun...\n");
27
+ const platform = process.platform;
28
+
29
+ if (platform === "win32") {
30
+ console.log(" Run this in PowerShell:");
31
+ console.log(" irm bun.sh/install.ps1 | iex\n");
32
+ console.log(" Then re-run: npx @calvin.magezi/agent-hq");
33
+ process.exit(1);
34
+ }
35
+
36
+ // macOS / Linux
37
+ const result = spawnSync("bash", ["-c", "curl -fsSL https://bun.sh/install | bash"], {
38
+ stdio: "inherit",
39
+ });
40
+
41
+ if (result.status !== 0) {
42
+ console.error("\n Bun installation failed. Install manually: https://bun.sh\n");
43
+ process.exit(1);
44
+ }
45
+
46
+ // Source the new PATH (Bun installs to ~/.bun/bin)
47
+ const bunBin = path.join(process.env.HOME || "~", ".bun", "bin");
48
+ process.env.PATH = bunBin + ":" + process.env.PATH;
49
+
50
+ if (!hasBun()) {
51
+ console.log("\n Bun installed but not found on PATH.");
52
+ console.log(" Restart your terminal, then re-run: npx @calvin.magezi/agent-hq\n");
53
+ process.exit(1);
54
+ }
55
+
56
+ console.log("\n Bun installed successfully.\n");
57
+ }
58
+
59
+ // ── Locate the monorepo root ────────────────────────────────────────────────
60
+
61
+ function findRepoRoot(start) {
20
62
  let dir = start;
21
63
  for (let i = 0; i < 8; i++) {
22
64
  const pkg = path.join(dir, "package.json");
23
- const apps = path.join(dir, "apps/agent");
65
+ const apps = path.join(dir, "apps", "agent");
24
66
  if (fs.existsSync(pkg) && fs.existsSync(apps)) return dir;
25
67
  const parent = path.dirname(dir);
26
68
  if (parent === dir) return null;
@@ -29,66 +71,78 @@ function findRepoRoot(start: string): string | null {
29
71
  return null;
30
72
  }
31
73
 
32
- // When installed via npm/bun globally, this file lives at:
33
- // node_modules/.bin/hq → node_modules/agent-hq/bin/hq.ts
34
- // So walk up from __dirname to find the repo, or fall back to CWD.
35
- const repoFromPackage = findRepoRoot(path.resolve(import.meta.dir, "../../.."));
74
+ const repoFromPackage = findRepoRoot(path.resolve(__dirname, "..", "..", ".."));
36
75
  const repoFromCwd = findRepoRoot(process.cwd());
37
- const REPO_ROOT = repoFromPackage ?? repoFromCwd;
76
+ const REPO_ROOT = repoFromPackage || repoFromCwd;
38
77
 
39
- // ── Delegate or bootstrap ─────────────────────────────────────────────────────
78
+ // ── Delegate or bootstrap ───────────────────────────────────────────────────
40
79
 
41
80
  if (REPO_ROOT) {
42
- // We're inside (or near) the monorepo — exec the full CLI
43
- const fullCli = path.join(REPO_ROOT, "scripts/hq.ts");
81
+ // Inside (or near) the monorepo — ensure Bun, then delegate to full CLI
82
+ if (!hasBun()) installBun();
83
+
84
+ const fullCli = path.join(REPO_ROOT, "scripts", "hq.ts");
44
85
  if (fs.existsSync(fullCli)) {
45
- const result = spawnSync(process.execPath, [fullCli, ...process.argv.slice(2)], {
86
+ const result = spawnSync("bun", [fullCli, ...process.argv.slice(2)], {
46
87
  stdio: "inherit",
47
88
  env: process.env,
48
89
  });
49
- process.exit(result.status ?? 0);
90
+ process.exit(result.status || 0);
50
91
  }
51
92
  }
52
93
 
53
- // ── Not in repo — run init to bootstrap ──────────────────────────────────────
94
+ // ── Not in repo — run init to bootstrap ─────────────────────────────────────
54
95
 
55
96
  console.log(`
56
- ┌─────────────────────────────────────────────────────┐
57
- │ agent-hq — first run │
58
- │ │
59
- │ No agent-hq repository found near this location. │
60
- │ Let's set everything up. │
61
- └─────────────────────────────────────────────────────┘
97
+ +-------------------------------------------------+
98
+ | agent-hq -- first run |
99
+ | |
100
+ | No agent-hq repository found. |
101
+ | Let's set everything up. |
102
+ +-------------------------------------------------+
62
103
  `);
63
104
 
105
+ // Ensure Bun is available before cloning
106
+ if (!hasBun()) installBun();
107
+
64
108
  const isNonInteractive =
65
109
  process.argv.includes("--non-interactive") ||
66
110
  process.argv.includes("-y") ||
67
111
  !process.stdout.isTTY;
68
112
 
69
113
  const installDir = path.join(
70
- process.env.AGENT_HQ_DIR ?? (process.env.HOME ?? "~"),
114
+ process.env.AGENT_HQ_DIR || process.env.HOME || "~",
71
115
  "agent-hq"
72
116
  );
73
117
 
74
- console.log(`Cloning agent-hq to: ${installDir}`);
75
- const clone = spawnSync("git", [
76
- "clone", "https://github.com/CalvinMagezi/agent-hq.git", installDir
77
- ], { stdio: "inherit" });
118
+ if (fs.existsSync(path.join(installDir, "package.json"))) {
119
+ console.log(` Found existing repo at: ${installDir}`);
120
+ console.log(` Running: cd ${installDir} && bun scripts/hq.ts init\n`);
121
+ } else {
122
+ console.log(` Cloning agent-hq to: ${installDir}\n`);
123
+ const clone = spawnSync("git", [
124
+ "clone", "https://github.com/CalvinMagezi/agent-hq.git", installDir
125
+ ], { stdio: "inherit" });
78
126
 
79
- if (clone.status !== 0) {
80
- console.error("\nClone failed. Check your internet connection.");
81
- process.exit(1);
127
+ if (clone.status !== 0) {
128
+ console.error("\n Clone failed. Check your internet connection and that git is installed.");
129
+ process.exit(1);
130
+ }
82
131
  }
83
132
 
84
- const installArgs = [
85
- path.join(installDir, "scripts/hq.ts"),
133
+ const initArgs = isNonInteractive ? ["--non-interactive"] : [];
134
+ const passedArgs = process.argv.slice(2).filter(a =>
135
+ a.startsWith("--vault") || a.startsWith("--repo-url") ||
136
+ a === "--non-interactive" || a === "-y" || a === "--reset"
137
+ );
138
+
139
+ const init = spawnSync("bun", [
140
+ path.join(installDir, "scripts", "hq.ts"),
86
141
  "init",
87
- ...(isNonInteractive ? ["--non-interactive"] : []),
88
- ];
89
- const init = spawnSync(process.execPath, installArgs, {
142
+ ...new Set([...initArgs, ...passedArgs]),
143
+ ], {
90
144
  cwd: installDir,
91
145
  stdio: "inherit",
92
146
  env: process.env,
93
147
  });
94
- process.exit(init.status ?? 0);
148
+ process.exit(init.status || 0);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@calvin.magezi/agent-hq",
3
- "version": "0.5.0",
3
+ "version": "0.6.4",
4
4
  "description": "HQ CLI — local-first AI agent hub for Claude, Gemini & Discord",
5
5
  "homepage": "https://github.com/CalvinMagezi/agent-hq",
6
6
  "repository": {
@@ -27,7 +27,7 @@
27
27
  "README.md"
28
28
  ],
29
29
  "engines": {
30
- "bun": ">=1.1.0"
30
+ "node": ">=18.0.0"
31
31
  },
32
32
  "scripts": {
33
33
  "prepublishOnly": "echo 'Publishing hq CLI...'"