grok-bot-cli 0.2.3 → 0.3.1

package/README.md

@@ -14,7 +14,7 @@ Manage [Grok Bot](https://cursor.com/help/grok-bot/plans) agents, groups, and me
 npm install --global grok-bot-cli
 ```
 
-Requires Node.js 18+ and the Grok Bot desktop app on macOS or Linux. Open Grok Bot and sign in once; `gbot` automatically uses the app's encrypted session and routing credentials. No token copying is required. On Linux the app keeps its session under `~/.config/Grok Bot` (or `$XDG_CONFIG_HOME`); when it is stored in the system keyring, `gbot` reads the key with `secret-tool` (package `libsecret-tools`).
+Requires Node.js 18+ and the Grok Bot desktop app on macOS, Linux, or Windows. Open Grok Bot and sign in once; `gbot` automatically uses the app's encrypted session and routing credentials. No token copying is required. On Linux the app keeps its session under `~/.config/Grok Bot` (or `$XDG_CONFIG_HOME`); when it is stored in the system keyring, `gbot` reads the key with `secret-tool` (package `libsecret-tools`). On Windows the session lives under `%APPDATA%\\Grok Bot` and decrypts with the app's DPAPI-wrapped Safe Storage key.
 
 ## Use
 
@@ -37,6 +37,105 @@ gbot bots delete Writer
 
 Run `gbot --help` for every command.
 
+## Gateway URL policy
+
+By default `gbot` only sends credentials to expected hosts:
+
+- **Gateway** URLs (box + API): `https` on `*.cursor.sh` / `*.cursor.com` / `*.cursorvm.com` (the box family EnsureSandBox returns).
+- **Backend** URLs (`EnsureSandBox` / `CURSOR_API_BASE_URL`): `https` on `*.cursor.sh` / `*.cursor.com` only — never `*.cursorvm.com`, so a Cursor access token cannot be pointed at a box host.
+
+- `GROK_BOT_ALLOW_LOCAL_GATEWAY=1` — permit `http(s)://127.0.0.1`, `localhost`, and `::1` for **gateways** only (local/dev). Prints a one-shot stderr warning.
+- `GROK_BOT_ALLOW_ANY_GATEWAY=1` — disable host checks (unsafe; for break-glass only). Prints a one-shot stderr warning.
+
+All gateway / `EnsureSandBox` fetches use `redirect: "error"` so credentials are not followed across redirects.
+
+## Messaging Codex threads from Grok Bot
+
+`gbot codex` attaches to a local [Codex app-server](https://learn.chatgpt.com/docs/app-server) daemon and injects messages into its threads with the documented JSON-RPC methods (`initialize`, `thread/list`, `thread/resume`, `turn/start`).
+
+```sh
+codex app-server daemon start          # once per machine session
+gbot codex status                      # socket, daemon version, reachability
+gbot codex list-threads --limit 10     # id, status, cwd, preview
+gbot codex send <threadId> "Grok here: the build is green, please continue."
+```
+
+`send` resumes the thread, starts a turn with your text, prints the turn id, and returns; Codex keeps working after `gbot` disconnects. Every command accepts `--json`.
+
+**Which Codex you reach.** `gbot` connects to `$CODEX_HOME/app-server-control/app-server-control.sock` (default `~/.codex/...`) with a built-in WebSocket client. The daemon must be started by `codex app-server daemon start`. `list-threads` shows the threads recorded under `CODEX_HOME` (CLI, TUI, VS Code); `send` works on any of them that no other client currently holds open. Method and parameter names are pinned to the Codex release recorded in `src/codex-bridge.js` (`codex app-server generate-json-schema`); `status` prints the daemon and CLI versions so a stale daemon is visible, and `codex app-server daemon restart` picks up the installed CLI. Native Windows is not supported yet (AF_UNIX control socket); use WSL, Linux, or macOS.
+
+**ChatGPT Desktop limitation.** Desktop runs its own private stdio app-server and does not publish the shared control socket, so external clients cannot reach live Desktop tasks. When the socket is absent, `gbot codex status` exits 1 and says so, naming the upstream issues: [openai/codex#41014](https://github.com/openai/codex/issues/41014) and [openai/codex#41112](https://github.com/openai/codex/issues/41112). `gbot` never reads Desktop's temporary `CODEX_APP_TOOLS_PIPE_PATH` sockets under `/tmp/codex-browser-use/`; that channel is private to Desktop.
+
+**Failure modes.**
+
+- Socket absent: no daemon, or Desktop-private mode. Start the daemon or wait for the upstream fixes.
+- Unknown thread: `send` fails with "Unknown Codex thread"; use `list-threads`.
+- Thread open elsewhere: a thread with an active writer (VS Code, TUI) fails with "open in another client"; close it there first.
+- Approvals: `gbot` never approves commands or file changes on your behalf. If Codex asks while `gbot` is still connected, `send` refuses the request, exits 1, and tells you the turn id. `send` disconnects as soon as the turn starts, so later approval requests stay with the daemon for a Codex client to answer; for unattended sends set `approval_policy = "never"` in the daemon's `config.toml`.
+
+## Talking to Grok Bot from Codex
+
+`plugin/` is an [Agent Bundle](https://scriptedalchemy.github.io/agent-bundle/) plugin
+that gives Codex, Claude Code, and Cursor two MCP tools on a `grok-bot` server,
+`gbot_send` and `gbot_thread`, plus a `talk-to-grok-bot` skill that tells the agent
+when to ping a bot and how to word the message. The tools bundle this repository's
+gateway client, so the installed plugin does not need `gbot` on `PATH`.
+
+The plugin is not part of the npm package. From a clone of this repository, build
+the artifact once, then install it into each host you use:
+
+```sh
+git clone https://github.com/ScriptedAlchemy/grok-bot-cli.git
+cd grok-bot-cli/plugin
+npm install
+npm run build
+npx agent-bundle install codex --from artifact
+npx agent-bundle install claude --from artifact
+npx agent-bundle install cursor --from artifact
+npx agent-bundle doctor --from artifact
+```
+
+Add `--replace` to an install command to overwrite an earlier copy. `npm run check`
+runs the plugin gates: source validation, build, artifact validation, typecheck, and
+the route-unit tests, which drive both tools against a loopback fake gateway.
+
+Auth resolves exactly as for `gbot`: `GROK_BOT_GATEWAY_URL` + `GROK_BOT_GATEWAY_TOKEN`,
+then the Grok Bot app session, then `CURSOR_ACCESS_TOKEN`. The MCP server therefore
+needs outbound HTTPS to the gateway host and read access to the app-session file
+(`~/.config/Grok Bot` on Linux, `~/Library/Application Support/Grok Bot` on macOS).
+A sandbox that blocks network egress or hides the home directory makes `gbot_send`
+fail with the gateway error; run `gbot doctor` inside the same sandbox to see which
+credential source is visible.
+
+To route a repository's agents to a bot by default, add a note to its `AGENTS.md`:
+
+```md
+## Grok Bot
+
+Use the `grok-bot` MCP tools to coordinate with Grok Bot. Send questions and
+handoffs to the `General` bot with `gbot_send` (first line: who you are and what
+you need), then read the reply with `gbot_thread`. Do not block a turn waiting
+for it.
+```
+
+## Local history
+
+Recording is **opt-in**. Set `GROK_BOT_HISTORY=on` (or `true`/`1`) to append successful
+`send`/`thread`/`chat` observations as plaintext JSONL at
+`~/.grok-bot-cli/history.jsonl`. Without that env, nothing is written.
+
+```bash
+export GROK_BOT_HISTORY=on
+gbot send Researcher "Investigate the startup timeout"
+gbot thread Researcher
+gbot history Researcher --search timeout
+gbot history --path
+```
+
+`history` works offline. Use `--history-dir` / `GROK_BOT_HISTORY_DIR` to relocate,
+`--no-history` to skip one command. New dirs are `0700`, files `0600`. Conversation
+text is recorded as you typed it; gateway credentials and raw response metadata are not.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-bot-cli",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "CLI for Grok Bot agents and groups: create, update, message, inspect threads, and automate cleanup",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
     "changeset": "changeset",
     "gbot": "node src/cli.js",
     "release": "changeset publish",
-    "test": "node --test"
+    "test": "node scripts/run-unit-tests.mjs"
   },
   "repository": {
     "type": "git",
@@ -43,6 +43,6 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@changesets/cli": "3.0.1"
+    "@changesets/cli": "3.0.3"
   }
 }

package/src/app-session.js

@@ -6,10 +6,12 @@ import { join } from "node:path";
 
 // Chromium OSCrypt: "v10" = fixed password (macOS: the Keychain password; Linux: "peanuts"),
 // "v11" = Linux Secret Service password. macOS stretches with 1003 PBKDF2 rounds, Linux with 1.
+// Windows v10 uses AES-256-GCM with a DPAPI-wrapped key from Local State (not PBKDF2).
 const SAFE_STORAGE_PREFIX_V10 = "v10";
 const SAFE_STORAGE_PREFIX_V11 = "v11";
+const SAFE_STORAGE_PREFIX_V10_BUF = Buffer.from(SAFE_STORAGE_PREFIX_V10);
 const LINUX_BASIC_TEXT_PASSWORD = "peanuts";
-const SUPPORTED_PLATFORMS = new Set(["darwin", "linux"]);
+const SUPPORTED_PLATFORMS = new Set(["darwin", "linux", "win32"]);
 
 export class GrokBotGatewaySessionError extends Error {
   constructor(code, message) {
@@ -80,23 +82,57 @@ export function decryptSafeStorageString(encryptedBase64, password, platform = "
   ]).toString("utf8");
 }
 
-export function grokBotGatewayDescriptorPath(home = homedir(), platform = process.platform, env = process.env) {
+// Windows Chromium Safe Storage: "v10" + 12-byte nonce + AES-256-GCM ciphertext + 16-byte tag.
+export function decryptWindowsSafeStorageString(encryptedBase64, key) {
+  const encrypted = Buffer.from(encryptedBase64, "base64");
+  if (!encrypted.subarray(0, 3).equals(SAFE_STORAGE_PREFIX_V10_BUF)) {
+    throw new Error("Unsupported Grok Bot Safe Storage format.");
+  }
+
+  const decipher = crypto.createDecipheriv(
+    "aes-256-gcm",
+    key,
+    encrypted.subarray(3, 15),
+  );
+  decipher.setAuthTag(encrypted.subarray(-16));
+  return Buffer.concat([
+    decipher.update(encrypted.subarray(15, -16)),
+    decipher.final(),
+  ]).toString("utf8");
+}
+
+function grokBotAppDataPath(home, platform, env = {}) {
+  if (platform === "win32") {
+    const appData = env.APPDATA || join(home, "AppData/Roaming");
+    return join(appData, "Grok Bot");
+  }
   if (platform === "linux") {
     const configHome = env.XDG_CONFIG_HOME || join(home, ".config");
-    return join(configHome, "Grok Bot/gateway-descriptor.json");
+    return join(configHome, "Grok Bot");
   }
-  return join(
-    home,
-    "Library/Application Support/Grok Bot/gateway-descriptor.json",
-  );
+  return join(home, "Library/Application Support/Grok Bot");
+}
+
+export function grokBotGatewayDescriptorPath(home = homedir(), platform = process.platform, env = process.env) {
+  return join(grokBotAppDataPath(home, platform, env), "gateway-descriptor.json");
+}
+
+function sessionEnv({ env = process.env, appData } = {}) {
+  // Windows tests pass appData directly; empty string clears APPDATA to exercise the home fallback.
+  if (appData !== undefined) return { ...env, APPDATA: appData };
+  return env;
 }
 
 export function hasGrokBotGatewaySession({
   platform = process.platform,
   home = homedir(),
   env = process.env,
+  appData,
 } = {}) {
-  return SUPPORTED_PLATFORMS.has(platform) && existsSync(grokBotGatewayDescriptorPath(home, platform, env));
+  return (
+    SUPPORTED_PLATFORMS.has(platform) &&
+    existsSync(grokBotGatewayDescriptorPath(home, platform, sessionEnv({ env, appData })))
+  );
 }
 
 function readKeychainPassword(platform = process.platform) {
@@ -114,27 +150,72 @@ function readKeychainPassword(platform = process.platform) {
   ).trimEnd();
 }
 
+function unprotectWithDpapi(blob) {
+  const script =
+    "Add-Type -AssemblyName System.Security; " +
+    "$blob = [Convert]::FromBase64String([Console]::In.ReadToEnd().Trim()); " +
+    "[Convert]::ToBase64String([Security.Cryptography.ProtectedData]::Unprotect($blob, $null, 'CurrentUser'))";
+  const out = execFileSync(
+    join(
+      process.env.SystemRoot ?? "C:\\Windows",
+      "System32/WindowsPowerShell/v1.0/powershell.exe",
+    ),
+    ["-NoProfile", "-NonInteractive", "-Command", script],
+    { input: blob.toString("base64"), encoding: "utf8" },
+  );
+  return Buffer.from(out.trim(), "base64");
+}
+
+function readWindowsSafeStorageKey(home, env, unprotectData) {
+  const path = join(grokBotAppDataPath(home, "win32", env), "Local State");
+  const encryptedKey = existsSync(path)
+    ? JSON.parse(readFileSync(path, "utf8")).os_crypt?.encrypted_key
+    : null;
+  const blob = Buffer.from(
+    typeof encryptedKey === "string" ? encryptedKey : "",
+    "base64",
+  );
+  if (blob.subarray(0, 5).toString("latin1") !== "DPAPI") {
+    throw new GrokBotGatewaySessionError(
+      "MISSING_SAFE_STORAGE_KEY",
+      "Grok Bot Local State has no Safe Storage key.",
+    );
+  }
+  return unprotectData(blob.subarray(5));
+}
+
 export function loadGrokBotGatewaySession({
   platform = process.platform,
   home = homedir(),
   env = process.env,
+  appData,
   getKeychainPassword = readKeychainPassword,
+  unprotectData = unprotectWithDpapi,
 } = {}) {
   if (!SUPPORTED_PLATFORMS.has(platform)) return null;
 
-  const path = grokBotGatewayDescriptorPath(home, platform, env);
+  const effectiveEnv = sessionEnv({ env, appData });
+  const path = grokBotGatewayDescriptorPath(home, platform, effectiveEnv);
   if (!existsSync(path)) return null;
 
   const wrapped = JSON.parse(readFileSync(path, "utf8"));
   const encrypted = encryptedPayload(wrapped);
-  const prefix = Buffer.from(encrypted, "base64").subarray(0, 3).toString("latin1");
-  // Linux v10 is the keyring-less basic_text backend; no secret store to ask.
-  const needsKeychain = !(platform === "linux" && prefix === SAFE_STORAGE_PREFIX_V10);
-  const clear = decryptSafeStorageString(
-    encrypted,
-    needsKeychain ? getKeychainPassword(platform) : LINUX_BASIC_TEXT_PASSWORD,
-    platform,
-  );
+  let clear;
+  if (platform === "win32") {
+    clear = decryptWindowsSafeStorageString(
+      encrypted,
+      readWindowsSafeStorageKey(home, effectiveEnv, unprotectData),
+    );
+  } else {
+    const prefix = Buffer.from(encrypted, "base64").subarray(0, 3).toString("latin1");
+    // Linux v10 is the keyring-less basic_text backend; no secret store to ask.
+    const needsKeychain = !(platform === "linux" && prefix === SAFE_STORAGE_PREFIX_V10);
+    clear = decryptSafeStorageString(
+      encrypted,
+      needsKeychain ? getKeychainPassword(platform) : LINUX_BASIC_TEXT_PASSWORD,
+      platform,
+    );
+  }
   const descriptor = JSON.parse(clear);
   if (!descriptor.baseUrl || !descriptor.token) {
     throw new GrokBotGatewaySessionError(

package/src/cli.js

@@ -3,6 +3,10 @@ import { AVATAR_COLORS, AVATAR_SHAPES, MAX_GROUP_MEMBERS, StoreError, defaultCan
 import { hasGatewayAuth } from "./gateway.js";
 import { openBackend } from "./commands.js";
 import { inspectGrokBotGatewaySession } from "./app-session.js";
+import { entryText, transcriptEntries } from "./transcript.js";
+import { historyPath, readHistory, saveHistory } from "./history.js";
+import { redactSecrets } from "./url-policy.js";
+import { codexStatus, listCodexThreads, sendToCodexThread } from "./codex-bridge.js";
 
 function print(value) {
   if (typeof value === "string") process.stdout.write(value + "\n");
@@ -11,8 +15,17 @@ function print(value) {
 
 function fail(err) {
   let message = err instanceof Error ? err.message : String(err);
-  message = message.replace(/Bearer\s+[A-Za-z0-9._\-]+/g, "Bearer <redacted>");
-  process.stderr.write(message + "\n");
+  message = redactSecrets(message);
+  if (jsonErrors && err instanceof Error) {
+    const out = { error: message };
+    if (err.delivery !== undefined) out.delivery = err.delivery;
+    if (err.threadId !== undefined) out.threadId = err.threadId;
+    if (err.turnId !== undefined) out.turnId = err.turnId;
+    if (err.targetId !== undefined) out.targetId = err.targetId;
+    process.stderr.write(JSON.stringify(out) + "\n");
+  } else {
+    process.stderr.write(message + "\n");
+  }
   process.exit(1);
 }
 
@@ -45,8 +58,13 @@ function usage() {
     "  groups set <group> --member ID [--member ...]",
     "  groups delete <id-or-name>",
     "  send <bot-or-group> <message...>",
-    "  thread <bot-or-group> [--limit N] [--root MESSAGE_ID]",
+    "  thread <bot-or-group> [--limit N] [--root MESSAGE_ID] [--full]",
     "  chat <bot-or-group>     alias for thread",
+    "  history [bot-or-group] [--search TEXT] [--limit N]  (offline)",
+    "  history --path         print the local JSONL file path",
+    "  codex status",
+    "  codex list-threads [--limit N]",
+    "  codex send <threadId> <message...>",
     "",
     "Max group members: " + MAX_GROUP_MEMBERS,
     "--description / --instructions is the UI Instructions field (same key).",
@@ -55,6 +73,10 @@ function usage() {
     "Flags: --gateway  --files  --dir DIR  --json",
     "Auth: GROK_BOT_GATEWAY_URL + GROK_BOT_GATEWAY_TOKEN, or the Grok Bot app session, or CURSOR_ACCESS_TOKEN",
     "File fallback: GROK_BOT_AGENTS_DIR",
+    "Codex: talks to the local app-server daemon socket under CODEX_HOME (default ~/.codex)",
+    "History: opt-in plaintext JSONL at ~/.grok-bot-cli/history.jsonl",
+    "         GROK_BOT_HISTORY=on to record; --history-dir / GROK_BOT_HISTORY_DIR to relocate",
+    "         --no-history to skip one command",
   ].join("\n");
 }
 
@@ -105,6 +127,81 @@ function hasFlag(args, name) {
   return true;
 }
 
+/** Peel a trailing flag that `--` does not protect; free-text commands keep mid-text tokens. */
+function takeTrailingFlag(args, name) {
+  const stop = args.indexOf("--");
+  const end = stop === -1 ? args.length : stop;
+  if (end > 0 && args[end - 1] === name) {
+    args.splice(end - 1, 1);
+    return true;
+  }
+  return false;
+}
+
+/** Peel global CLI options only from the leading argv (before the command). */
+let jsonErrors = false;
+function takeLeadingGlobals(args) {
+  let json = false;
+  let gateway = false;
+  let files = false;
+  let noHistory = false;
+  let historyDir;
+  let dir;
+  while (args.length) {
+    const a = args[0];
+    if (a === "--") {
+      args.shift();
+      break;
+    }
+    if (a === "--json") {
+      json = true;
+      jsonErrors = true;
+      args.shift();
+      continue;
+    }
+    if (a === "--gateway") {
+      gateway = true;
+      args.shift();
+      continue;
+    }
+    if (a === "--files") {
+      files = true;
+      args.shift();
+      continue;
+    }
+    if (a === "--no-history") {
+      noHistory = true;
+      args.shift();
+      continue;
+    }
+    if (a === "--history-dir") {
+      args.shift();
+      const value = args.shift();
+      if (value == null || value.startsWith("-")) throw new StoreError("--history-dir needs a value");
+      historyDir = value;
+      continue;
+    }
+    if (a === "--dir") {
+      args.shift();
+      const value = args.shift();
+      if (value == null || value.startsWith("-")) throw new StoreError("--dir needs a value");
+      dir = value;
+      continue;
+    }
+    break;
+  }
+  return { json, gateway, files, dir, noHistory, historyDir };
+}
+
+/** Strip CSI/OSC and other C0/C1 controls so thread fields cannot drive the terminal. */
+function stripTerminalControls(text) {
+  return String(text)
+    .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, "")
+    .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, "")
+    .replace(/\u001b./g, "")
+    .replace(/[\u0000-\u001F\u007F-\u009F]/g, "");
+}
+
 function parseOnOff(value, flag) {
   const v = String(value).trim().toLowerCase();
   if (v === "on" || v === "true" || v === "1" || v === "yes") return true;
@@ -184,27 +281,10 @@ function formatRecord(rec, all) {
   return kind + "  " + rec.name + title + "\n    " + rec.id + desc + avatar + settingsLine + extra;
 }
 
-function entryText(e) {
-  if (!e || typeof e !== "object") return "";
-  const direct = e.text || e.prompt || e.message || e.preview;
-  if (typeof direct === "string" && direct) return direct;
-  const content = e.content;
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) {
-    return content.map((part) => {
-      if (typeof part === "string") return part;
-      if (part && typeof part === "object") return part.text || part.content || "";
-      return "";
-    }).filter(Boolean).join("\n");
-  }
-  if (content && typeof content === "object") return content.text || JSON.stringify(content);
-  return "";
-}
-
-function formatTranscript(out) {
+function formatTranscript(out, { full = false } = {}) {
   const rec = out.target;
   const payload = out.transcript || out.thread || {};
-  const entries = payload.entries || payload.messages || payload.items || (Array.isArray(payload) ? payload : []);
+  const entries = transcriptEntries(payload);
   const header = (rec.isGroup ? "group" : "bot") + "  " + rec.name + "\n    " + rec.id;
   if (!Array.isArray(entries) || entries.length === 0) {
     return header + "\n    (no messages)";
@@ -214,11 +294,70 @@ function formatTranscript(out) {
     const role = e.role || e.kind || e.sender || e.type || "msg";
     const text = entryText(e);
     const id = e.id || e.messageId || "";
-    lines.push("[" + role + (id ? " " + id : "") + "] " + String(text).slice(0, 400));
+    lines.push("[" + role + (id ? " " + id : "") + "] " + (full ? text : truncateCliText(text)));
   }
   return lines.join("\n");
 }
 
+/** Bounded preview; --json/--full still retrieve the complete text. */
+function truncateCliText(text, max = 400) {
+  if (text.length <= max) return text;
+  return text.slice(0, max) + "… [+" + (text.length - max) + " chars; --full or --json for complete text]";
+}
+
+function formatCodexStatus(s) {
+  const lines = ["socket: " + s.socketPath];
+  if (!s.reachable) return lines.concat("reachable: no", s.message).join("\n");
+  lines.push("reachable: yes (daemon)");
+  lines.push("daemon version: " + (s.daemonVersion ?? "unknown") + "  cli version: " + (s.cliVersion ?? "unknown") + "  pinned schema: " + s.pinnedVersion);
+  if (s.versionMismatch) lines.push("warning: daemon and CLI versions differ; `codex app-server daemon restart` picks up the installed CLI");
+  return lines.join("\n");
+}
+
+function formatCodexThread(t) {
+  const title = t.name ? " - " + stripTerminalControls(t.name) : "";
+  const preview = t.preview
+    ? "\n    " + stripTerminalControls(String(t.preview).replace(/\s+/g, " ")).slice(0, 200)
+    : "";
+  return stripTerminalControls(t.id) + "  " + stripTerminalControls(t.status) + title + "\n    " + stripTerminalControls(t.cwd ?? "") + preview;
+}
+
+async function runCodex(sub, rest, json) {
+  // Structured subcommands take no free text, so --json peels anywhere. Send
+  // peels a trailing --json only; mid-message tokens stay message content.
+  if (sub === "status" || sub === "list-threads") {
+    if (hasFlag(rest, "--json")) { json = true; jsonErrors = true; }
+  }
+  if (sub === "status") {
+    const status = await codexStatus();
+    print(json ? status : formatCodexStatus(status));
+    if (!status.reachable) process.exitCode = 1;
+    return;
+  }
+  if (sub === "list-threads") {
+    const limitRaw = takeFlag(rest, "--limit");
+    const limit = limitRaw ? Number(limitRaw) : 20;
+    if (!Number.isInteger(limit) || limit < 1) throw new StoreError("--limit must be a positive integer");
+    const out = await listCodexThreads({ limit });
+    if (json) print(out);
+    else if (out.threads.length === 0) print("No Codex threads.");
+    else print(out.threads.map(formatCodexThread).join("\n\n"));
+    return;
+  }
+  if (sub === "send") {
+    const threadId = rest.shift();
+    if (takeTrailingFlag(rest, "--json")) { json = true; jsonErrors = true; }
+    if (rest[0] === "--") rest.shift();
+    const message = rest.join(" ").trim();
+    if (!threadId || threadId.startsWith("-") || !message) throw new StoreError("gbot codex send <threadId> <message...>");
+    const out = await sendToCodexThread(threadId, message);
+    if (json) print(out);
+    else print("Started turn " + out.turnId + " (" + out.turnStatus + ") on Codex thread " + out.threadId);
+    return;
+  }
+  throw new StoreError("gbot codex status | list-threads [--limit N] | send <threadId> <message...>");
+}
+
 async function main(argv) {
   const args = argv.slice(2);
   if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
@@ -226,10 +365,8 @@ async function main(argv) {
     return;
   }
 
-  const json = hasFlag(args, "--json");
-  const gateway = hasFlag(args, "--gateway");
-  const filesMode = hasFlag(args, "--files");
-  const rootFlag = takeFlag(args, "--dir");
+  // `json` may also be peeled later from command-local argv (trailing `--json`).
+  let { json, gateway, files: filesMode, dir: rootFlag, noHistory, historyDir } = takeLeadingGlobals(args);
   const cmd = args[0];
   const sub = args[1];
   const rest = args.slice(2);
@@ -267,6 +404,41 @@ async function main(argv) {
     return;
   }
 
+  if (cmd === "history") {
+    const options = args.slice(1);
+    // Command-local flags (globals only peel from argv before the command).
+    if (hasFlag(options, "--json")) { json = true; jsonErrors = true; }
+    const showPath = hasFlag(options, "--path");
+    const search = takeFlag(options, "--search");
+    const limitRaw = takeFlag(options, "--limit");
+    const limit = limitRaw === undefined ? 40 : Number(limitRaw);
+    if (!Number.isSafeInteger(limit) || limit < 1) throw new StoreError("--limit must be a positive integer");
+    if (options.length > 1 || options[0]?.startsWith("-") || (showPath && (options.length || search !== undefined || limitRaw !== undefined))) {
+      throw new StoreError("gbot history [bot-or-group] [--search TEXT] [--limit N], or history --path");
+    }
+    const path = historyPath(historyDir);
+    if (showPath) print(json ? { path } : path);
+    else {
+      const rows = await readHistory(path, { ref: options[0], search, limit });
+      if (json) print(rows);
+      else print(rows.length ? rows.map((row) =>
+        "[" + row.recordedAt + "] " + row.target.name + " (" + row.target.id + ") [" + row.role + "] " + row.text
+      ).join("\n") : "No local history.");
+    }
+    return;
+  }
+
+  if (cmd === "codex") {
+    await runCodex(sub, rest, json);
+    return;
+  }
+
+  // Peel command-local --json before touching the backend so auth/gateway
+  // failures honor it. Send peels a trailing --json only (mid-text tokens stay
+  // message content); `--` protects everything after it.
+  if (cmd === "send" && takeTrailingFlag(rest, "--json")) { json = true; jsonErrors = true; }
+  if ((cmd === "thread" || cmd === "chat") && hasFlag(rest, "--json")) { json = true; jsonErrors = true; }
+
   const backend = await openBackend({ root: rootFlag, gateway, files: filesMode });
 
   if (cmd === "bots" && sub === "list") {
@@ -376,23 +548,29 @@ async function main(argv) {
 
   if (cmd === "send") {
     const ref = sub;
+    if (hasFlag(rest, "--json")) { json = true; jsonErrors = true; }
     const message = rest.join(" ").trim();
     if (!ref || !message) throw new StoreError("gbot send <bot-or-group> <message...>");
     const out = await backend.send(ref, message);
-    if (json) print({ id: out.target.id, name: out.target.name, kind: out.target.isGroup ? "group" : "bot", result: out.result });
-    else print("Sent to " + (out.target.isGroup ? "group" : "bot") + " " + out.target.name + " (" + out.target.id + ")");
+    saveHistory(out, { dir: historyDir, disabled: noHistory, event: "send", prompt: message });
+    const receipt = out.messageId ? " message " + out.messageId : "";
+    if (json) print({ id: out.target.id, name: out.target.name, kind: out.target.isGroup ? "group" : "bot", result: out.result, delivery: out.delivery || "accepted", ...(out.messageId ? { messageId: out.messageId } : {}) });
+    else print("Sent to " + (out.target.isGroup ? "group" : "bot") + " " + out.target.name + " (" + out.target.id + ")" + receipt);
     return;
   }
 
   if (cmd === "thread" || cmd === "chat") {
     const ref = sub;
-    if (!ref) throw new StoreError("gbot thread <bot-or-group> [--limit N] [--root MESSAGE_ID]");
+    if (!ref) throw new StoreError("gbot thread <bot-or-group> [--limit N] [--root MESSAGE_ID] [--full]");
+    const full = hasFlag(rest, "--full");
     const limitRaw = takeFlag(rest, "--limit");
     const rootId = takeFlag(rest, "--root");
     const limit = limitRaw ? Number(limitRaw) : 40;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new StoreError("--limit must be an integer 1-200");
     const out = rootId ? await backend.thread(ref, rootId) : await backend.transcript(ref, limit);
+    saveHistory(out, { dir: historyDir, disabled: noHistory, event: cmd, rootId });
     if (json) print(out);
-    else print(formatTranscript(out));
+    else print(formatTranscript(out, { full }));
     return;
   }