█

AI/TLDR

grok-cli

A terminal coding agent for the Grok API, with X search, sub-agents and remote control

GitHub★ 3.5k
Autonomous Coding AgentsOpen source
Language
TypeScript
License
MIT

Overview

grok-cli is a terminal coding agent that talks to xAI's Grok API. It is community-built and not affiliated with xAI, and it uses the publicly documented API, so you bring your own Grok API key from x.ai. The interactive experience is an OpenTUI interface built on Bun; the project recommends a modern terminal emulator such as WezTerm, Alacritty, Ghostty or Kitty for it.

Beyond the usual edit-and-run loop it leans on what the Grok API offers: real-time X search and web search are first-class tools, sub-agents are enabled by default, and a built-in `computer` sub-agent (backed by agent-desktop, macOS only) can drive the host desktop through accessibility snapshots — the documented loop is snapshot, resolve refs, act, snapshot again, rather than screenshot-and-guess.

It is also built to run unattended. A headless `--prompt` mode exits after one turn and does not need terminal UI support, `--format json` emits a newline-delimited stream of step-level events (`step_start`, `text`, `tool_use`, `step_finish`, `error`) for scripts and CI, and `--batch-api` routes unattended work through xAI's Batch API for cheaper delayed runs. A background daemon supports recurring schedules, sessions can be resumed by id, and pairing it once with Telegram lets you drive the agent from a phone while the CLI keeps running.

What it does

  • Interactive OpenTUI coding agent built with Bun, plus a headless one-shot `--prompt` mode for scripts and CI
  • Real-time X search and web search as built-in tools, across the Grok model lineup
  • Sub-agents on by default, including a macOS `computer` sub-agent for desktop automation via accessibility snapshots
  • Structured output with `--format json` — semantic step events rather than scraped text
  • `--batch-api` for lower-cost unattended runs through xAI's Batch API
  • Recurring and one-time schedules driven by a background daemon (`grok daemon --background`)
  • Resumable sessions (`grok --session latest`) and Telegram pairing for remote control
  • Self-management commands: `grok update`, `grok uninstall --keep-config`

Getting started

You need a Grok API key from x.ai. The install script is the supported path; the Bun global install is an alternative if Bun is already on your PATH.

Install

Install with the project's script, or globally with Bun.

bashbash
curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash

# alternative (requires Bun on PATH)
bun add -g grok-dev

Start it on a project

Run it interactively in the current directory, or point it at a repository.

bashbash
grok
grok -d /path/to/your/repo

Run it headlessly

One prompt, then exit — for scripts, CI and scheduled work. Add --format json for a machine-readable event stream, or --batch-api for cheaper unattended runs.

bashbash
grok --prompt "run the test suite and summarize failures"
grok --prompt "summarize the repo state" --format json
grok --prompt "review the repo overnight" --batch-api

Keep work running

Resume a saved session, list the models and their pricing hints, or start the daemon that recurring schedules need.

bashbash
grok --session latest
grok models
grok daemon --background

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

When to use it

  • Reach for it when your provider of choice is Grok and you want a terminal agent that speaks its API directly
  • Reach for it when a coding task needs live X or web context rather than the model's training data
  • Reach for it to script agent work in CI, where the JSON event stream is easier to consume than TUI output
  • Reach for it for scheduled maintenance jobs — a nightly changelog update or an overnight repo review over the Batch API

How grok-cli compares

grok-cli alongside other open-source autonomous coding agents tools AI/TLDR tracks, ranked by GitHub stars.

ToolStarsWhat it does
opencode★ 209kOpenCode is an open source AI coding agent that runs in your terminal, with built-in build and plan agents and an optional desktop app.
Claude Code★ 148kAnthropic's agentic coding tool for the terminal, IDE and GitHub: it understands your codebase, executes routine tasks, explains code and handles git workflows from natural-language commands.
OpenAI Codex★ 126kOpenAI's cloud and CLI coding agent that writes features, fixes bugs, and proposes code changes across a repo, running tasks in parallel.
Pi★ 108kMinimal terminal coding agent harness with four built-in tools, extended through TypeScript extensions, skills and prompt templates instead of forks.
Gemini CLI★ 107kAn open-source command-line AI agent from Google that connects your terminal to Gemini models for reading code, editing files, running shell commands, and searching the web.
autoresearch★ 96.5kKarpathy's minimal harness that hands a coding agent a single-GPU LLM training script and lets it run fixed five-minute experiments, keeping or discarding each change on its own.
OpenHands★ 88.8kAn open-source AI software-development agent that plans tasks, edits files, runs commands, and tests code, usable from a terminal CLI, a local web GUI, or a Python SDK.
grok-cli★ 3.5kA terminal coding agent for the Grok API, with X search, sub-agents and remote control