Add first-class Grok setup support alongside Claude and Codex

AGENTS.md

@@ -1,30 +1,32 @@
 # AGENTS.md
 
-Guidance for Codex (and humans) working in this repo.
+Guidance for Codex, Grok, and humans working in this repo.
 
 ## What this repo is
 
 A small collection of shell scripts and an installer that set up a comfortable
-Claude Code and/or Codex working environment on a fresh Linux machine: a tmux
-login session picker, agent status information, tmux copy/scrollback config,
+Claude Code, Codex, and/or Grok working environment on a fresh Linux machine: a
+tmux login session picker, agent status information, tmux copy/scrollback config,
 and 1Password-backed SSH key login. There is no build system.
 
 ## Layout
 
 - `scripts/` contains canonical files installed into `$HOME`. Edit these, not
   installed copies.
-- `setup.sh` is the interactive, idempotent installer.
+- `setup.sh` is the interactive, idempotent installer
+  (`--codex` / `--claude` / `--grok` / `--both` / `--all`).
 - `scripts/statusline.sh` is Claude Code-specific. Codex uses its native
-  `tui.status_line` setting instead.
+  `tui.status_line` setting; Grok uses its built-in TUI status.
 - `prompts/machine-setup.md` is the self-contained Claude Code setup prompt.
 - `prompts/codex-machine-setup.md` is the Codex setup prompt.
+- `prompts/grok-machine-setup.md` is the Grok setup prompt.
 
 ## Conventions
 
 - `scripts/tmux-login.sh` is POSIX sh. Verify it with `sh -n`.
 - `scripts/statusline.sh` and `setup.sh` are Bash. Verify them with `bash -n`.
 - Keep `CLAUDE.md` and `AGENTS.md` aligned when shared repository guidance
-  changes.
+  changes. Grok loads both automatically.
 - Keep edits small, readable, and idempotent.
 
 ## Safety
@@ -34,6 +36,21 @@ authentication automatically. Preserve the interactive, SSH, tmux, and
 terminfo guards in `scripts/profile-snippet.sh`. After login-flow changes, test
 from a second SSH session while keeping the first session open.
 
+## Multi-agent handoffs
+
+When handing work between Claude, Codex, and Grok, write `handoff/<task>.md`:
+
+1. Goal (one sentence)
+2. Exact file list in scope
+3. Worked example if the change is mechanical
+4. Acceptance command(s) (e.g. `./tests/test.sh`)
+5. Explicit DO-NOT-TOUCH: `profile-snippet.sh`, login-path semantics of
+   `tmux-login.sh`, the `infocmp` guard, anything that disables SSH password auth
+
+Never hand off SSH login-path or installer safety semantics without human review.
+Grok can resume recent Claude/Codex sessions via its `resume-claude` /
+`resume-codex` skills.
+
 ## Testing
 
 ```bash

CLAUDE.md

@@ -5,21 +5,23 @@ Guidance for Claude Code (and humans) working in this repo.
 ## What this repo is
 
 A small collection of shell scripts + an installer that set up a standard Claude
-Code and/or Codex working environment on a fresh Linux machine: a tmux login
-session picker, agent status information, tmux copy/scrollback config, and
+Code, Codex, and/or Grok working environment on a fresh Linux machine: a tmux
+login session picker, agent status information, tmux copy/scrollback config, and
 1Password-backed SSH key login. No build system.
 
 ## Layout
 
 - `scripts/` — the canonical files that get installed to `$HOME`. **Edit these**,
   not copies. `setup.sh` installs from here, so there is one source of truth.
-- `setup.sh` — interactive installer. Reads from `scripts/`; does not embed copies.
+- `setup.sh` — interactive installer (`--codex` / `--claude` / `--grok` /
+  `--both` / `--all`). Reads from `scripts/`; does not embed copies.
 - `prompts/machine-setup.md` — the setup written as a Claude Code prompt. It
   **does** embed the script bodies (so it's self-contained when pasted into a
   fresh machine). If you change a script in `scripts/`, update the embedded copy
   in this prompt to match.
-- `AGENTS.md` — the equivalent repository guidance Codex loads automatically.
+- `AGENTS.md` — the equivalent repository guidance Codex (and Grok) load.
 - `prompts/codex-machine-setup.md` — a Codex-native setup prompt.
+- `prompts/grok-machine-setup.md` — a Grok-native setup prompt.
 
 ## Conventions
 
@@ -30,6 +32,7 @@ session picker, agent status information, tmux copy/scrollback config, and
   Verify with `bash -n`. It must always `exit 0` and tolerate empty/garbage stdin.
 - The statusline reads all JSON fields in **one** `jq` call (perf: it runs on
   every render). Keep it that way — don't reintroduce per-field `jq` calls.
+- Keep `CLAUDE.md` and `AGENTS.md` aligned when shared guidance changes.
 - Keep edits small and readable; match the surrounding comment density.
 
 ## Safety (important)
@@ -44,6 +47,13 @@ These scripts run in the SSH login path. A bug can lock someone out of a machine
   resolvable `$TERM` via `infocmp`). The `infocmp` check is what prevents an
   unknown terminal from exec'ing a tmux that instantly dies and strands the login.
 
+## Multi-agent handoffs
+
+When handing work to Codex or Grok, write `handoff/<task>.md` with: goal, exact
+file list, worked example if mechanical, acceptance command(s), and DO-NOT-TOUCH
+(login path, `infocmp`, password auth). Never hand off SSH login-path or installer
+safety semantics without human review. See `AGENTS.md` for the same protocol.
+
 ## Testing
 
 ```bash

