grok-telegram-bot 2.0.0

package/docs/INSTALL.md

@@ -0,0 +1,153 @@
+# 📦 Install guide
+
+Get the Grok Telegram Bot running in a few minutes. Pick one of three ways:
+
+- **[Option A — npm (recommended)](#option-a--npm-recommended)** — one command,
+  global `grok-tg` CLI, easiest to update.
+- **[Option B — 1-click installer](#option-b--1-click-installer)** — download a
+  release zip and double-click the installer.
+- **[Option C — manual / from source](#option-c--manual--from-source)** — clone
+  the repo (best for contributors).
+
+## Prerequisites
+
+- **Grok CLI** installed and authenticated — run `grok chat` once to confirm.
+- **Node.js 20+**.
+- A **bot token** from [@BotFather](https://t.me/BotFather).
+- Your **Telegram user ID** from [@userinfobot](https://t.me/userinfobot).
+
+---
+
+## Option A — npm (recommended)
+
+Install the CLI once, globally. It ships with the `tsx` runtime, so there's no
+build step.
+
+```bash
+npm install -g grok-telegram-bot
+```
+
+This gives you the **`grok-tg`** command (alias: `grok-telegram-bot`). Everything
+operates on the **current folder** — your `.env`, `logs/` and `data/` live there,
+so keep one folder per bot instance:
+
+```bash
+mkdir my-bot && cd my-bot       # a home for this bot's config + logs + data
+grok-tg setup                   # auto-detects grok, writes ./.env
+#   (or pass values directly:  grok-tg setup <BOT_TOKEN> <YOUR_USER_ID>)
+# edit .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS
+grok-tg run                     # run in the foreground (Ctrl-C to stop)
+```
+
+> ⚠️ **Set `ALLOWED_USERS`** in `.env` to your Telegram user ID(s). Empty means
+> *anyone* who finds the bot can run commands on your machine.
+
+### Startup options (`grok-tg <command>`)
+
+| Command | What it does |
+|---|---|
+| `grok-tg setup [token] [userId]` | Create/update `.env` in this folder (auto-detects `grok` + project roots). |
+| `grok-tg run` | Run the bot in the foreground. |
+| `grok-tg install` | Install + start a **24/7 background service** that autostarts on boot/login. |
+| `grok-tg status` | Show install + running state of the service. |
+| `grok-tg logs [n]` | Tail the last `n` log lines (default 100). |
+| `grok-tg stop` / `restart` / `start` | Control the running service. |
+| `grok-tg uninstall` | Stop + remove the background service. |
+| `grok-tg help` | Show all commands. |
+
+The background service is **user-level** and auto-detected per platform — a
+hidden Scheduled Task on Windows, a `systemd` **user** service on Linux (with
+linger for boot-without-login), and a launchd **LaunchAgent** on macOS. It runs
+the bot bound to the folder you installed it from, so its `.env`/`logs`/`data`
+stay in that folder.
+
+Update later with `npm install -g grok-telegram-bot@latest` (global npm installs
+also auto-update when idle). Full upgrade steps for every install type are in
+**[UPGRADE.md](./UPGRADE.md)**.
+
+> **Try without installing:** `npx grok-telegram-bot setup` then
+> `npx grok-telegram-bot run` works too (slower first run).
+
+---
+
+## Option B — 1-click installer
+
+Every [release](https://github.com/artickc/grok-telegram-bot/releases) ships a
+clean `grok-telegram-bot-<version>.zip` (no `node_modules`, `.env`, logs or data)
+that contains the 1-click installers.
+
+1. **Download** the latest `grok-telegram-bot-<version>.zip` and unzip it (or
+   `git clone` the repo).
+2. **Run the installer for your OS** from the unzipped folder. It installs
+   dependencies, auto-detects `grok`, writes `.env`, asks for your bot
+   token, and optionally sets up the 24/7 background service.
+
+   **Windows** — double-click `install.cmd`, or in a terminal:
+
+   ```powershell
+   .\install.cmd
+   ```
+
+   **Linux / macOS**:
+
+   ```bash
+   chmod +x install.sh && ./install.sh
+   ```
+
+3. **Set access control.** Open `.env` and set `ALLOWED_USERS` to your Telegram
+   user ID(s).
+
+---
+
+## Option C — manual / from source
+
+Best for contributors (run with auto-reload, no build step).
+
+```bash
+git clone https://github.com/artickc/grok-telegram-bot.git
+cd grok-telegram-bot
+npm install
+npm run setup            # auto-detects grok + project roots, writes .env
+# edit .env: set TELEGRAM_BOT_TOKEN and ALLOWED_USERS
+npm start                # or: npm run dev  (auto-reload)
+```
+
+Run it 24/7 as a background service:
+
+```bash
+npm run install:service     # install + start, enable autostart on boot/login
+npm run service -- status   # show install + running state
+npm run service -- logs 200 # tail the log file
+npm run uninstall:service   # stop + remove
+```
+
+No build step — TypeScript runs directly via `tsx`.
+
+---
+
+## Updating
+
+Already installed and want the newest version? See **[UPGRADE.md](./UPGRADE.md)**
+— it covers upgrading npm installs (automatic or `npm install -g
+grok-telegram-bot@latest`), 1-click/zip installs (replace files, keep your
+`.env`/`data/`), and git/source checkouts (`git pull && npm install`), plus how
+to restart after upgrading.
+
+## Configuration
+
+All options live in `.env`. See the **Configuration** table in the
+[README](../README.md) for every variable and its default. By default the bot
+keeps `.env`, `logs/` and `data/` in the folder you run it from (override log
+location with `LOG_DIR` / `LOG_FILE` and data with `DATA_DIR`).
+
+## Troubleshooting
+
+- **Bot doesn't respond** — confirm your ID is in `ALLOWED_USERS` and the token
+  is correct; check `logs/grok-telegram-bot.log` (run `grok-tg logs`).
+- **`grok` not found** — set `GROK_CLI_PATH` in `.env` to the binary's full
+  path.
+- **`grok-tg: command not found`** — ensure your global npm bin dir is on `PATH`
+  (`npm bin -g`), or use `npx grok-telegram-bot <command>`.
+- **"high volume of traffic" / transient errors** — the bot auto-retries with
+  backoff (6s → 60s) and shows the real error; switch model with the 🧩 menu or
+  `/model <id>` if a model stays busy.

package/docs/UPGRADE.md

@@ -0,0 +1,253 @@
+# ⬆️ Upgrade guide
+
+How to update Grok Telegram Bot to the newest version — for bots installed **via
+npm** and for bots installed **without npm** (1-click zip installer or a
+git/source checkout).
+
+> **Your config is safe.** Upgrading only replaces the bot's *code*. Your
+> settings, credentials and history — `.env`, `data/` (accounts, tasks, ephemeral
+> state) and `logs/` — live **outside** the code and are never overwritten by an
+> upgrade. Global npm installs keep them in `~/.grok/tg/`; zip/source installs
+> keep them in the bot's folder.
+
+Jump to your install type:
+
+- **[Which install do I have?](#which-install-do-i-have)**
+- **[A — Upgrade an npm install](#a--upgrade-an-npm-install)** (auto or manual)
+- **[B — Upgrade a 1-click / zip install (no npm)](#b--upgrade-a-1-click--zip-install-no-npm)**
+- **[C — Upgrade a git / source install](#c--upgrade-a-git--source-install)**
+- **[Restart after upgrading](#restart-after-upgrading)**
+- **[Switch a non-npm install over to npm](#switch-a-non-npm-install-over-to-npm)**
+- **[Pin a version / roll back](#pin-a-version--roll-back)**
+- **[Troubleshooting](#troubleshooting)**
+
+---
+
+## Which install do I have?
+
+Check the current version and where the bot is running from:
+
+```bash
+grok-tg --version 2>/dev/null || npm ls -g grok-telegram-bot
+npm root -g          # global npm modules dir — npm installs live under here
+```
+
+- If `grok-telegram-bot` shows up under `npm root -g`, you have an **npm install** → **[Option A](#a--upgrade-an-npm-install)**.
+- If you ran `install.cmd` / `install.sh` from an unzipped release folder, you have a **zip install** → **[Option B](#b--upgrade-a-1-click--zip-install-no-npm)**.
+- If you `git clone`d the repo, you have a **source install** → **[Option C](#c--upgrade-a-git--source-install)**.
+
+The latest published version is always on the
+[**Releases**](https://github.com/artickc/grok-telegram-bot/releases) page and in
+[CHANGELOG.md](../CHANGELOG.md).
+
+---
+
+## A — Upgrade an npm install
+
+### Automatic (default)
+
+Global npm installs **update themselves**. With `AUTO_UPDATE=true` (the default),
+the bot checks npm hourly and, **when it's fully idle** (no turn or task running,
+no other active Grok session), it runs `npm install -g grok-telegram-bot@latest`,
+restarts, and posts the new version's changelog in your chat (tagged `#update`).
+
+You don't have to do anything. To control it, set in your `.env`:
+
+```ini
+AUTO_UPDATE=true        # set false to disable self-updates
+UPDATE_CHECK_MS=3600000 # how often to check npm (ms)
+```
+
+> Auto-update only applies to **global npm** installs. Zip/source checkouts are
+> left untouched (see B and C).
+
+### Manual
+
+To upgrade right now (or if you disabled auto-update):
+
+```bash
+npm install -g grok-telegram-bot@latest
+```
+
+Then restart the running bot so it loads the new code — see
+**[Restart after upgrading](#restart-after-upgrading)**.
+
+Your `.env`, `data/` and `logs/` in `~/.grok/tg/` (or your `GROK_TG_DIR`) are
+untouched.
+
+---
+
+## B — Upgrade a 1-click / zip install (no npm)
+
+Zip installs **do not auto-update** — you replace the files yourself. The steps
+are the same ones you used to install, plus keeping your config. Your `.env`,
+`data/` and `logs/` live **inside the bot's folder**, so the goal is to swap the
+code while preserving those.
+
+1. **Stop the service** (from your current bot folder):
+
+   ```bash
+   npm run service -- stop        # or: grok-tg stop
+   ```
+
+2. **Download** the latest `grok-telegram-bot-<version>.zip` from the
+   [Releases](https://github.com/artickc/grok-telegram-bot/releases) page and
+   **unzip it into a fresh folder**.
+
+3. **Carry your config across** — copy these from the OLD folder into the NEW one:
+
+   - `.env` (your token, allowed users, settings) — **required**
+   - `data/` (saved accounts, scheduled tasks) — recommended
+   - `logs/` — optional
+
+   **Windows (PowerShell)**
+
+   ```powershell
+   Copy-Item ..\old-bot\.env  .\ -Force
+   Copy-Item ..\old-bot\data  .\ -Recurse -Force
+   ```
+
+   **Linux / macOS**
+
+   ```bash
+   cp ../old-bot/.env ./ && cp -r ../old-bot/data ./
+   ```
+
+4. **Install deps + service** from the new folder:
+
+   ```bash
+   # Windows: .\install.cmd     Linux/macOS: ./install.sh
+   # or manually:
+   npm install
+   npm run install:service      # re-registers the service to the new folder
+   ```
+
+   `install.cmd` / `install.sh` detect the copied `.env` and skip re-asking for
+   your token.
+
+> **Tip:** upgrading zip installs by hand every release is tedious. Consider
+> **[switching to npm](#switch-a-non-npm-install-over-to-npm)** for one-command
+> (and automatic) updates.
+
+---
+
+## C — Upgrade a git / source install
+
+A source checkout upgrades with `git`. Your `.env`, `data/` and `logs/` are
+git-ignored, so they survive a pull untouched.
+
+```bash
+cd grok-telegram-bot
+git pull                 # fetch the latest code
+npm install              # pick up any new/updated dependencies
+```
+
+Then restart the bot — see **[Restart after upgrading](#restart-after-upgrading)**.
+
+If you're on a fork or have local changes, stash them first (`git stash`), pull,
+`npm install`, then `git stash pop`.
+
+---
+
+## Restart after upgrading
+
+New code only takes effect once the running process restarts. Pick what matches
+how you run the bot:
+
+| How you run it | Restart command |
+|---|---|
+| Background service (npm) | `grok-tg restart` |
+| Background service (zip/source) | `npm run service -- restart` |
+| Foreground (`grok-tg run` / `npm start`) | stop with Ctrl-C, start again |
+
+Confirm it's healthy afterwards:
+
+```bash
+grok-tg status         # or: npm run service -- status
+grok-tg logs 100       # or: npm run service -- logs 100
+```
+
+> Auto-update (Option A) restarts for you, so a manual restart is only needed
+> after a **manual** upgrade.
+
+---
+
+## Switch a non-npm install over to npm
+
+Recommended if you're tired of manual zip upgrades — npm gives you one-command
+and automatic updates.
+
+1. **Install the CLI globally:**
+
+   ```bash
+   npm install -g grok-telegram-bot
+   ```
+
+2. **Move your config to the canonical home** `~/.grok/tg/` (run `grok-tg setup
+   --path` to print the exact location), so npm runs find the same settings:
+
+   **Windows (PowerShell)**
+
+   ```powershell
+   $dst = "$env:USERPROFILE\.grok\tg"; New-Item -ItemType Directory -Force $dst | Out-Null
+   Copy-Item .\.env "$dst\" -Force
+   Copy-Item .\data "$dst\" -Recurse -Force
+   ```
+
+   **Linux / macOS**
+
+   ```bash
+   mkdir -p ~/.grok/tg && cp .env ~/.grok/tg/ && cp -r data ~/.grok/tg/
+   ```
+
+   (Alternatively keep your folder and point at it with `GROK_TG_DIR`.)
+
+3. **Remove the old service and install the npm one:**
+
+   ```bash
+   # in the OLD folder:
+   npm run uninstall:service
+   # then, from anywhere:
+   grok-tg install
+   ```
+
+From now on, upgrade with `npm install -g grok-telegram-bot@latest` (or let
+auto-update handle it).
+
+---
+
+## Pin a version / roll back
+
+Install any specific version (e.g. to roll back a bad upgrade):
+
+```bash
+npm install -g grok-telegram-bot@1.7.2
+```
+
+To stop the bot from moving off a pinned version, set `AUTO_UPDATE=false` in
+`.env` and restart. For zip/source installs, download the matching release zip or
+`git checkout v1.7.2`.
+
+---
+
+## Troubleshooting
+
+- **Still on the old version after upgrading** — you didn't restart. Run
+  `grok-tg restart` (npm) or `npm run service -- restart` (zip/source), then
+  check `grok-tg status`.
+- **`grok-tg: command not found`** — ensure your global npm bin dir is on `PATH`
+  (`npm bin -g`), or use `npx grok-telegram-bot <command>`.
+- **Auto-update never fires** — it only runs for **global npm** installs, and
+  only while the bot is **idle**; check `AUTO_UPDATE` is `true` and see the log
+  (`grok-tg logs 200`) for a `waiting for idle` line.
+- **Lost settings after a zip upgrade** — you upgraded into a new folder without
+  copying `.env`/`data/`. Copy them from the old folder (Option B, step 3) and
+  restart.
+- **Two bots replying / "⛔ Not authorized"** — an old process is still polling.
+  The bot is single-instance per token, so just start the new one
+  (`grok-tg restart`) and it terminates the ghost.
+
+---
+
+See also: **[docs/INSTALL.md](./INSTALL.md)** for first-time setup and
+[CHANGELOG.md](../CHANGELOG.md) for what changed in each version.

package/docs/ops/RELEASE_CHECKLIST.md

@@ -0,0 +1,39 @@
+# Release checklist
+
+A release ships a **batch of merged pull requests** as one versioned tag. The
+heavy lifting (zip + notes + publish) is automated by
+`.github/workflows/release.yml`; this checklist covers the manual steps.
+
+## 1. Pre-flight (on `main`)
+
+- [ ] All intended PRs for this batch are **merged into `main`**.
+- [ ] `git checkout main && git pull` — local `main` matches origin.
+- [ ] `npm ci && npm run typecheck` passes with no errors.
+- [ ] Manual smoke test where relevant (`npm start`, basic Telegram round-trip).
+
+## 2. Changelog & version
+
+- [ ] Add a new `## [X.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md` with the
+      user-facing features/fixes (this becomes the GitHub Release notes).
+- [ ] Add the matching link reference at the bottom of `CHANGELOG.md`.
+- [ ] Choose the bump per SemVer: `patch` (fixes), `minor` (features),
+      `major` (breaking).
+
+## 3. Tag & publish
+
+```bash
+npm version minor          # bumps package.json, commits, creates the v* tag
+git push --follow-tags     # pushing the tag triggers the Release workflow
+```
+
+- [ ] Watch the **Release** workflow in the Actions tab finish green.
+- [ ] Confirm the GitHub Release exists with:
+  - [ ] the correct title (`vX.Y.Z`),
+  - [ ] notes matching the CHANGELOG section,
+  - [ ] the attached `grok-telegram-bot-X.Y.Z.zip`,
+  - [ ] GitHub's auto-generated Source code archives.
+
+## 4. Post-release
+
+- [ ] Announce / update any docs that reference the version.
+- [ ] Open the next batch of feature branches off the new `main`.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "grok-telegram-bot",
+  "version": "2.0.0",
+  "description": "Control the official Grok Build CLI from Telegram over the Agent Client Protocol (ACP). Sign in with your xAI account, switch projects, resume sessions, stream responses with diffs, queue follow-ups, manage multiple sign-ins, and run 24/7 as a cross-platform background service.",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "grok-tg": "bin/grok-tg.mjs",
+    "grok-telegram-bot": "bin/grok-tg.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "scripts",
+    "tsconfig.json",
+    ".env.example",
+    "CHANGELOG.md",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "prepublishOnly": "npm run typecheck",
+    "setup": "node scripts/setup.mjs",
+    "service": "tsx src/cli.ts",
+    "install:service": "tsx src/cli.ts install",
+    "uninstall:service": "tsx src/cli.ts uninstall",
+    "service:status": "tsx src/cli.ts status",
+    "service:logs": "tsx src/cli.ts logs"
+  },
+  "keywords": [
+    "grok",
+    "grok-cli",
+    "xai",
+    "telegram",
+    "telegram-bot",
+    "ai-agent",
+    "ai-coding-assistant",
+    "mobile-coding",
+    "chatops",
+    "devtools",
+    "daemon",
+    "cross-platform",
+    "grammy"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/artickc/grok-telegram-bot.git"
+  },
+  "homepage": "https://github.com/artickc/grok-telegram-bot#readme",
+  "bugs": {
+    "url": "https://github.com/artickc/grok-telegram-bot/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "diff": "^7.0.0",
+    "dotenv": "^16.4.7",
+    "grammy": "^1.30.0",
+    "tsx": "^4.19.2"
+  },
+  "optionalDependencies": {
+    "@homebridge/node-pty-prebuilt-multiarch": "0.13.1"
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.0",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}

package/scripts/setup.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Easy setup: creates/updates the bot's .env, auto-detects the `grok` binary
+ * and sensible PROJECT_ROOTS, and optionally writes the bot token / user id:
+ *
+ *   node scripts/setup.mjs [--path] [--instance <dir>] [<TELEGRAM_BOT_TOKEN> [ALLOWED_USER_ID]]
+ *
+ * By default the .env lives in the canonical, path-independent home
+ * `~/.grok/tg/.env`, so the bot loads the SAME config no matter where it's
+ * started from. `--path` just prints the resolved .env path and exits.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const examplePath = join(root, ".env.example");
+const CANONICAL_DIR = join(homedir(), ".grok", "tg");
+
+function expandHome(p) {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) return join(homedir(), p.slice(2));
+  return p;
+}
+
+/** Mirror of config.ts resolveInstanceDir() so setup writes EXACTLY where the
+ *  bot will read from. Keep the two in sync. */
+function resolveInstanceDir() {
+  const flag = process.argv.indexOf("--instance");
+  if (flag !== -1 && process.argv[flag + 1]) return resolve(process.argv[flag + 1]);
+  const envDir = (process.env.GROK_TG_DIR || process.env.GROK_TG_CWD || "").trim();
+  if (envDir) return resolve(expandHome(envDir));
+  if (existsSync(join(process.cwd(), ".env"))) return process.cwd();
+  return CANONICAL_DIR;
+}
+
+const argv = process.argv.slice(2);
+let pathOnly = false;
+const positionals = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--path") pathOnly = true;
+  else if (a === "--instance") i++;
+  else positionals.push(a);
+}
+const [tokenArg, userArg] = positionals;
+
+const instanceDir = resolveInstanceDir();
+const envPath = join(instanceDir, ".env");
+
+if (pathOnly) {
+  console.log(envPath);
+  process.exit(0);
+}
+
+mkdirSync(instanceDir, { recursive: true });
+
+function detectGrok() {
+  const home = homedir();
+  const exe = process.platform === "win32" ? "grok.exe" : "grok";
+  const candidates = [
+    join(home, ".grok", "bin", exe),
+    join(home, ".local", "bin", "grok"),
+    "/usr/local/bin/grok",
+    "/opt/homebrew/bin/grok",
+  ];
+  return candidates.find((p) => existsSync(p)) || "";
+}
+
+function detectRoots() {
+  const guesses = ["H:\\Lucru\\Domains", "C:\\Lucru\\Domains", join(homedir(), "projects")];
+  return guesses.filter((p) => existsSync(p));
+}
+
+let env = existsSync(envPath) ? readFileSync(envPath, "utf-8") : readFileSync(examplePath, "utf-8");
+
+function setVar(key, value) {
+  if (value === undefined || value === "") return;
+  const re = new RegExp(`^${key}=.*$`, "m");
+  const line = `${key}=${value}`;
+  env = re.test(env) ? env.replace(re, line) : `${env.trimEnd()}\n${line}\n`;
+}
+
+const grok = detectGrok();
+if (grok) {
+  setVar("GROK_CLI_PATH", grok);
+  console.log(`\u2713 Found grok: ${grok}`);
+} else {
+  console.log("! grok not auto-detected \u2014 set GROK_CLI_PATH in .env or ensure it's on PATH.");
+}
+
+const roots = detectRoots();
+if (roots.length) {
+  setVar("PROJECT_ROOTS", roots.join(","));
+  console.log(`\u2713 PROJECT_ROOTS: ${roots.join(", ")}`);
+}
+
+if (tokenArg) {
+  setVar("TELEGRAM_BOT_TOKEN", tokenArg);
+  console.log("\u2713 Wrote TELEGRAM_BOT_TOKEN");
+}
+if (userArg) {
+  setVar("ALLOWED_USERS", userArg);
+  console.log(`\u2713 Wrote ALLOWED_USERS=${userArg}`);
+}
+
+writeFileSync(envPath, env, "utf-8");
+console.log(`\n\u2713 .env written to ${envPath}`);
+console.log("  (loaded from here no matter which folder you start the bot in)");
+
+if (!/^TELEGRAM_BOT_TOKEN=.+/m.test(env)) {
+  console.log("\nNext: open .env, paste your bot token from @BotFather, then sign in with `grok login` (or /reauth). Then run `grok-tg run`.");
+} else {
+  console.log("\nReady! Sign in with `grok login` if you haven't, then run `grok-tg run` (or `npm start`).");
+}

package/src/agents/catalog.ts

@@ -0,0 +1,58 @@
+/**
+ * Discover Grok sub-agents. Grok ships built-in sub-agents (general, explore,
+ * vision, verify, computer) and supports custom ones defined under `subAgents`
+ * in `~/.grok/user-settings.json`. There is no headless `--agent` flag, so the
+ * bot surfaces these for visibility; the model delegates to them via its own
+ * `task`/`delegate` tools during a turn.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("agents");
+
+export interface AgentInfo {
+  name: string;
+  description?: string;
+  scope: "project" | "global" | "builtin";
+}
+
+const BUILTINS: AgentInfo[] = [
+  { name: "general", description: "General-purpose sub-agent", scope: "builtin" },
+  { name: "explore", description: "Read-only codebase exploration", scope: "builtin" },
+  { name: "vision", description: "Image understanding", scope: "builtin" },
+  { name: "verify", description: "Build/run/test verification", scope: "builtin" },
+];
+
+interface SubAgentEntry {
+  name?: string;
+  instruction?: string;
+  description?: string;
+}
+
+function readSubAgents(path: string, scope: "project" | "global", out: Map<string, AgentInfo>): void {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return;
+  }
+  try {
+    const json = JSON.parse(raw) as { subAgents?: SubAgentEntry[] };
+    for (const a of json.subAgents ?? []) {
+      if (!a.name || out.has(a.name)) continue;
+      out.set(a.name, { name: a.name, description: a.description || a.instruction, scope });
+    }
+  } catch (e) {
+    log.debug(`skip ${path}:`, (e as Error).message);
+  }
+}
+
+export function listAgents(projectPath?: string): AgentInfo[] {
+  const found = new Map<string, AgentInfo>();
+  if (projectPath) readSubAgents(join(projectPath, ".grok", "settings.json"), "project", found);
+  readSubAgents(join(homedir(), ".grok", "user-settings.json"), "global", found);
+  const custom = [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return [...BUILTINS, ...custom];
+}