[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-73769":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":34,"readmeContent":35,"aiSummary":36,"trendingCount":16,"starSnapshotCount":16,"syncStatus":37,"lastSyncTime":38,"discoverSource":39},73769,"grok-cli","superagent-ai\u002Fgrok-cli","superagent-ai","An open-source coding agent for the Grok API","",null,"TypeScript",3144,390,31,13,0,14,38,118,42,29.78,"MIT License",false,"main",true,[27,28,29,30,31,32,33],"agents","ai","cli","code","coding-agent","grok","xai","2026-06-12 02:03:17","# grok-cli: an open-source coding agent for the Grok API\n\n[![CI](https:\u002F\u002Fgithub.com\u002Fsuperagent-ai\u002Fgrok-cli\u002Factions\u002Fworkflows\u002Ftypecheck.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fsuperagent-ai\u002Fgrok-cli\u002Factions\u002Fworkflows\u002Ftypecheck.yml)\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fgrok-dev.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fgrok-dev)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](.\u002FLICENSE)\n[![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https:\u002F\u002Fwww.typescriptlang.org\u002F)\n[![Bun](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBun-1.x-000000?logo=bun&logoColor=white)](https:\u002F\u002Fbun.sh\u002F)\n\n> **Disclaimer:** This project is community-built, open-source, and **not affiliated with, endorsed by, or sponsored by xAI Corp.** \"Grok\" is a trademark of xAI Corp. This tool uses the publicly available Grok API.\n\nAn open-source terminal coding agent that connects to xAI’s Grok API — real-time **X search**, **web search**, 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 built with **Bun** and **OpenTUI**.\n\n[https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F7ca4f6df-50ca-4e9c-91b2-d4abad5c66cb](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F7ca4f6df-50ca-4e9c-91b2-d4abad5c66cb)\n\n---\n\n## Install\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fsuperagent-ai\u002Fgrok-cli\u002Fmain\u002Finstall.sh | bash\n```\n\n**Alternative installs** (requires Bun on PATH):\n\n```bash\nbun add -g grok-dev\n```\n\n**Self-management** (script-installed only):\n\n```bash\ngrok update\ngrok uninstall\ngrok uninstall --dry-run\ngrok uninstall --keep-config\n```\n\n**Prerequisites:** a **Grok API key** from [x.ai](https:\u002F\u002Fx.ai) and a modern terminal emulator for the interactive OpenTUI experience. Headless `--prompt` mode does not depend on terminal UI support. If you want host desktop automation via the built-in computer sub-agent, also enable **Accessibility** permission for your terminal app on macOS.\n\n---\n\n## Run it\n\n**Interactive (default)** — launches the OpenTUI coding agent:\n\n```bash\ngrok\n```\n\n### Supported terminals\n\nFor the most reliable interactive OpenTUI experience, use a modern terminal emulator. We currently document and recommend:\n\n- **WezTerm** (cross-platform)\n- **Alacritty** (cross-platform)\n- **Ghostty** (macOS and Linux)\n- **Kitty** (macOS and Linux)\n\nOther modern terminals may work, but these are the terminal apps we currently recommend and document for interactive use.\n\n**Pick a project directory:**\n\n```bash\ngrok -d \u002Fpath\u002Fto\u002Fyour\u002Frepo\n```\n\n**Headless** — one prompt, then exit (scripts, CI, automation):\n\n```bash\ngrok --prompt \"run the test suite and summarize failures\"\ngrok -p \"show me package.json\" --directory \u002Fpath\u002Fto\u002Fproject\ngrok --prompt \"refactor X\" --max-tool-rounds 30\ngrok --prompt \"summarize the repo state\" --format json\ngrok --prompt \"review the repo overnight\" --batch-api\ngrok --verify\n```\n\n`--batch-api` uses xAI's Batch API for lower-cost unattended runs. It is a good\nfit for scripts, CI, schedules, and other non-interactive workflows where a\ndelayed result is fine.\n\n**Continue a saved session:**\n\n```bash\ngrok --session latest\ngrok -s \u003Csession-id>\n```\n\nWorks in interactive mode too—same flag.\n\n**Structured headless output:**\n\n```bash\ngrok --prompt \"summarize the repo state\" --format json\n```\n\n`--format json` emits a newline-delimited JSON event stream instead of the\ndefault human-readable text output. Events are semantic, step-level records such\nas `step_start`, `text`, `tool_use`, `step_finish`, and `error`.\n\n### Computer sub-agent\n\nGrok ships a built-in `**computer**` sub-agent backed by `[agent-desktop](https:\u002F\u002Fgithub.com\u002Flahfir\u002Fagent-desktop)` for host desktop automation on macOS.\n\nAsk for it in natural language, for example:\n\n```bash\ngrok \"Use the computer sub-agent to take a screenshot of my host desktop and tell me what is open.\"\ngrok \"Use the computer sub-agent to launch Google Chrome, snapshot the UI, and tell me which refs correspond to the address bar and tabs.\"\n```\n\nNotes:\n\n- Screenshots are saved under `**.grok\u002Fcomputer\u002F**` by default.\n- The primary workflow is **snapshot -> refs -> action -> snapshot** using `agent-desktop` accessibility snapshots and stable refs like `@e1`.\n- `computer_screenshot` is available for visual confirmation, but the preferred path is `computer_snapshot` plus ref-based actions such as `computer_click`, `computer_type`, and `computer_scroll`.\n- macOS requires **System Settings → Privacy & Security → Accessibility** access for the terminal app running `grok`.\n- `agent-desktop` currently targets **macOS**.\n- If Bun blocks the native binary download during install, run:\n\n```bash\nnode .\u002Fnode_modules\u002Fagent-desktop\u002Fscripts\u002Fpostinstall.js\n```\n\n### Scheduling\n\nSchedules let Grok run a headless prompt on a recurring schedule or once. Ask\nfor it in natural language, for example:\n\n```text\nCreate a schedule named daily-changelog-update that runs every weekday at 9am\nand updates CHANGELOG.md from the latest merged commits.\n```\n\nRecurring schedules require the background daemon:\n\n```bash\ngrok daemon --background\n```\n\nUse `\u002Fschedule` in the TUI to browse saved schedules. One-time schedules start\nimmediately in the background; recurring schedules keep running as long as the\ndaemon is active.\n\n**List Grok models and pricing hints:**\n\n```bash\ngrok models\n```\n\n**Pass an opening message without another prompt:**\n\n```bash\ngrok fix the flaky test in src\u002Ffoo.test.ts\n```\n\n**Generate images or short videos from chat:**\n\n```bash\ngrok \"Generate a retro-futuristic logo for my CLI called Grok Forge\"\ngrok \"Edit .\u002Fassets\u002Fhero.png into a watercolor poster\"\ngrok \"Animate .\u002Fassets\u002Fcover.jpg into a 6 second cinematic push-in\"\n```\n\nImage and video generation are exposed as agent tools inside normal chat sessions.\nYou keep using a text model for the session, and Grok saves generated media under\n`.grok\u002Fgenerated-media\u002F` by default unless you ask for a specific output path.\n\n---\n\n## What you actually get\n\n\n| Thing                             | What it means                                                                                                                                                                                                              |\n| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Built for the Grok API**        | Defaults tuned for the xAI API; models like `grok-4.3`, `grok-4.20-non-reasoning`, `grok-4.20-multi-agent-0309`, plus current flagship and multi-agent variants—run `grok models` for the full menu.                       |\n| **X + web search**                | `**search_x`** and `**search_web`** tools—live posts and docs without pretending the internet stopped in 2023.                                                                                                             |\n| **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. |\n| **Sub-agents (default behavior)** | Foreground `**task`** delegation (e.g. explore, general, or computer) plus background `**delegate`** for read-only deep dives—parallelize like you mean it.                                                                |\n| **Verify**                        | `**\u002Fverify`** or `**--verify`** — inspects your app, builds, tests, boots it, and runs browser smoke checks in a sandboxed environment. Screenshots and video included.                                                    |\n| **Computer use**                  | Built-in `**computer`** sub-agent for host desktop automation via `**agent-desktop`**. It prefers semantic accessibility snapshots and stable refs, with screenshots saved under `**.grok\u002Fcomputer\u002F**` when requested.     |\n| **Custom sub-agents**             | Define named agents with `**subAgents`** in `**~\u002F.grok\u002Fuser-settings.json`** and manage them from the TUI with `**\u002Fagents**`.                                                                                              |\n| **Remote control**                | Pair **Telegram** from the TUI (`\u002Fremote-control` → Telegram): DM your bot, `**\u002Fpair`**, approve the code in-terminal. Keep the CLI running while you ping it from your phone.                                             |\n| **No “mystery meat” UI**          | OpenTUI React terminal UI—fast, keyboard-driven, not whatever glitchy thing you’re thinking of.                                                                                                                            |\n| **Skills**                        | Agent Skills under `**.agents\u002Fskills\u002F\u003Cname>\u002FSKILL.md`** (project) or `**~\u002F.agents\u002Fskills\u002F`** (user). Use `**\u002Fskills**` in the TUI to list what’s installed.                                                                |\n| **MCPs**                          | Extend with Model Context Protocol servers—configure via `**\u002Fmcps`** in the TUI or `**.grok\u002Fsettings.json`** (`mcpServers`).                                                                                               |\n| **Sessions**                      | Conversations persist; `**--session latest`** picks up where you left off.                                                                                                                                                 |\n| **Headless**                      | `**--prompt`** \u002F `**-p`** for non-interactive runs—pipe it, script it, bench it.                                                                                                                                           |\n| **Hackable**                      | TypeScript, clear agent loop, bash-first tools—fork it, shamelessly.                                                                                                                                                       |\n\n\n### Coming soon\n\n**Deeper autonomous agent testing** — persistent sandbox sessions, richer browser workflows, and stronger \"prove it works\" evidence.\n\n---\n\n## API key (pick one)\n\n**Environment (good for CI):**\n\n```bash\nexport GROK_API_KEY=your_key_here\n```\n\n`**.env**` in the project (see `.env.example` if present):\n\n```bash\nGROK_API_KEY=your_key_here\n```\n\n**CLI once:**\n\n```bash\ngrok -k your_key_here\n```\n\n**Saved in user settings** — `~\u002F.grok\u002Fuser-settings.json`:\n\n```json\n{ \"apiKey\": \"your_key_here\" }\n```\n\nOptional `**subAgents**` — custom foreground sub-agents. Each entry needs `**name**`, `**model**`, and `**instruction**`:\n\n```json\n{\n  \"subAgents\": [\n    {\n      \"name\": \"security-review\",\n      \"model\": \"grok-4.3\",\n      \"instruction\": \"Prioritize security implications and suggest concrete fixes.\"\n    }\n  ]\n}\n```\n\nNames cannot be `general`, `explore`, `vision`, `verify`, or `computer` because those are reserved for the built-in sub-agents.\n\nOptional: `**GROK_BASE_URL**` (default `https:\u002F\u002Fapi.x.ai\u002Fv1`), `**GROK_MODEL**`, `**GROK_MAX_TOKENS**`.\n\n---\n\n## Telegram (remote control) — short version\n\n1. Create a bot with [@BotFather](https:\u002F\u002Ft.me\u002FBotFather), copy the token.\n2. Set `**TELEGRAM_BOT_TOKEN**` or add `**telegram.botToken**` in `~\u002F.grok\u002Fuser-settings.json` (the TUI `**\u002Fremote-control**` flow can save it).\n3. Start `**grok**`, open `**\u002Fremote-control**` → **Telegram** if needed, then in Telegram DM your bot: `**\u002Fpair`**, enter the **6-character code** in the terminal when asked.\n4. 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).\n\n### Voice & audio messages\n\nSend a voice note or audio attachment in Telegram and Grok will transcribe it with the **Grok Speech-to-Text API** (`POST https:\u002F\u002Fapi.x.ai\u002Fv1\u002Fstt`) before passing the text to the agent. The endpoint accepts Telegram's OGG\u002FOpus voice notes and common audio containers (MP3, WAV, M4A, FLAC, AAC) directly — no local model download, `whisper-cli`, or `ffmpeg` required.\n\n#### Prerequisites\n\n- A valid `GROK_API_KEY` (the same key used for the agent). Transcription reuses the CLI's `apiKey` \u002F `baseURL` resolution, so if the agent can reach xAI, transcription will too.\n\n#### Configure in `~\u002F.grok\u002Fuser-settings.json`\n\n```json\n{\n  \"telegram\": {\n    \"botToken\": \"YOUR_BOT_TOKEN\",\n    \"audioInput\": {\n      \"enabled\": true,\n      \"language\": \"en\"\n    }\n  }\n}\n```\n\n\n| Setting    | Default | Description                                                                                                           |\n| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------- |\n| `enabled`  | `true`  | Set to `false` to ignore voice\u002Faudio messages entirely.                                                               |\n| `language` | `en`    | Language code forwarded to `\u002Fv1\u002Fstt`. Enables Inverse Text Normalization (numbers, currencies, units → written form). |\n\n\nOptional headless flow when you do not want the TUI open:\n\n```bash\ngrok telegram-bridge\n```\n\nTreat the bot token like a password.\n\n---\n\n## Hooks\n\nHooks execute shell commands at key agent lifecycle events — enforce policies, run linters, trigger tests, or log activity.\n\nConfigure in `~\u002F.grok\u002Fuser-settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \".\u002Fscripts\u002Flint-before-edit.sh\",\n            \"timeout\": 10\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nHook commands receive JSON on **stdin** (event details) and can return JSON on **stdout**. Exit code `0` = success, `2` = block the action, other = non-blocking error.\n\n**Supported events:** `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `PreCompact`, `PostCompact`, `Notification`, `InstructionsLoaded`, `CwdChanged`.\n\n---\n\n## Instructions & project brain\n\n- `**AGENTS.md`** — merged from git root down to your cwd (Codex-style; see repo docs). `**AGENTS.override.md**` wins per directory when present.\n\n---\n\n## Project settings\n\nProject file: `**.grok\u002Fsettings.json**` — e.g. the current model for this project.\n\n---\n\n## Sandbox\n\nGrok CLI can run shell commands inside a [Shuru](https:\u002F\u002Fgithub.com\u002Fsuperhq-ai\u002Fshuru) microVM sandbox so the agent can't touch your host filesystem or network.\n\n**Requires macOS 14+ on Apple Silicon.**\n\nEnable it with `--sandbox` on the CLI, or toggle it from the TUI with `\u002Fsandbox`.\n\nOn the first interactive run in a new directory, Grok asks whether to remember sandbox or host mode for that workspace and stores the choice in `~\u002F.grok\u002Fworkspace-trust.json`. Explicit `--sandbox` \u002F `--no-sandbox` flags and non-interactive commands keep their current behavior.\n\nWhen sandbox mode is active you can configure:\n\n- **Network** — off by default; enable with `--allow-net`, restrict with `--allow-host`\n- **Port forwards** — `--port 8080:80`\n- **Resource limits** — CPUs, memory, disk size (via settings or `\u002Fsandbox` panel)\n- **Checkpoints** — start from a saved environment snapshot\n- **Secrets** — inject API keys without exposing them inside the VM\n\nAll settings are saved in `~\u002F.grok\u002Fuser-settings.json` (user) and `.grok\u002Fsettings.json` (project).\n\n### Verify\n\nRun `**\u002Fverify`** in the TUI or `**--verify`** on the CLI to verify your app locally:\n\n```bash\ngrok --verify\ngrok -d \u002Fpath\u002Fto\u002Fyour\u002Fapp --verify\n```\n\nThe 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.\n\n---\n\n## Troubleshooting\n\nCommon issues and solutions:\n\n### Installation issues\n\n**Install script fails on macOS**\n\nMake sure you have a modern shell and `curl` available:\n\n```bash\n# Verify curl is installed\nwhich curl\n\n# If using an outdated shell, try with bash explicitly\nbash -c \"$(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fsuperagent-ai\u002Fgrok-cli\u002Fmain\u002Finstall.sh)\"\n```\n\n**Bun not found**\n\nThe install script bundles Bun, but if you want to use your own:\n\n```bash\ncurl -fsSL https:\u002F\u002Fbun.sh\u002Finstall | bash\nbun add -g grok-dev\n```\n\n### API key issues\n\n**\"Missing GROK_API_KEY\" error**\n\nSet your API key using one of these methods:\n\n```bash\n# Environment variable\nexport GROK_API_KEY=your_key_here\n\n# Or save to user settings\ngrok -k your_key_here\n```\n\nGet your API key from [x.ai](https:\u002F\u002Fx.ai).\n\n### Terminal UI issues\n\n**UI doesn't render correctly**\n\nTry a different terminal emulator. Recommended:\n\n- WezTerm (cross-platform)\n- Alacritty (cross-platform)\n- Ghostty (macOS\u002FLinux)\n- Kitty (macOS\u002FLinux)\n\n**Screen flickering or artifacts**\n\nEnsure your terminal supports true color and Unicode. Update your terminal emulator to the latest version.\n\n### Telegram remote control\n\n**Bot doesn't respond**\n\n1. Verify `TELEGRAM_BOT_TOKEN` is set correctly\n2. Ensure the CLI process is still running (long polling lives in the process)\n3. Check that you've completed the `\u002Fpair` flow and been approved\n\n**Voice messages not transcribing**\n\n- Verify `GROK_API_KEY` is set (transcription uses the same key)\n- Check `~\u002F.grok\u002Fuser-settings.json` has `telegram.audioInput.enabled: true`\n\n### Sandbox mode\n\n**Sandbox only works on macOS 14+ with Apple Silicon**\n\nIf you're on Intel Mac or Linux, sandbox mode is not available. Use standard mode without `--sandbox`.\n\n### Performance issues\n\n**Slow response times**\n\n- Check your network connection to x.ai API\n- Try `grok-4.20-non-reasoning` for non-reasoning workloads\n- Reduce `--max-tool-rounds` for headless runs\n\n**High memory usage**\n\n- Long-running sessions accumulate context; start a fresh session periodically\n- Use `\u002Fcompact` in TUI to compress conversation history\n\n### Getting help\n\n- Check existing [issues](https:\u002F\u002Fgithub.com\u002Fsuperagent-ai\u002Fgrok-cli\u002Fissues)\n- Open a new issue with:\n  - OS and terminal emulator version\n  - Grok CLI version (`grok --version`)\n  - Steps to reproduce\n  - Error messages or logs\n\n---\n\n## Development\n\nFrom a clone:\n\n```bash\nbun install\nbun run build\nbun run start\n# or: node dist\u002Findex.js\n```\n\nOther useful commands:\n\n```bash\nbun run dev      # run from source (Bun)\nbun run typecheck\nbun run lint\n```\n\n---\n\n## Trademarks\n\n\"Grok\" is a registered trademark of xAI Corp. This project is not affiliated with, endorsed by, or sponsored by xAI Corp. All trademarks belong to their respective owners.\n\n---\n\n## License\n\nMIT\n","grok-cli 是一个开源的终端编码代理，用于连接 xAI 的 Grok API。该项目使用 TypeScript 编写，并通过 Bun 和 OpenTUI 构建了终端用户界面。它支持实时 X 搜索、网络搜索、完整的 Grok 模型阵容，默认启用子代理，并可以通过 Telegram 进行远程控制。此外，grok-cli 提供了交互式和无头模式，适用于自动化脚本、持续集成以及日常开发中的代码审查和重构等场景。",2,"2026-06-11 03:47:18","high_star"]