README.md

@@ -1,14 +1,15 @@
 # coding-agent-machine-setup
 
 Turn a fresh Linux box (VM, LXC container, server) into a comfortable
-[Codex](https://developers.openai.com/codex/) and/or
-[Claude Code](https://claude.com/claude-code) working environment in one go:
+[Codex](https://developers.openai.com/codex/),
+[Claude Code](https://claude.com/claude-code), and/or
+[Grok Build](https://x.ai/cli) working environment in one go:
 
 - 🔑 **SSH key login via 1Password** — key lives in the 1Password SSH agent, unlocked by Touch ID / your vault, never on disk.
 - 🪟 **tmux + an interactive login session picker** — every SSH login lands on a menu: attach an existing session, jump straight into a project, start a new named session, or drop to a plain shell.
 - 🖱 **tmux copy / scrollback / history tuning** — mouse selection + wheel scrollback, 50k-line history.
-- 📊 **Agent-native status information** — Codex gets a native footer with directory, Git branch, model/reasoning, and context remaining; Claude Code keeps the custom two-line statusline with rate-limit meters.
-- 🧭 **Native instruction files** — `AGENTS.md` for Codex and `CLAUDE.md` for Claude Code carry equivalent repository guidance.
+- 📊 **Agent-native status information** — Codex gets a native footer with directory, Git branch, model/reasoning, and context remaining; Claude Code keeps the custom two-line statusline with rate-limit meters; Grok uses its built-in TUI status.
+- 🧭 **Native instruction files** — `AGENTS.md` (Codex + Grok) and `CLAUDE.md` (Claude Code; Grok loads both) carry equivalent repository guidance.
 
 It's all small, readable shell — no frameworks, no daemons.
 
@@ -46,11 +47,13 @@ Choose a specific agent when desired:
 ```bash
 ./setup.sh --codex
 ./setup.sh --claude
-./setup.sh --both
+./setup.sh --grok
+./setup.sh --both    # Claude + Codex
+./setup.sh --all     # Claude + Codex + Grok
 ```
 
-With no flag, the installer detects installed agents; if neither is present it
-defaults to Codex setup.
+With no flag, the installer detects installed agents and configures those present;
+if none are present it defaults to Codex setup.
 
 The installer is interactive and conservative: it shows what it changes, skips
 anything already done, asks before installing packages, and **never disables SSH
@@ -60,8 +63,8 @@ password auth for you** (do that yourself once key login is confirmed). It will:
 2. Optionally add a public key to `~/.ssh/authorized_keys` (and print the laptop-side 1Password steps).
 3. Write `~/.tmux-login.sh` with the projects you enter, and wire the guarded hook into `~/.profile`.
 4. Install `~/.tmux.conf` (or merge in the mouse + history settings).
-5. Configure Codex's native footer in `~/.codex/config.toml`, install Claude's
-   custom statusline, or both, according to the selected mode.
+5. Per selected mode: configure Codex's native footer, install Claude's custom
+   statusline, and/or ensure Grok's `~/.grok/bin` is on PATH.
 
 > **Test from a second SSH session.** Because this touches the login path, open a
 > new terminal and confirm everything works **while keeping your current session
@@ -74,8 +77,29 @@ password auth for you** (do that yourself once key login is confirmed). It will:
 interactively, asks before risky actions, and is handy when a machine's quirks
 need judgment the installer doesn't have.
 
-For Codex, use `prompts/codex-machine-setup.md`. Codex also reads this
-repository's `AGENTS.md` automatically.
+| Agent | Setup prompt | Instruction file |
+|-------|--------------|------------------|
+| Claude Code | `prompts/machine-setup.md` | `CLAUDE.md` |
+| Codex | `prompts/codex-machine-setup.md` | `AGENTS.md` |
+| Grok Build | `prompts/grok-machine-setup.md` | `AGENTS.md` + `CLAUDE.md` |
+
+## Working with multiple agents
+
+Shared shell environment (tmux picker, scrollback, SSH) is agent-agnostic. Project
+rules live in `AGENTS.md` / `CLAUDE.md` — keep them aligned. Grok also picks up
+Claude Code skills and MCP config via harness compatibility by default.
+
+Rough strengths (not hard rules):
+
+| Agent | Good fit |
+|-------|----------|
+| **Claude** | Judgment calls, SSH login-path safety, installer design, ambiguous UX |
+| **Codex** | Bulk mechanical edits with machine-checkable acceptance (`sh -n`, `./tests/test.sh`) |
+| **Grok** | Parallel explore/subagents, cost-efficient sweeps, web/research; `resume-claude` / `resume-codex` skills |
+
+Cross-agent handoffs: write `handoff/<task>.md` with goal, exact file list, acceptance
+command(s), and an explicit DO-NOT-TOUCH list (login path, `infocmp` guard, password auth).
+Never hand off SSH login-path or installer safety semantics without human review.
 
 ## What goes where
 
@@ -86,9 +110,11 @@ repository's `AGENTS.md` automatically.
 | `scripts/tmux.conf`        | `~/.tmux.conf`            | Mouse, 50k scrollback, copy-mode notes. |
 | `scripts/statusline.sh`    | `~/.claude/statusline.sh` | The Claude Code statusline (bash). |
 | native Codex configuration | `~/.codex/config.toml` | Codex footer; no wrapper script required. |
+| Grok PATH block | `~/.bashrc` | Ensures `~/.grok/bin` is on PATH (idempotent). |
 | `setup.sh`                 | —                         | Interactive installer that wires it all up. |
 | `prompts/machine-setup.md` | —                         | The "let Claude set it up" prompt. |
 | `prompts/codex-machine-setup.md` | —                    | The equivalent Codex setup prompt. |
+| `prompts/grok-machine-setup.md` | —                     | The equivalent Grok setup prompt. |
 
 ## Customizing
 
@@ -101,6 +127,8 @@ repository's `AGENTS.md` automatically.
 - **Codex footer:** edit `tui.status_line` in `~/.codex/config.toml`. Run
   `/status` for full session configuration and `/model` to change model or
   reasoning effort.
+- **Grok:** edit `~/.grok/config.toml` for UI/model defaults. Auth with
+  `grok login` or `grok login --device-auth` on headless SSH hosts.
 - **tmux clipboard / vi keys:** uncomment the optional lines at the bottom of
   `~/.tmux.conf`, then `tmux source-file ~/.tmux.conf`.
 
@@ -114,6 +142,8 @@ repository's `AGENTS.md` automatically.
   sure the file your shell sources pulls in the snippet.
 - **Unknown `$TERM`:** the login hook skips the picker (rather than stranding you)
   if your `$TERM` isn't in the server's terminfo db, and prints how to install it.
+- **Agent binaries are never auto-installed** — the installer prints official
+  install URLs for missing agents and continues with configuration only.
 
 ## License
 

prompts/grok-machine-setup.md

@@ -0,0 +1,26 @@
+# Set up this Linux machine for Grok Build
+
+Help me turn this Linux machine into a comfortable Grok Build CLI environment.
+Clone this repository if it is not already present, inspect the current machine
+without overwriting existing configuration, and run:
+
+```bash
+./setup.sh --grok
+```
+
+Work interactively and preserve these rules:
+
+- Never disable SSH password authentication.
+- Before changing the SSH login path, show what will change.
+- Keep the current SSH connection open and test from a second connection.
+- Preserve existing tmux and Grok configuration.
+- If Grok is absent, offer the official installer
+  (`curl -fsSL https://x.ai/cli/install.sh | bash`) and ask before running it.
+- After setup, verify `grok --version`. On headless SSH hosts prefer
+  `grok login --device-auth`; otherwise `grok login` is fine.
+- Confirm that Grok loads this repository's `AGENTS.md` and/or `CLAUDE.md`.
+
+The installer ensures `~/.grok/bin` is on PATH. Grok uses a built-in TUI status
+(no external statusline script) and already reads Claude Code skills/MCP via
+harness compatibility. Do not install the Claude Code statusline for a
+Grok-only setup.