# grox
Agentic coding with Grok.
## What it does
Grox is a CLI coding agent powered by Grok (xAI). It reads your codebase, runs commands, and writes code. It is designed to build understanding before making changes: reading files, exploring structure, and checking patterns rather than making changes too eagerly.
## Permission modes
Grox has four permission modes that control what the agent can do without asking:
- **Default** (`grox`) — Reads are automatic. Writes and shell commands prompt for approval. Destructive commands always prompt.
- **Trust** (`grox --auto-approve-writes`) — Writes inside the project are auto-approved. Everything else prompts.
- **Read-only** (`grox --read-only`) — The agent can only read files and respond. All writes and shell execution are denied.
- **Yolo** (`grox --yolo`) — Everything is auto-approved, including destructive commands. No guardrails.
## Tools
The agent has five tools:
- **file_read** — Read file contents.
- **file_write** — Create or overwrite files. Path-validated to stay inside the project root.
- **list_files** — Explore directory structure.
- **grep** — Search file contents by regex using ripgrep.
- **shell_exec** — Run shell commands in the project root.
## GROX.md
Add a `GROX.md` file in your project root to give the agent custom instructions. This gets appended to the system prompt as a "Project instructions" section. Truncated at 10K characters.
## Architecture
Seven flat Rust modules:
- **main** — REPL, CLI parsing, display formatting
- **agent** — Turn-based agent loop (max 25 turns per message)
- **api** — xAI Responses API client with SSE streaming
- **tools** — Tool definitions and execution
- **permissions** — Permission modes, destructive command detection, approval flow
- **prompt** — System prompt construction (5 sections + optional GROX.md)
- **util** — Project root detection, path validation, output clipping
The agent loop is synchronous and turn-based: send input to the API with a `previous_response_id`, execute any tool calls sequentially, return results, repeat. The server manages conversation history. Requires ripgrep (`rg`) on PATH for the grep tool.