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.
grok.mp4
npm i -g grok-devThe CLI binary is grok (yes, the package name and the command differ—deal with it).
Prerequisites: Node 18+ (for the global install), and a Grok API key from x.ai.
Interactive (default) — launches the OpenTUI coding agent:
grokPick a project directory:
grok -d /path/to/your/repoHeadless — one prompt, then exit (scripts, CI, automation):
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 jsonContinue a saved session:
grok --session latest
grok -s <session-id>Works in interactive mode too—same flag.
Structured headless output:
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.
List Grok models and pricing hints:
grok modelsPass an opening message without another prompt:
grok fix the flaky test in src/foo.test.ts| 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. |
| 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. |
| 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. |
Autonomous agent testing (think: sandboxed machine, recorded runs, Replit-style “prove it works”—the kind of thing that makes flaky human QA nervous). Not shipped yet; when it lands, we’ll be insufferable about it.
Environment (good for CI):
export GROK_API_KEY=your_key_here.env in the project (see .env.example if present):
GROK_API_KEY=your_key_hereCLI once:
grok -k your_key_hereSaved in user settings — ~/.grok/user-settings.json:
{ "apiKey": "your_key_here" }Optional subAgents — custom foreground sub-agents. Each entry needs name, model, and instruction:
{
"subAgents": [
{
"name": "security-review",
"model": "grok-code-fast-1",
"instruction": "Prioritize security implications and suggest concrete fixes."
}
]
}Names cannot be general or explore 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.
- Create a bot with @BotFather, copy the token.
- Set
TELEGRAM_BOT_TOKENor addtelegram.botTokenin~/.grok/user-settings.json(the TUI/remote-controlflow can save it). - 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. - 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).
Treat the bot token like a password.
AGENTS.md— merged from git root down to your cwd (Codex-style; see repo docs).AGENTS.override.mdwins per directory when present.
Project file: .grok/settings.json — e.g. the current model for this project.
From a clone:
bun install
bun run build
bun run start
# or: node dist/index.jsOther useful commands:
bun run dev # run from source (Bun)
bun run typecheck
bun run lintMIT
