grok-dev 1.1.0 → 1.1.1

package/.claude/worktrees/vigilant-johnson/.cursor/hooks/state/continual-learning.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "lastRunAtMs": 0,
+  "turnsSinceLastRun": 4,
+  "lastTranscriptMtimeMs": null,
+  "lastProcessedGenerationId": "518874b0-1435-472e-9c42-c54214a9ae4e",
+  "trialStartedAtMs": null
+}

package/.claude/worktrees/vigilant-johnson/.cursor/rules/development-workflow.mdc

@@ -0,0 +1,66 @@
+---
+description: Development workflow and common commands
+globs: "**/*"
+alwaysApply: true
+---
+
+# Development Workflow
+
+## Prerequisites
+
+- Bun 1.0+ (required)
+
+## Common Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Development (runs from source with Bun)
+bun run dev
+
+# Build (compile TypeScript to dist/)
+bun run build
+
+# Type checking (no emit)
+bun run typecheck
+
+# Linting
+bun run lint
+
+# Format (check / write)
+bun run format
+bun run format:fix
+
+# Run the built CLI
+bun run start
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----|----|----|
+| `GROK_API_KEY` | Yes | API key for xAI Grok |
+| `GROK_BASE_URL` | No | Custom API endpoint (default: `https://api.x.ai/v1`) |
+| `GROK_MODEL` | No | Model override (default: `grok-4-1-fast`) |
+| `GROK_MAX_TOKENS` | No | Max tokens per response (default: 16384) |
+
+Copy `.env.example` to `.env` and fill in your values.
+
+## Git hooks
+
+After `bun install`, **Husky** installs a **pre-commit** hook that runs **`lint-staged`**: Biome **format + lint** (`check --write`) on staged `*.{ts,tsx,js,mjs,cjs,json}` files. Fixes are written to disk and re-staged automatically when possible.
+
+## Before Submitting Changes
+
+1. Run `bun run typecheck` — CI enforces this on every PR.
+2. Run `bun run lint` — fix any Biome issues (or let pre-commit apply safe fixes).
+3. Ensure no secrets or `.env` files are committed.
+4. Follow the PR template in `.github/pull_request_template.md`.
+
+## Project Structure Conventions
+
+- Source code lives in `src/`, compiled output in `dist/` (gitignored).
+- The CLI entry point is `src/index.ts` which uses Commander.js for argument parsing.
+- UI is built with OpenTUI React (`@opentui/react`).
+- Only tool is bash — all file operations happen through shell commands.

package/.claude/worktrees/vigilant-johnson/.cursor/rules/project-overview.mdc

