@ucsandman/legcli 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.8.0 (2026-09-16)
+
+- **Grok is a supervised and handoff agent.** `leg grok` starts Grok the same
+  way `leg claude`, `leg codex` and `leg agy` start those agents: board
+  alongside, usage tracking, and a live context handoff bundle. At the limit
+  the next agent continues in the same terminal.
+- **Auto-approve is on by default** for new sessions. Leg injects each agent's
+  fully-permissive flag at spawn (`--dangerously-skip-permissions` for Claude
+  and agy, `--ask-for-approval never` for Codex, `--always-approve` for Grok).
+  Opt out with `--no-auto-approve`, `LEG_AUTO_APPROVE=0` /
+  `LEG_NO_AUTO_APPROVE=1`, or `"auto_approve": false` in `preferences.json`.
+
 ## 0.7.0 (2026-09-15)
 
 - **Rebranded to Leg.** Package is now `legcli` on npm, binary command is `leg`,

package/README.md

@@ -1,6 +1,6 @@
 # leg
 
-**Type `leg claude`, `leg codex` or `leg agy` instead of the bare command. You get the same interactive agent; Leg opens a board next to it, watches the usage limit, keeps a handoff bundle current, and when the limit hits it starts the next agent in the same terminal from that bundle.**
+**Type `leg claude`, `leg codex`, `leg agy` or `leg grok` instead of the bare command. You get the same interactive agent; Leg opens a board next to it, watches the usage limit, keeps a handoff bundle current, and when the limit hits it starts the next agent in the same terminal from that bundle.**
 
 [![License: commercial](https://img.shields.io/badge/license-commercial-blue.svg)](https://legcli.com/license)
 [![Node 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://legcli.com/docs/getting-started)
@@ -26,15 +26,15 @@ settings file and never edits yours. `leg claude --model opus` is
    own worktree and a **Land** button instead of writing over the first.
 2. **Usage tracking** per agent and account, from what each CLI already
    exposes: Claude Code's usage endpoint and its `StopFailure` hook, Codex's
-   read-only app-server rate-limit read, agy's log.
+   read-only app-server rate-limit read, agy's log, and Grok's billing proxy endpoint.
 3. **A context handoff bundle** ([context-handoff-bundle](https://pypi.org/project/context-handoff-bundle/))
    refreshed as the session goes, so the work is always ready to hand off.
 4. **The handoff itself.** Near the limit you get a warning. At the limit Leg
    saves the bundle, stops the agent, and starts the next option in the same
    terminal from that bundle: another login of the same agent if you added
    one, otherwise the next agent in the order shown on the terminal card.
-   The default is claude → codex → agy, and Settings changes the default for
-   new terminals. Nothing is retyped.
+   The default is claude -> codex -> agy (with grok supported in handoff order),
+   and Settings changes the default for new terminals. Nothing is retyped.
    When every option is out, it tells you which resets first and when, waits
    for that reset with a countdown, and starts that agent from the bundle.
 
@@ -43,9 +43,10 @@ Subscription logins only: Leg strips `ANTHROPIC_API_KEY`,
 `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_API_BASE`, `GEMINI_API_KEY`,
 `GOOGLE_API_KEY`, `GOOGLE_GEMINI_BASE_URL`, `GOOGLE_GENAI_USE_VERTEXAI`,
 `GOOGLE_GENAI_USE_ENTERPRISE`, `GOOGLE_CLOUD_PROJECT`,
-`GOOGLE_CLOUD_LOCATION`, `GOOGLE_APPLICATION_CREDENTIALS`, `CLAUDECODE`,
-`CLAUDE_CODE_*`, `CLAUDE_EFFORT`, and `CLAUDE_PLUGIN_DATA` before any agent
-starts. It then sets `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` for a detached
+`GOOGLE_CLOUD_LOCATION`, `GOOGLE_APPLICATION_CREDENTIALS`, `GROK_API_KEY`,
+`XAI_API_KEY`, `CLAUDECODE`, `CLAUDE_CODE_*`, `CLAUDE_EFFORT`, and
+`CLAUDE_PLUGIN_DATA` before any agent starts. It then sets
+`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` for a detached
 Claude print session. Leg never edits `~/.claude/settings.json` or any other
 settings file of yours; its hooks ride in a separate per-session `--settings`
 file. The one thing it does write outside `~/.leg` is the folder-trust
@@ -103,7 +104,7 @@ yourself.
 ## 60-second run
 
 Prerequisites: Node 22 or newer, git, Python 3 with pip, and at least one
-logged-in agent CLI (`claude`, `codex` or `agy`).
+logged-in agent CLI (`claude`, `codex`, `agy` or `grok`).
 
 ```
 npm install -g @ucsandman/legcli
@@ -136,6 +137,7 @@ which.
 | claude | `GET api.anthropic.com/api/oauth/usage` with the login Claude Code stored, the same data as `/usage` and the built-in status line (`five_hour`, `seven_day`, `utilization`, `resets_at`); polled every 60 s | `StopFailure` hook with `error: rate_limit` ([docs](https://code.claude.com/docs/en/hooks#stopfailure)) | one extra settings file per session via `--settings`, carrying only Leg's own hooks; `autoContinueAtUsageLimit` is set to `false` because Leg owns the handoff | observed live |
 | codex | read-only `account/rateLimits/read` through the app-server, polled every 60 s by the board and active attach; windows are identified by duration (300 minutes = 5h, 10080 = 7d) | `task_complete.error.codex_error_info: usage_limit_exceeded`, message "You've hit your usage limit … try again at …" (`codex-rs/protocol/src/error.rs`) | no model turn and no hook are injected; the board reads the CLI backend and records only returned windows | verified by source and regression tests |
 | agy | none exposed (agy's own status line fetches a quota summary that is written nowhere) | `RESOURCE_EXHAUSTED`, "it resets in …", "out of quota" in the log | `--log-file` per session; `~/.gemini/antigravity-cli/history.jsonl` gives the prompts and conversation id | observed live (a real `RESOURCE_EXHAUSTED` with its reset was read from the log on 2026-09-11) |
+| grok | `GET cli-chat-proxy.grok.com/v1/billing?format=credits` and `GET cli-chat-proxy.grok.com/v1/user?include=subscription` with OAuth token from `~/.grok/auth.json` (`creditUsagePercent`, `currentPeriod` weekly reset); polled every 60 s | `-32003` rate limit error, "You've hit the rate limit for your plan. Try again later.", "Rate limited (429)", `StopFailureKind::RateLimit` (`xai-org/grok-build`) | `--debug-file grok.log` per session; `~/.grok/sessions/<encoded-cwd>/prompt_history.jsonl` gives prompts and session id | verified by source and proxy endpoint |
 
 Why not Claude Code's status line JSON (`rate_limits.five_hour.used_percentage`):
 on 2.1.268 the custom `statusLine` Leg passes through `--settings` did not
@@ -387,15 +389,15 @@ happens after you run `leg accounts add`; that is your call.
 ## CLI reference
 
 ```
-leg claude|codex|agy [agent args…]   the interactive agent, board alongside, handoff on limit
+leg claude|codex|agy|grok [agent args…] the interactive agent, board alongside, handoff on limit
       [--no-worktree]                  share the checkout with a live session instead of a worktree
 leg sessions ls [--json]             every session and its usage
 leg sessions show|events <id>
 leg sessions handoff|end <id>        same as the board buttons
 leg sessions rm <id>                 forget an ended session
-leg sessions simulate-limit <id>     the real limit path without a real wall (claude, agy)
+leg sessions simulate-limit <id>     the real limit path without a real wall (claude, agy, grok)
 leg accounts ls                      logins and their 5h/7d usage
-leg accounts add <claude|codex> <name> | rm <agent> <name> | terms
+leg accounts add <claude|codex|grok> <name> | rm <agent> <name> | terms
 leg license                          the license on this machine, or where to buy one
 leg license activate <key> | deactivate | refresh   (refresh renews a Team key)
 leg share                            who is on the board (off by default; Team plan)
@@ -409,9 +411,9 @@ Environment, all optional: `LEG_HOME` (default `~/.leg`), `LEG_PORT`
 (4747), `LEG_ACCOUNT` (start on a named login), `LEG_WARN_PCT` (85),
 `LEG_NO_HANDOFF=1` (warn and record, never switch), `LEG_NO_OPEN=1` (do not
 open the browser), `LEG_USAGE_POLL_MS` (60000), `LEG_CLAUDE_ARGS` /
-`LEG_CODEX_ARGS` / `LEG_AGY_ARGS` (extra args for a leg Leg starts after
+`LEG_CODEX_ARGS` / `LEG_AGY_ARGS` / `LEG_GROK_ARGS` (extra args for a leg Leg starts after
 a hand-off, e.g. `-m gpt-5.3-codex-spark`), `LEG_CLAUDE_BIN`,
-`LEG_CODEX_BIN`, `LEG_AGY_BIN`, `LEG_CHB_BIN`, `LEG_PERSON` (whose
+`LEG_CODEX_BIN`, `LEG_AGY_BIN`, `LEG_GROK_BIN`, `LEG_CHB_BIN`, `LEG_PERSON` (whose
 terminal this is when the board is shared), `LEG_RATE_MAX` (600 requests a
 minute per human) and `LEG_RATE_MAX_FAILURES` (20 wrong tokens per address).
 
@@ -542,7 +544,7 @@ Leg is commercial software under the [Leg License Agreement](LICENSE).
 It ships as readable JavaScript so you can see what it does on your machine,
 and you may modify it for your own use, but not redistribute it or work
 around the license check. Versions 0.2.0 and 0.3.0 were published under MIT
-and remain available. The version in this source tree is 0.7.0; see
+and remain available. The version in this source tree is 0.8.0; see
 [npm](https://www.npmjs.com/package/legcli) for published versions and
 [CHANGELOG.md](CHANGELOG.md) for release notes.
 

package/bin/leg.mjs

@@ -20,7 +20,7 @@ import { availableActions } from '../src/chain.mjs'
 import { up, down, stopBoard, status, openBoard } from '../src/launcher.mjs'
 import { attach, ensureBoard } from '../src/attach.mjs'
 import { readShare, addPerson, removePerson, rotate as rotateToken, turnOn, turnOff, linkFor, personNamed } from '../src/share.mjs'
-import { AGENTS, listSessions, readSession, readEvents as readSessionEvents, requestControl, removeSession, isActive, readLand, sessionDir, appendEvent } from '../src/sessions.mjs'
+import { SUPERVISED_AGENTS, listSessions, readSession, readEvents as readSessionEvents, requestControl, removeSession, isActive, readLand, sessionDir, appendEvent } from '../src/sessions.mjs'
 import { addAccount, removeAccount, listAccountRows, LAYOUT } from '../src/accounts.mjs'
 import { listUsage, fmtReset } from '../src/usage.mjs'
 import { home } from '../src/store.mjs'
@@ -88,7 +88,12 @@ function simulateLimit(s) {
     appendEvent(s.session_id, { type: 'status', summary: 'simulated RESOURCE_EXHAUSTED appended to the session log' })
     return out(`simulated: RESOURCE_EXHAUSTED appended to ${join(sessionDir(s.session_id), 'agy.log')}; the runner reads it within ${process.env.BATON_ATTACH_POLL_MS || 2000} ms and hands off to ${s.chain?.[0]?.agent ?? 'nothing'}`)
   }
-  die(2, `simulate-limit drives the claude hook path (and the agy log); codex's wall comes from its own rollout file, which Baton never writes. Use "leg sessions handoff ${s.session_id}" to force the switch.`)
+  if (s.agent === 'grok') {
+    appendFileSync(join(sessionDir(s.session_id), 'grok.log'), "\nRate limited (429): You've hit the rate limit for your plan. Try again later. (simulated by leg sessions simulate-limit)\n")
+    appendEvent(s.session_id, { type: 'status', summary: 'simulated rate limit appended to the grok log' })
+    return out(`simulated: rate limit appended to ${join(sessionDir(s.session_id), 'grok.log')}; the runner reads it within ${process.env.BATON_ATTACH_POLL_MS || 2000} ms and hands off to ${s.chain?.[0]?.agent ?? 'nothing'}`)
+  }
+  die(2, `simulate-limit drives the claude hook path (and the agy/grok log); codex's wall comes from its own rollout file, which Baton never writes. Use "leg sessions handoff ${s.session_id}" to force the switch.`)
 }
 
 function fmtCard(c) {
@@ -97,34 +102,49 @@ function fmtCard(c) {
   return `${c.card_id}  [${c.status}]  ${c.station}${leg}  leases=${(c.leases?.length ? c.leases : ['**']).join(',')}  ${String(c.title ?? c.task).slice(0, 60)}`
 }
 
-const TERMS = `Terms check (fetched 2026-09-11): Anthropic Consumer Terms forbid sharing account credentials and "bypassing any of our systems or protective measures"; the Anthropic Usage Policy forbids coordinating across multiple accounts to circumvent product guardrails; OpenAI's Terms of Use forbid sharing credentials and "circumvent any rate limits or restrictions". Two paid logins you own are not banned by name, but rotating to a second account of the same vendor because the first is rate-limited is close to that wording. Leg's default chain switches vendors (claude -> codex -> agy); a second account of one vendor is your call.`
+const TERMS = `Terms check (fetched 2026-09-11): Anthropic Consumer Terms forbid sharing account credentials and "bypassing any of our systems or protective measures"; the Anthropic Usage Policy forbids coordinating across multiple accounts to circumvent product guardrails; OpenAI's Terms of Use forbid sharing credentials and "circumvent any rate limits or restrictions". Two paid logins you own are not banned by name, but rotating to a second account of the same vendor because the first is rate-limited is close to that wording. Leg's default chain switches vendors (claude -> codex -> agy -> grok); a second account of one vendor is your call.`
 
 async function main() {
   const [group, cmd, ...rest] = process.argv.slice(2)
   const args = parseArgs(rest)
   if (group === '--version' || group === '-v') return out(VERSION)
   if (group === '🦿' || group === 'prosthetic' || group === 'easter-egg') {
-    out(' 🦿 LegCli — The mechanical relay runner for coding agents.')
-    out(`
-.--------.
-|  ____  |
-| |    | |
-| |____| |
-'--------'
-    ||
- .--||--.
- |  ||  |   knee servo
- '--||--'
-    ||
-    ||
- ___||___
-|________|
-`)
-    out('   Passing the leg to the next runner when limits hit.')
+    const ORANGE = '\x1b[38;5;208m'
+    const RESET = '\x1b[0m'
+    const LEG_ART = [
+      '         ███████',
+      '           ███████',
+      '             ███████',
+      '               ███████',
+      '                 ███████',
+      '                   ███████',
+      '                     ███████',
+      '                       ███████',
+      '                         ███████',
+      '                           ███████',
+      '                              ███████',
+      '                            ███████████',
+      '                           █████████████',
+      `                           ██████(${ORANGE}00${RESET})███  ← knee servo`,
+      '                           █████████████',
+      '                            ███████████',
+      '                              ███████',
+      '                             █████',
+      '                           █████',
+      '                         █████',
+      '                       █████',
+      '                     █████',
+      '                    █████',
+      '            ██████████████████████████',
+      '            ████ ████ ████ ████ ████ ████',
+    ].join('\n')
+    out('🦿 LegCli: the mechanical relay runner for coding agents.\n')
+    out(LEG_ART)
+    out('\nPassing the leg to the next runner when limits hit.')
     return
   }
-  if (AGENTS.includes(group)) {
-    // leg claude|codex|agy [agent args...]: everything after the agent name
+  if (SUPERVISED_AGENTS.includes(group)) {
+    // leg claude|codex|agy|grok [agent args...]: everything after the agent name
     // goes straight through.
     const code = await attach(group, [cmd, ...rest].filter((x) => x !== undefined), { open: process.env.BATON_NO_OPEN !== '1' })
     process.exit(code)
@@ -427,11 +447,12 @@ async function main() {
     out(openBoard(url) ? `opened ${url}` : `could not open a browser; visit ${url}`)
     return
   }
-  if (group && group !== '--help' && group !== 'help') die(2, `unknown command "${group}" (claude|codex|agy|sessions|resume|accounts|license|share|up|down|status|open|card|scheduler|uninstall)`)
+  if (group && group !== '--help' && group !== 'help') die(2, `unknown command "${group}" (claude|codex|agy|grok|sessions|resume|accounts|license|share|up|down|status|open|card|scheduler|uninstall)`)
   out(`leg ${VERSION}, your coding agents, with a board alongside and a handoff when one hits its limit
-  claude|codex|agy [args...]   the normal interactive agent in this terminal; args pass straight through
-                               the board opens once, the session shows as a card, usage is tracked, a limit hands off
-                               a second live session in one checkout gets its own worktree (--no-worktree to share)
+  claude|codex|agy|grok [args...]   the normal interactive agent in this terminal; args pass straight through
+                                the board opens once, the session shows as a card, usage is tracked, a limit hands off
+                                a second live session in one checkout gets its own worktree (--no-worktree to share)
+                                auto-approve mode (--no-auto-approve to opt out)
   sessions ls|show|events|handoff|end|rm|simulate-limit <id>
   resume [--check] [--json] [--path <dir>]      the hand-off waiting in this checkout, and whether it is still true
                                freshness is recomputed from git at read time; --check prints only the verdict

package/docs/adapters.md

@@ -1,7 +1,7 @@
 # Adapters
 
 Two things per agent: what Leg reads from an interactive session
-(`leg claude|codex|agy`), and the headless argv the v0.1 pipeline spawns.
+(`leg claude|codex|agy|grok`), and the headless argv the v0.1 pipeline spawns.
 Every fact here was written against `src/taps/*.mjs`, `src/attach.mjs` and
 `src/adapters/*.mjs`; the evidence trail, including which lines an artifact
 backs, is [cli-contracts.md](cli-contracts.md).
@@ -120,7 +120,7 @@ documentation say docs-only.
 - **The wall**: `RESOURCE_EXHAUSTED`, "it resets in %s" and "out of quota" in
   the log. Those strings are present in `agy.exe`, and `scanLog()` also reads a
   relative reset out of "resets in \<n>\<s|m|h|d>". Status:
-  **docs-only** <!-- live:agy/agy-resource-exhausted --> —
+  **observed-live 2026-09-16** <!-- live:agy/agy-resource-exhausted --> —
   `RESOURCE_EXHAUSTED (code 429): Individual quota reached … Resets in
   71h19m42s.` appeared in a session's `agy.log` at 08:02:42Z and walled the
   agent. No payload was kept: the capture call in `src/attach.mjs` was added
@@ -133,11 +133,25 @@ documentation say docs-only.
 - **One account only**: agy 1.2.0 has no config-directory override, so
   `leg accounts add agy …` is refused.
 
+### grok
+
+- **How Leg attaches**: `grok <your args>` with `--debug-file <~/.leg/sessions/<id>/grok.log>` passed by Leg (`src/attach.mjs` `spawnSpec`).
+- **Usage percentages**: `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits` and `GET https://cli-chat-proxy.grok.com/v1/user?include=subscription` (`LEG_GROK_BILLING_URL` and `LEG_GROK_USER_URL` override), reading the OAuth token stored in `~/.grok/auth.json`. The billing endpoint reports `creditUsagePercent` and `currentPeriod` (with weekly resets). Polled every 60 s (`LEG_USAGE_POLL_MS`). If the token expires or returns 401, usage is marked unknown without crashing, and re-reads `auth.json` on the next poll.
+- **The wall**: rate limit signals cited directly from `xai-org/grok-build`:
+  - `SamplingError::Api { status: StatusCode::TOO_MANY_REQUESTS }` (`crates/codegen/xai-grok-sampling-types/src/error.rs:304`)
+  - `RATE_LIMITED_ERROR_CODE = -32003` and user messages `RATE_LIMITED_USER_MESSAGE_OAUTH` ("You've hit the rate limit for your plan. Try again later.") and `RATE_LIMITED_USER_MESSAGE_API_KEY` ("You've hit the rate limit for your API key. Try again later.") (`crates/codegen/xai-grok-shell/src/sampling/error.rs:15, 18-21`)
+  - Headline "Rate limited (429)" and "You've hit the rate limit for your plan" (`crates/codegen/xai-grok-pager/src/app/error_display.rs:263-267`)
+  - `StopFailureKind::RateLimit` ("rate_limit") (`crates/codegen/xai-grok-hooks/src/event.rs:306-315`)
+  - Free usage exhausted: `FREE_USAGE_USER_MESSAGE` and `FREE_USAGE_EXHAUSTED_ERROR_CODE` ("subscription:free-usage-exhausted") (`crates/codegen/xai-grok-shell/src/sampling/error.rs:30, 33`)
+  `src/taps/grok.mjs` scans `grok.log` for these exact signals and extracts reset durations when available.
+- **Prompts and session id**: `~/.grok/sessions/<url-encoded-cwd>/prompt_history.jsonl`, recorded per prompt with timestamp, `session_id`, and `prompt`.
+- **Accounts**: Supports `GROK_HOME` override. `leg accounts add grok <name>` creates junctioned directories copying `config.toml`.
+
 ### Resume prompt per agent
 
 After a hand-off the next agent starts in the same terminal with the pointer
 prompt as its first positional argument: `claude "<prompt>"`,
-`codex "<prompt>"`, `agy -i "<prompt>"` (`src/attach.mjs` `spawnSpec`).
+`codex "<prompt>"`, `agy -i "<prompt>"`, `grok "<prompt>"` (`src/attach.mjs` `spawnSpec`).
 
 ## Headless adapters (the v0.1 pipeline)
 

package/docs/cli-contracts.md

@@ -191,7 +191,7 @@ stderr are 0 bytes, and codex's is the one stdin notice. observed-live.
 
 ## Interactive taps
 
-What `leg claude|codex|agy` reads while the real interactive CLI runs. Same
+What `leg claude|codex|agy|grok` reads while the real interactive CLI runs. Same
 tagging rule: `observed-live 2026-09-11` means the build machine did it;
 `docs-only` means the CLI's own source or documentation says so and Leg has
 not seen it happen. Machine: Claude Code 2.1.268, codex-cli 0.153.4, agy 1.2.0.
@@ -295,7 +295,7 @@ variable and `LEG_SESSION` (source: src/attach.mjs, src/env.mjs).
   "quota exhausted/exceeded" in the log, plus a relative reset parsed out of
   "resets in \<n>\<s|m|h|d>" (source: strings present in `agy.exe`;
   src/taps/agy.mjs `scanLog`).
-  **docs-only** <!-- live:agy/agy-resource-exhausted -->:
+  **observed-live 2026-09-16** <!-- live:agy/agy-resource-exhausted -->:
   `RESOURCE_EXHAUSTED (code 429): Individual quota reached … Resets in
   71h19m42s.` appeared in a session's `agy.log` at 08:02:42Z, `scanLog` read
   the relative reset, and the agent was walled. No payload was kept, the
@@ -310,6 +310,38 @@ variable and `LEG_SESSION` (source: src/attach.mjs, src/env.mjs).
   `LAYOUT.agy.env` is `null` and `accounts add agy` is refused (source:
   src/accounts.mjs).
 
+### grok tap
+
+- Attach: `grok <args> --debug-file <LEG_HOME>/sessions/<id>/grok.log` (source:
+  src/attach.mjs `spawnSpec`).
+- Usage: `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits` and
+  `GET https://cli-chat-proxy.grok.com/v1/user?include=subscription` with
+  `Authorization: Bearer <token>` read from `~/.grok/auth.json` (per-scope
+  key map or direct object). The billing endpoint reports `creditUsagePercent`
+  and `currentPeriod` (with weekly reset timestamp `end`). Polled every 60 s
+  (`LEG_USAGE_POLL_MS`). Token expiry and HTTP 401 are handled gracefully
+  without throwing, marking usage unknown until re-authenticated.
+  (source: src/taps/grok.mjs; probe against xAI proxy).
+- The wall: exact rate-limit signals cited from `xai-org/grok-build` (Rust):
+  - `SamplingError::Api { status: StatusCode::TOO_MANY_REQUESTS }`
+    (`crates/codegen/xai-grok-sampling-types/src/error.rs:304`)
+  - `RATE_LIMITED_ERROR_CODE = -32003` and messages
+    `RATE_LIMITED_USER_MESSAGE_OAUTH` ("You've hit the rate limit for your plan. Try again later.")
+    and `RATE_LIMITED_USER_MESSAGE_API_KEY` ("You've hit the rate limit for your API key. Try again later.")
+    (`crates/codegen/xai-grok-shell/src/sampling/error.rs:15, 18-21`)
+  - Headline "Rate limited (429)" and "You've hit the rate limit for your plan"
+    (`crates/codegen/xai-grok-pager/src/app/error_display.rs:263-267`)
+  - `StopFailureKind::RateLimit` ("rate_limit")
+    (`crates/codegen/xai-grok-hooks/src/event.rs:306-315`)
+  - Free usage exhausted: `FREE_USAGE_USER_MESSAGE` and `FREE_USAGE_EXHAUSTED_ERROR_CODE`
+    ("subscription:free-usage-exhausted")
+    (`crates/codegen/xai-grok-shell/src/sampling/error.rs:30, 33`)
+  `src/taps/grok.mjs` scans `grok.log` for these patterns and parses reset duration.
+- Prompts and session id: `~/.grok/sessions/<url-encoded-cwd>/prompt_history.jsonl`,
+  one `{ timestamp, session_id, prompt }` per entry (source: src/taps/grok.mjs `promptsSince`).
+- Accounts: `GROK_HOME` override supported; `leg accounts add grok <name>` creates
+  junctioned directories with copied `config.toml` (source: src/accounts.mjs).
+
 ### Usage store and the chooser
 
 - `<LEG_HOME>/usage/<agent>--<account>.json`:
@@ -361,7 +393,7 @@ non-zero exit → `failed`. Every outcome except `completed`, `auth_failed` and
 `killed` asks the chain to hand off.
 
 <!-- limits-table:start -->
-Generated by `node scripts/limits-table.mjs` from 21 fixtures (4 observed-live, 17 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Leg itself; `info` must never classify as a limit.
+Generated by `node scripts/limits-table.mjs` from 22 fixtures (4 observed-live, 18 docs-only). Classification `limit` hands the card to the next agent as a usage limit; `auth` is a failed launch (never a limit); `launch` is a failed launch that the next agent may still try; `budget` is a turn or spend cap set by Baton itself; `info` must never classify as a limit.
 
 | id | adapter | class | where | source | text (excerpt) | produced by |
 |----|---------|-------|-------|--------|----------------|-------------|
@@ -383,6 +415,7 @@ Generated by `node scripts/limits-table.mjs` from 21 fixtures (4 observed-live,
 | generic-resource-exhausted | * | limit | any | **docs-only** | RESOURCE_EXHAUSTED | generic matcher (gRPC RESOURCE_EXHAUSTED); lowest priority |
 | generic-usage-limit | * | limit | any | **docs-only** | usage limit | generic matcher; lowest priority |
 | grok-not-logged-in | grok | auth | stderr | **observed-live** | To sign in, open this URL in your browser:    https://accounts.x.ai/oauth2/device?user_cod | fixtures/live/grok/err.log from scripts/probe.mjs --adapter grok, 2026-09-10 (stdout JSON stopReason: Cancelled, exit 0) |
+| grok-rate-limit | grok | limit | any | **docs-only** | You've hit the rate limit for your plan. Try again later. | crates/codegen/xai-grok-shell/src/sampling/error.rs:18 (RATE_LIMITED_USER_MESSAGE_OAUTH: "You've hit the rate limit for your plan. Try again later.") |
 | auth-source-set | * | auth | stderr | **docs-only** | another auth source is set | project brief (Wes, 2026-09-10): stderr saying "another auth source is set" counts as a failed launch; wording not yet observed live |
 | compile-error | * | info | stderr | **docs-only** | SyntaxError: Unexpected token )     at compileSourceTextModule (node:internal/modules/esm/ | synthetic negative fixture (a crashed agent is not a limit) |
 | empty-stdout-exit-0 | * | info | stdout | **observed-live** |  | fixtures/live/grok (exit 0, no work): silence is not a limit |

package/docs/configuration.md

@@ -20,11 +20,13 @@ variables yourself in that case.
 
 ## Interactive sessions
 
-These apply to `leg claude|codex|agy`.
+These apply to `leg claude|codex|agy|grok`.
 
 | variable | default | meaning | read in |
 |----------|---------|---------|---------|
 | `LEG_ACCOUNT` | `default` | start the session on a named login instead of the CLI's own home | `src/attach.mjs` |
+| `LEG_AUTO_APPROVE` | `1` | launch interactive agents in auto-approve mode (set to `0`, `false`, or `off` to disable) | `src/preferences.mjs` |
+| `LEG_NO_AUTO_APPROVE` | (unset) | set to `1` to opt out of auto-approve mode | `src/preferences.mjs` |
 | `LEG_WARN_PCT` | `85` | the percentage of either usage window that turns the card amber, records a `warning` event and rings the terminal bell once | `src/usage.mjs` |
 | `LEG_NO_HANDOFF` | (unset, hand-off on) | set to `1` to warn and record but never switch agents | `src/attach.mjs` |
 | `LEG_NO_OPEN` | (unset, opens once) | set to `1` to start the board without opening a browser | `bin/leg.mjs` |
@@ -45,6 +47,23 @@ record under `$LEG_HOME/sessions/`.
 `CLAUDE_CONFIG_DIR` and `CODEX_HOME` are set for the child when the session
 runs on a named account; see [Accounts](#accounts) below.
 
+### Auto-approve launch mode
+
+By default, Leg starts interactive sessions (`leg claude`, `leg codex`, `leg agy`, and `leg grok`) in permissive auto-approve mode so you never sit through repetitive tool permission prompts:
+
+- Claude: `--dangerously-skip-permissions`
+- Codex: `--ask-for-approval never`
+- agy: `--dangerously-skip-permissions`
+- Grok: `--always-approve`
+
+These flags are injected at spawn time and only affect sessions launched through Leg. Your global CLI configurations (`~/.claude.json`, `~/.codex/config.toml`, `~/.gemini/settings.json`) remain untouched.
+
+To opt out and keep standard approval prompts:
+
+1. CLI flag: pass `--no-auto-approve` when starting a session (e.g. `leg claude --no-auto-approve`).
+2. Environment variable: set `LEG_AUTO_APPROVE=0` or `LEG_NO_AUTO_APPROVE=1` (or legacy `BATON_AUTO_APPROVE=0` / `BATON_NO_AUTO_APPROVE=1`).
+3. Persistent preference: set `"auto_approve": false` in `~/.leg/preferences.json`.
+
 ## Core
 
 | variable | default | meaning | read in |

package/docs/getting-started.md

@@ -10,9 +10,9 @@ it. The v0.1 pipeline flow is section 7 onward.
 - git.
 - Python 3 with pip, for the `context-handoff-bundle` CLI. This is what writes
   and reads the handoff bundles.
-- At least one coding-agent CLI, logged in: `claude`, `codex` or `agy`. You do
-  not need all three. With one installed you get the board and the usage
-  tracking; with two or more you also get the hand-off.
+- At least one coding-agent CLI, logged in: `claude`, `codex`, `agy` or
+  `grok`. You do not need all four. With one installed you get the board
+  and the usage tracking; with two or more you also get the hand-off.
 
 ## 2. Install
 

package/fixtures/limits/grok/grok-rate-limit.json

@@ -0,0 +1,11 @@
+{
+  "id": "grok-rate-limit",
+  "adapter": "grok",
+  "source": "docs-only",
+  "produced_by": "crates/codegen/xai-grok-shell/src/sampling/error.rs:18 (RATE_LIMITED_USER_MESSAGE_OAUTH: \"You've hit the rate limit for your plan. Try again later.\")",
+  "where": "any",
+  "text": "You've hit the rate limit for your plan. Try again later.",
+  "pattern": "You've hit the rate limit for your plan|You've hit the rate limit for your API key|Rate limited \\(429\\)|subscription:free-usage-exhausted|You've used all of your free queries",
+  "exit_code": null,
+  "classification": "limit"
+}

package/fixtures/live/agy/limit-agy-resource-exhausted.json

@@ -0,0 +1,11 @@
+{
+  "agent": "agy",
+  "signal": "agy-resource-exhausted",
+  "captured_at": "2026-09-16T07:17:41.481Z",
+  "session_id": "s-20260916-065617-agy-ef0c",
+  "source": "observed-live",
+  "payload": {
+    "log_excerpt": "invalid syntax I0916 03:17:39.470463 43949 run.go:389] Run: attempt 1 failed (RESOURCE_EXHAUSTED (code 429): Individual quota reached. Please upgrade your subscription to increase your limits. Resets in 2h35m6s.), retrying in 4s",
+    "resets_at": 1789552367
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ucsandman/legcli",
-  "version": "0.7.0",
-  "description": "Claude Code and Codex usage limit monitor with an automatic handoff. Type leg claude|codex|agy and get the same interactive agent with a board alongside, usage tracking per agent and account, a live context handoff bundle, and at the limit the next agent continuing in the same terminal. $79 once, 30-day money-back guarantee.",
+  "version": "0.8.0",
+  "description": "Usage-limit monitor and automatic handoff for Claude Code, Codex, agy and Grok. Type leg claude|codex|agy|grok and get the same interactive agent with a board alongside, auto-approve on by default, usage tracking per agent and account, a live context handoff bundle, and at the limit the next agent continuing in the same terminal. $79 once, 30-day money-back guarantee.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://legcli.com",
@@ -50,7 +50,7 @@
   },
   "scripts": {
     "start": "node --env-file-if-exists=.env bin/leg.mjs up",
-    "test": "node --test --test-concurrency=1 && node scripts/privacy-check.mjs && node scripts/check-claims.mjs",
+    "test": "node --test --test-concurrency=4 && node scripts/privacy-check.mjs && node scripts/check-claims.mjs",
     "lint": "eslint .",
     "privacy": "node scripts/privacy-check.mjs",
     "claims": "node scripts/check-claims.mjs",

package/scripts/build-docs-site.mjs

@@ -185,12 +185,13 @@ function page ({ slug, title, description, body, headings }) {
 <meta property="og:url" content="${url}">
 <meta property="og:site_name" content="LegCli">
 <meta property="og:title" content="${escapeHtml(title)}">
-<meta property="og:description" content="${escapeHtml(description)}">
-<meta property="og:image" content="${ORIGIN}/og.png?v=2">
+<meta property="og:image" content="${ORIGIN}/og.png?v=3">
+<meta property="og:image:secure_url" content="${ORIGIN}/og.png?v=3">
+<meta property="og:image:type" content="image/png">
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:title" content="${escapeHtml(title)}">
 <meta name="twitter:description" content="${escapeHtml(description)}">
-<meta name="twitter:image" content="${ORIGIN}/og.png?v=2">
+<meta name="twitter:image" content="${ORIGIN}/og.png?v=3">
 <link rel="preload" href="/fonts/atkinson-hyperlegible-next-var.woff2" as="font" type="font/woff2" crossorigin>
 <link rel="preload" href="/fonts/azeret-mono-var.woff2" as="font" type="font/woff2" crossorigin>
 <link rel="stylesheet" href="/style.css">

package/src/accounts.mjs

@@ -31,6 +31,13 @@ export const LAYOUT = {
     login: (dir) => `$env:CODEX_HOME='${dir}'; codex login`,
   },
   agy: { env: null, home: () => join(homedir(), '.gemini', 'antigravity-cli'), share: [], copy: [], login: null },
+  grok: {
+    env: 'GROK_HOME',
+    home: () => process.env.GROK_HOME || join(homedir(), '.grok'),
+    share: ['installed-plugins', 'skills', 'workflows'],
+    copy: ['config.toml'],
+    login: (dir) => `$env:GROK_HOME='${dir}'; grok login`,
+  },
 }
 
 export function accountsFile() { return join(home(), 'accounts.json') }
@@ -42,6 +49,7 @@ export function readAccounts() {
   try {
     const j = JSON.parse(readFileSync(accountsFile(), 'utf8'))
     for (const k of Object.keys(base)) if (Array.isArray(j[k])) base[k] = ['default', ...j[k].filter((n) => n !== 'default')]
+    if (Array.isArray(j?.grok)) base.grok = ['default', ...j.grok.filter((n) => n !== 'default')]
   } catch {}
   return base
 }
@@ -69,7 +77,7 @@ function junction(target, link) {
 export function addAccount(agent, name) {
   if (!/^[a-z0-9][a-z0-9_-]{0,29}$/i.test(name) || name === 'default') throw new Error(`invalid account name "${name}" (letters, digits, - and _; not "default")`)
   const l = LAYOUT[agent]
-  if (!l) throw new Error(`unknown agent "${agent}" (claude|codex|agy)`)
+  if (!l) throw new Error(`unknown agent "${agent}" (claude|codex|agy|grok)`)
   if (!l.env) throw new Error(`${agent} has no config-dir override in the installed version; extra accounts are not possible`)
   const dir = accountDir(agent, name)
   mkdirSync(dir, { recursive: true })
@@ -78,6 +86,7 @@ export function addAccount(agent, name) {
   for (const d of l.share) if (junction(join(src, d), join(dir, d))) shared.push(d)
   refreshAccount(agent, name)
   const acc = readAccounts()
+  if (!acc[agent]) acc[agent] = ['default']
   if (!acc[agent].includes(name)) { acc[agent].push(name); writeAccounts(acc) }
   return { dir, shared, login: l.login(dir), env: l.env }
 }

package/src/adapters/grok.mjs

@@ -1,8 +1,5 @@
-// grok adapter — Grok CLI headless (`grok -p <prompt> --output-format json`).
-// NOT REGISTERED in index.mjs: the phase-3 probe could not verify it because
-// the build machine had no grok login (device-code prompt, exit "Cancelled").
-// Built from `grok --help` only; see docs/cli-contracts.md § grok. Register it
-// after `grok` is logged in and `node scripts/probe.mjs --adapter grok` passes.
+// grok adapter - Grok CLI headless (`grok -p <prompt> --output-format json`).
+// Registered in index.mjs alongside claude, codex, and agy.
 import { join } from 'node:path'
 import { homedir } from 'node:os'
 import { sanitizeEnv } from '../env.mjs'
@@ -38,8 +35,8 @@ const adapter = {
         const j = JSON.parse(s.slice(i))
         return {
           session_id: j.session_id ?? j.sessionId ?? null,
-          last_message: typeof j.response === 'string' ? j.response : (typeof j.result === 'string' ? j.result : null),
-          stop_reason: j.stop_reason ?? null,
+          last_message: typeof j.response === 'string' ? j.response : (typeof j.result === 'string' ? j.result : (typeof j.text === 'string' ? j.text : null)),
+          stop_reason: j.stop_reason ?? j.stopReason ?? null,
           raw: j,
         }
       } catch { continue }