A Terminal Coding Agent That Talks to Grok, and Lets You Drive It From Telegram
You've probably tried wiring an AI model into your terminal and ended up with a pile of shell scripts held together by hope. Or maybe you've wanted a coding agent that can actually search the web and X in real time, but didn't want to babysit it from your desk. grok-cli is an open-source coding agent that connects to xAI's Grok API, and it comes with a few features that make it worth a look.
What It Does
At its core, grok-cli is a terminal coding agent. You run it, it talks to the Grok API, and it helps you work on code in your project directory. It supports real-time X search and web search, the full Grok model lineup, and sub-agents that are on by default. The interactive experience is built with Bun and OpenTUI, so you get a proper terminal UI rather than a bare REPL.
It's not just interactive, though. There's a headless mode (--prompt) for scripts, CI, and automation, and you can pick up saved sessions later with --session latest or a specific session ID. If you need structured output, --format json emits a newline-delimited event stream with semantic records like step_start, text, tool_use, step_finish, and error—handy if you're piping results into something else.
One of the more unusual pieces is the built-in computer sub-agent, backed by agent-desktop, which handles host desktop automation on macOS. You ask for it in natural language, and it can take screenshots, launch apps, and snapshot the UI. There's also a --batch-api flag that routes through xAI's Batch API for lower-cost unattended runs where a delayed result is acceptable.
Why It's Cool
Remote control via Telegram is the standout feature. You pair once, and then you can drive the agent from your phone while the CLI runs on your machine. That's a genuinely different way to work—kick off a long task, walk away, and check in from wherever you are. Most terminal agents assume you're glued to the keyboard.
Sub-agents are on by default. Instead of making you opt into a more capable setup, grok-cli ships with them enabled. Combined with the computer sub-agent, that means the tool can reach outside the repo when a task calls for it, not just read and write files.
Headless mode is taken seriously. The --prompt flag, JSON event stream, --max-tool-rounds for bounding work, and --batch-api for cheap unattended runs all point to a tool that's meant to be used in real automation, not just demos. The --verify flag is there too, which suggests the project cares about checking its own output rather than just generating it.
It's honest about what it is. The README opens with a disclaimer that this is community-built and not affiliated with, endorsed by, or sponsored by xAI Corp. "Grok" is a trademark of xAI Corp., and the tool just uses the publicly available API. That kind of clarity is refreshing and tells you the maintainers aren't trying to imply an official relationship that doesn't exist.
Self-management is built in. If you install via the script, you get grok update, grok uninstall, grok uninstall --dry-run, and grok uninstall --keep-config. Small thing, but it means you're not left hunting for how to clean up later.
The terminal recommendations are specific. The README names WezTerm, Alacritty, Ghostty, and Kitty as the recommended and documented terminals for the interactive OpenTUI experience, and notes that others may work. That's more useful than a vague "any modern terminal" claim—you know exactly what's been tested.
How to Try It
-
Grab a Grok API key from x.ai. You'll need it before anything runs.
-
Install with the script:
curl -fsSL https://raw.githubusercontent.com/superagent-ai/grok-cli/main/install.sh | bash
Or, if you already have Bun on your PATH:
bun add -g grok-dev
- Launch the interactive agent from your project directory:
grok -d /path/to/your/repo
- Or run a one-off headless prompt:
grok --prompt "run the test suite and summarize failures"
- If you want the computer sub-agent on macOS, enable Accessibility permission for your terminal app. Then try something like:
grok "Use the computer sub-agent to take a screenshot of my host desktop and tell me what is open."
The full source and docs are at github.com/superagent-ai/grok-cli.
Final Thoughts
grok-cli is best suited to developers who already have a Grok API key and want a terminal agent that doesn't stop at file edits. The Telegram remote control and the computer sub-agent are the parts that set it apart, and the headless options make it usable in automation rather than just as an interactive toy. It's a young project with a clear scope and an honest README, which is a good sign. If you've been curious about Grok as a coding model but wanted a proper agent around it, this is a reasonable place to start.
Follow @githubprojects for more developer tools and open source projects.