@@ -0,0 +1,66 @@
+---
+description: Project overview and architecture reference
+globs: "**/*"
+alwaysApply: true
+---
+
+# Grok CLI — Project Overview
+
+Grok CLI (`@vibe-kit/grok-cli`) is an open-source AI coding agent powered by Grok that brings AI assistance directly into the terminal.
+
+## Tech Stack
+
+- **Language**: TypeScript (ES2022, ESNext modules)
+- **Runtime**: Bun (primary)
+- **UI Framework**: React with [OpenTUI](https://github.com/anomalyco/opentui) for terminal rendering
+- **Build**: `tsc` (TypeScript compiler)
+- **Package Manager**: Bun
+- **API Client**: OpenAI SDK (for OpenAI-compatible xAI API)
+- **Tools**: Bash-only (all file operations via shell commands)
+- **Search**: X Search API + Web Search via xAI Responses API
+
+## Architecture
+
+```
+src/
+├── index.ts          # CLI entry point (Commander.js + OpenTUI)
+├── agent/
+│   └── agent.ts      # Agent — orchestrates client, bash tool, search
+├── grok/
+│   ├── client.ts     # Grok API client (Chat Completions + Responses API)
+│   ├── models.ts     # Model definitions and metadata
+│   └── tools.ts      # Tool schemas (bash, search_web, search_x)
+├── tools/
+│   └── bash.ts       # Bash command execution
+├── ui/
+│   └── app.tsx       # OpenTUI React terminal UI
+├── utils/
+│   ├── settings.ts   # User and project settings
+│   ├── git-root.ts   # Resolve git repository root for AGENTS.md discovery
+│   └── instructions.ts # AGENTS.md (ecosystem) custom instructions
+└── types/
+    └── index.ts      # Shared TypeScript types
+```
+
+## Key Patterns
+
+- **Agent loop**: `Agent.processMessage()` is an async generator that yields `StreamChunk` objects — the LLM responds, tools execute, results feed back until no more tool calls remain.
+- **Bash-only tools**: The agent uses bash for everything (file editing, searching, git, builds, etc.).
+- **X Search & Web Search**: Integrated via the xAI Responses API for real-time information.
+- **Settings hierarchy**: Environment variables → User-level (`~/.grok/user-settings.json`) → Project-level (`.grok/settings.json`).
+- **Custom instructions**: `~/.grok/AGENTS.md`, then `AGENTS.override.md` / `AGENTS.md` per directory from git root through the workspace cwd (Codex-style merge).
+- **ESM only**: The project uses `"type": "module"` — all imports use `.js` extensions for compiled output.
+
+## Latest Grok Models
+
+- grok-4-0709 (flagship reasoning)
+- grok-4.20-beta-0309 (multi-agent, 2M context)
+- grok-4-fast (fast reasoning, 2M context)
+- grok-4-1-fast (latest fast, 2M context)
+- grok-code-fast-1 (code optimized)
+- grok-3, grok-3-mini
+
+## CI/CD
+
+- **typecheck.yml**: Runs `tsc --noEmit` on push/PR to `main`/`develop`.
+- **security.yml**: Runs `npm audit` and TruffleHog secret scanning.

package/.claude/worktrees/vigilant-johnson/.cursor/rules/react-ink-components.mdc

@@ -0,0 +1,45 @@
+---
+description: Guidelines for React components using Ink for terminal UI
+globs: "src/ui/**/*.tsx,src/hooks/**/*.ts"
+alwaysApply: false
+---
+
+# React + Ink Terminal UI
+
+## Framework
+
+This project uses [Ink](https://github.com/vadimdemedes/ink) v4 to render React components in the terminal. Ink provides `<Box>`, `<Text>`, and other primitives instead of HTML elements.
+
+## Component Patterns
+
+- Use **functional components** with hooks — no class components.
+- JSX is compiled with `"jsx": "react"` (classic transform), so `import React from "react"` is required in every `.tsx` file.
+- Components are in `src/ui/components/` and follow kebab-case naming (`chat-interface.tsx`, `diff-renderer.tsx`).
+
+## Key Components
+
+| Component | Purpose |
+|-----------|---------|
+| `ChatInterface` | Main chat loop, orchestrates agent interaction |
+| `ChatHistory` | Renders conversation entries |
+| `ChatInput` | User text input with key bindings |
+| `DiffRenderer` | Displays file diffs |
+| `ModelSelection` | Model picker UI |
+| `LoadingSpinner` | Animated loading indicator |
+| `ConfirmationDialog` | User confirmation prompts for tool operations |
+| `McpStatus` | MCP server connection status |
+| `CommandSuggestions` | Autocomplete suggestions |
+| `ApiKeyInput` | API key entry prompt |
+
+## Ink-Specific Guidelines
+
+- Use `<Box>` for layout (flexbox model) and `<Text>` for styled text.
+- Use Ink's `useInput` hook for keyboard handling.
+- Use `chalk` for color utilities in `src/ui/utils/colors.ts`.
+- Markdown rendering for chat output uses `marked` + `marked-terminal`.
+- The app is rendered via `render(React.createElement(ChatInterface, { agent, initialMessage }))` in the entry point.
+
+## Hooks
+
+- Custom hooks live in `src/hooks/`.
+- Follow the `use` prefix convention (`useInput`, `useChat`, etc.).

package/.claude/worktrees/vigilant-johnson/.cursor/rules/tools-and-agent.mdc

@@ -0,0 +1,62 @@
+---
+description: Guidelines for the agent system and tool implementations
+globs: "src/agent/**/*.ts,src/tools/**/*.ts,src/grok/**/*.ts"
+alwaysApply: false
+---
+
+# Agent & Tools System
+
+## Agent
+
+`Agent` (in `src/agent/agent.ts`) is the core orchestrator. It manages:
+
+- The Grok API client (`GrokClient`)
+- Bash tool for all shell operations
+- Web search and X search via the Responses API
+- Chat history and message accumulation
+- Abort/cancellation support
+
+### Agent Loop
+
+The agent uses an iterative tool-call pattern via `processMessage` (async generator):
+
+1. Send messages to the LLM via Chat Completions API (streaming).
+2. If the response contains `tool_calls`, execute each tool.
+3. Append tool results to the message history.
+4. Repeat until no tool calls remain or `maxToolRounds` is reached.
+5. Yield `StreamChunk` objects for real-time UI updates.
+
+## Tool Interface
+
+All tools return a `ToolResult`:
+
+```typescript
+interface ToolResult {
+  success: boolean;
+  output?: string;
+  error?: string;
+}
+```
+
+Tools should never throw — wrap errors in `{ success: false, error: "..." }`.
+
+## Built-in Tools
+
+| Tool | File | Purpose |
+|------|------|---------|
+| `BashTool` | `src/tools/bash.ts` | Execute any shell command |
+| `search_web` | via `GrokClient.searchWeb()` | Web search using Responses API |
+| `search_x` | via `GrokClient.searchX()` | X/Twitter search using Responses API |
+
+## Grok Client
+
+`GrokClient` (in `src/grok/client.ts`) handles two API endpoints:
+
+- **Chat Completions** (`/v1/chat/completions`): Main agent loop with streaming and tool calling
+- **Responses API** (`/v1/responses`): X Search and Web Search with server-side tools
+
+## Adding a New Tool
+
+1. Add the tool schema to `src/grok/tools.ts` (in the `TOOLS` array).
+2. Add the execution case in `Agent.executeTool()`.
+3. Update the system prompt in `Agent` to document the tool.

package/.claude/worktrees/vigilant-johnson/.cursor/rules/typescript-conventions.mdc

@@ -0,0 +1,54 @@
+---
+description: TypeScript coding conventions and style guidelines
+globs: "**/*.ts,**/*.tsx"
+alwaysApply: false
+---
+
+# TypeScript Conventions
+
+## Module System
+
+- This is an ESM project (`"type": "module"` in package.json).
+- Always use ES module `import`/`export` syntax — never `require()`.
+- When importing local modules, include the `.js` extension (TypeScript compiles `.ts` → `.js`):
+  ```typescript
+  import { GrokAgent } from "./agent/grok-agent.js";
+  ```
+
+## TypeScript Configuration
+
+- Target: ES2022, Module: ESNext, JSX: react
+- `strict: false` and `noImplicitAny: false` — the codebase does not enforce strict mode.
+- `moduleResolution: "Bundler"` is used.
+- Source files live in `src/`, compiled output goes to `dist/`.
+
+## Type Practices
+
+- Prefer explicit interfaces for public API boundaries (e.g. `ChatEntry`, `ToolResult`, `GrokToolCall`).
+- Use `type` imports when importing only types:
+  ```typescript
+  import type { ChatCompletionMessageParam } from "openai/resources/chat";
+  ```
+- `any` is acceptable where strict typing would add friction, but prefer narrower types when practical.
+- Shared types belong in `src/types/index.ts`.
+
+## Naming Conventions
+
+- **Files**: kebab-case (`grok-agent.ts`, `chat-interface.tsx`, `settings-manager.ts`).
+- **Classes**: PascalCase (`GrokAgent`, `TextEditorTool`, `BashTool`).
+- **Interfaces/Types**: PascalCase (`ChatEntry`, `ToolResult`, `StreamingChunk`).
+- **Functions/variables**: camelCase (`processUserMessage`, `loadApiKey`).
+- **Constants**: camelCase or UPPER_SNAKE_CASE for true constants (`GROK_TOOLS`).
+
+## Error Handling
+
+- Catch errors as `error: any` and access `.message` for display.
+- Tool execution methods return `ToolResult` objects (`{ success, output?, error? }`) rather than throwing.
+- Use `process.exit(1)` for fatal CLI errors.
+
+## ESLint Rules
+
+- `@typescript-eslint/no-unused-vars`: error
+- `@typescript-eslint/no-explicit-any`: warn
+
+Run `bun run lint` to check and `bun run typecheck` to verify types.

package/.claude/worktrees/vigilant-johnson/.husky/pre-commit

@@ -0,0 +1 @@
+bun run pre-commit

package/.claude/worktrees/vigilant-johnson/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [copyright holders]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission statement shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/.claude/worktrees/vigilant-johnson/README.md

@@ -0,0 +1,341 @@
+# There are many coding agents. **This is Grok’s.**
+
+[![CI](https://github.com/superagent-ai/grok-cli/actions/workflows/typecheck.yml/badge.svg)](https://github.com/superagent-ai/grok-cli/actions/workflows/typecheck.yml)
+[![npm](https://img.shields.io/npm/v/grok-dev.svg)](https://www.npmjs.com/package/grok-dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-1.x-000000?logo=bun&logoColor=white)](https://bun.sh/)
+
+The rest borrowed from each other. We borrowed from *all of them*, then wired it to **Grok**—real-time **X search**, **web search**, **`grok-code-fast-1`** and the full Grok model lineup, **sub-agents on by default**, **remote control via Telegram** (pair once, drive the agent from your phone while the CLI runs), and a terminal UI that doesn’t feel like it was assembled in a hurry.
+
+Open source. Terminal-native. Built with **Bun** and **OpenTUI**. If you want vibes *and* velocity, you’re in the right repo.
+
+Community-built and unofficial. This project is not affiliated with or endorsed by xAI, and it is not the official Grok CLI.
+
+https://github.com/user-attachments/assets/7ca4f6df-50ca-4e9c-91b2-d4abad5c66cb
+
+---
+
+## Install
+
+```bash
+npm i -g grok-dev
+```
+
+The CLI binary is **`grok`** (yes, the package name and the command differ—deal with it).
+
+**Prerequisites:** Node 18+ (for the global install), a **Grok API key** from [x.ai](https://x.ai), and a modern terminal emulator for the interactive OpenTUI experience. Headless `--prompt` mode does not depend on terminal UI support.
+
+---
+
+## Run it
+
+**Interactive (default)** — launches the OpenTUI coding agent:
+
+```bash
+grok
+```
+
+### Supported terminals
+
+For the most reliable interactive OpenTUI experience, use a modern terminal emulator. We currently document and recommend:
+
+- **WezTerm** (cross-platform)
+- **Alacritty** (cross-platform)
+- **Ghostty** (macOS and Linux)
+- **Kitty** (macOS and Linux)
+
+Other modern terminals may work, but these are the terminal apps we currently recommend and document for interactive use.
+
+**Pick a project directory:**
+
+```bash
+grok -d /path/to/your/repo
+```
+
+**Headless** — one prompt, then exit (scripts, CI, automation):
+
+```bash
+grok --prompt "run the test suite and summarize failures"
+grok -p "show me package.json" --directory /path/to/project
+grok --prompt "refactor X" --max-tool-rounds 30
+grok --prompt "summarize the repo state" --format json
+grok --verify
+```
+
+**Continue a saved session:**
+
+```bash
+grok --session latest
+grok -s <session-id>
+```
+
+Works in interactive mode too—same flag.
+
+**Structured headless output:**
+
+```bash
+grok --prompt "summarize the repo state" --format json
+```
+
+`--format json` emits a newline-delimited JSON event stream instead of the
+default human-readable text output. Events are semantic, step-level records such
+as `step_start`, `text`, `tool_use`, `step_finish`, and `error`.
+
+### Scheduling
+
+Schedules let Grok run a headless prompt on a recurring schedule or once. Ask
+for it in natural language, for example:
+
+```text
+Create a schedule named daily-changelog-update that runs every weekday at 9am
+and updates CHANGELOG.md from the latest merged commits.
+```
+
+Recurring schedules require the background daemon:
+
+```bash
+grok daemon --background
+```
+
+Use `/schedule` in the TUI to browse saved schedules. One-time schedules start
+immediately in the background; recurring schedules keep running as long as the
+daemon is active.
+
+**List Grok models and pricing hints:**
+
+```bash
+grok models
+```
+
+**Pass an opening message without another prompt:**
+
+```bash
+grok fix the flaky test in src/foo.test.ts
+```
+
+**Generate images or short videos from chat:**
+
+```bash
+grok "Generate a retro-futuristic logo for my CLI called Grok Forge"
+grok "Edit ./assets/hero.png into a watercolor poster"
+grok "Animate ./assets/cover.jpg into a 6 second cinematic push-in"
+```
+
+Image and video generation are exposed as agent tools inside normal chat sessions.
+You keep using a text model for the session, and Grok saves generated media under
+`.grok/generated-media/` by default unless you ask for a specific output path.
+
+---
+
+## What you actually get
+
+| Thing | What it means |
+|--------|----------------|
+| **Grok-native** | Defaults tuned for Grok; models like **`grok-code-fast-1`**, **`grok-4-1-fast-reasoning`**, **`grok-4.20-multi-agent-0309`**, plus flagship and fast variants—run `grok models` for the full menu. |
+| **X + web search** | **`search_x`** and **`search_web`** tools—live posts and docs without pretending the internet stopped in 2023. |
+| **Media generation** | Built-in **`generate_image`** and **`generate_video`** tools for text-to-image, image editing, text-to-video, and image-to-video flows. Generated files are saved locally so you can reuse them after the xAI URLs expire. |
+| **Sub-agents (default behavior)** | Foreground **`task`** delegation (e.g. explore vs general) plus background **`delegate`** for read-only deep dives—parallelize like you mean it. |
+| **Verify** | **`/verify`** or **`--verify`** — inspects your app, builds, tests, boots it, and runs browser smoke checks in a sandboxed environment. Screenshots and video included. |
+| **Custom sub-agents** | Define named agents with **`subAgents`** in **`~/.grok/user-settings.json`** and manage them from the TUI with **`/agents`**. |
+| **Remote control** | Pair **Telegram** from the TUI (`/remote-control` → Telegram): DM your bot, **`/pair`**, approve the code in-terminal. Keep the CLI running while you ping it from your phone. |
+| **No “mystery meat” UI** | OpenTUI React terminal UI—fast, keyboard-driven, not whatever glitchy thing you’re thinking of. |
+| **Skills** | Agent Skills under **`.agents/skills/<name>/SKILL.md`** (project) or **`~/.agents/skills/`** (user). Use **`/skills`** in the TUI to list what’s installed. |
+| **MCPs** | Extend with Model Context Protocol servers—configure via **`/mcps`** in the TUI or **`.grok/settings.json`** (`mcpServers`). |
+| **Sessions** | Conversations persist; **`--session latest`** picks up where you left off. |
+| **Headless** | **`--prompt`** / **`-p`** for non-interactive runs—pipe it, script it, bench it. |
+| **Hackable** | TypeScript, clear agent loop, bash-first tools—fork it, shamelessly. |
+
+### Coming soon
+
+**Deeper autonomous agent testing** — persistent sandbox sessions, richer browser workflows, and stronger "prove it works" evidence.
+
+---
+
+## API key (pick one)
+
+**Environment (good for CI):**
+
+```bash
+export GROK_API_KEY=your_key_here
+```
+
+**`.env`** in the project (see `.env.example` if present):
+
+```bash
+GROK_API_KEY=your_key_here
+```
+
+**CLI once:**
+
+```bash
+grok -k your_key_here
+```
+
+**Saved in user settings** — `~/.grok/user-settings.json`:
+
+```json
+{ "apiKey": "your_key_here" }
+```
+
+Optional **`subAgents`** — custom foreground sub-agents. Each entry needs **`name`**, **`model`**, and **`instruction`**:
+
+```json
+{
+  "subAgents": [
+    {
+      "name": "security-review",
+      "model": "grok-code-fast-1",
+      "instruction": "Prioritize security implications and suggest concrete fixes."
+    }
+  ]
+}
+```
+
+Names cannot be `general`, `explore`, `vision`, or `verify` because those are reserved for the built-in sub-agents.
+
+Optional: **`GROK_BASE_URL`** (default `https://api.x.ai/v1`), **`GROK_MODEL`**, **`GROK_MAX_TOKENS`**.
+
+---
+
+## Telegram (remote control) — short version
+
+1. Create a bot with [@BotFather](https://t.me/BotFather), copy the token.
+2. Set **`TELEGRAM_BOT_TOKEN`** or add **`telegram.botToken`** in `~/.grok/user-settings.json` (the TUI **`/remote-control`** flow can save it).
+3. Start **`grok`**, open **`/remote-control`** → **Telegram** if needed, then in Telegram DM your bot: **`/pair`**, enter the **6-character code** in the terminal when asked.
+4. First user must be approved once; after that, it’s remembered. **Keep the CLI process running** while you use the bot (long polling lives in that process).
+
+### Voice & audio messages
+
+Send a voice note or audio attachment in Telegram and Grok will transcribe it locally with **[whisper.cpp](https://github.com/ggml-org/whisper.cpp)** before passing the text to the agent. No cloud STT service is involved — everything runs on your machine.
+
+#### Prerequisites
+
+| Dependency | Why | Install (macOS) |
+|---|---|---|
+| **whisper-cli** | Runs the actual speech-to-text inference | `brew install whisper-cpp` |
+| **ffmpeg** | Converts Telegram voice notes (OGG/Opus) to WAV for whisper.cpp | `brew install ffmpeg` |
+
+After installing, verify both are available:
+
+```bash
+whisper-cli -h
+ffmpeg -version
+```
+
+#### Download a Whisper model
+
+Grok CLI auto-downloads the configured model on first use, but you can pre-download it:
+
+```bash
+mkdir -p ~/.grok/models/stt/whisper.cpp
+curl -L https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin \
+  -o ~/.grok/models/stt/whisper.cpp/ggml-tiny.en.bin
+```
+
+Available models (trade size for accuracy): `tiny.en` (75 MB), `base.en` (142 MB), `small.en` (466 MB).
+
+#### Configure in `~/.grok/user-settings.json`
+
+```json
+{
+  "telegram": {
+    "botToken": "YOUR_BOT_TOKEN",
+    "audioInput": {
+      "enabled": true,
+      "binaryPath": "/opt/homebrew/bin/whisper-cli",
+      "model": "tiny.en",
+      "modelPath": "~/.grok/models/stt/whisper.cpp/ggml-tiny.en.bin",
+      "autoDownloadModel": true,
+      "language": "en"
+    }
+  }
+}
+```
+
+| Setting | Default | Description |
+|---|---|---|
+| `enabled` | `true` | Set to `false` to ignore voice/audio messages entirely. |
+| `binaryPath` | `whisper-cli` | Absolute path or command name for the whisper.cpp CLI binary. |
+| `model` | `tiny.en` | Model alias used for auto-download resolution. |
+| `modelPath` | _(auto-resolved)_ | Explicit path to a `.bin` model file. Overrides `model` + auto-download. |
+| `autoDownloadModel` | `true` | Download the model into `~/.grok/models/stt/whisper.cpp` on first use. |
+| `language` | `en` | Whisper language code passed to the CLI. |
+
+Optional headless flow when you do not want the TUI open:
+
+```bash
+grok telegram-bridge
+```
+
+Treat the bot token like a password.
+
+---
+
+## Instructions & project brain
+
+- **`AGENTS.md`** — merged from git root down to your cwd (Codex-style; see repo docs). **`AGENTS.override.md`** wins per directory when present.
+
+---
+
+## Project settings
+
+Project file: **`.grok/settings.json`** — e.g. the current model for this project.
+
+---
+
+## Sandbox
+
+Grok CLI can run shell commands inside a [Shuru](https://github.com/superhq-ai/shuru) microVM sandbox so the agent can't touch your host filesystem or network.
+
+**Requires macOS 14+ on Apple Silicon.**
+
+Enable it with `--sandbox` on the CLI, or toggle it from the TUI with `/sandbox`.
+
+When sandbox mode is active you can configure:
+
+- **Network** — off by default; enable with `--allow-net`, restrict with `--allow-host`
+- **Port forwards** — `--port 8080:80`
+- **Resource limits** — CPUs, memory, disk size (via settings or `/sandbox` panel)
+- **Checkpoints** — start from a saved environment snapshot
+- **Secrets** — inject API keys without exposing them inside the VM
+
+All settings are saved in `~/.grok/user-settings.json` (user) and `.grok/settings.json` (project).
+
+### Verify
+
+Run **`/verify`** in the TUI or **`--verify`** on the CLI to verify your app locally:
+
+```bash
+grok --verify
+grok -d /path/to/your/app --verify
+```
+
+The agent inspects your project, figures out how to build and run it, spins up a sandbox, and produces a verification report with screenshots and video evidence. Works with any app type.
+
+---
+
+## Development
+
+From a clone:
+
+```bash
+bun install
+bun run build
+bun run start
+# or: node dist/index.js
+```
+
+Other useful commands:
+
+```bash
+bun run dev      # run from source (Bun)
+bun run typecheck
+bun run lint
+```
+
+---
+
+## License
+
+MIT