grok-cli

The xAI Grok-Powered Command Line Coding Agent

Ink React terminal with full markdown rendering, vivid syntax highlighting for 25+ languages, TOON compression, persistent memory via ai-memory, and 10 custom sub-agents

Release MIT License TypeScript Bun Ink TOON

Built for Developers

Full markdown rendering with vivid syntax highlighting for 25+ languages. TOON compression reduces token costs automatically. Persistent memory across sessions powered by ai-memory. Runs in every terminal.

Install (Homebrew)

brew tap alphaonedev/homebrew-tap && brew install grok-cli

Install (curl)

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

Pricing

Pay-per-token with no subscription. Costs based on xAI published rates with TOON compression active.

Light
$6
per month
Solo dev, side project
Medium
$44
per month
Full-time IC engineer
Heavy
$112
per month
Tech lead, multi-repo
Super Heavy
$235
per month
Principal eng, CI integrated
Ultra Heavy
$280
per month
Platform team, org-wide
TierWhoDaily PatternTokens/MoCost/Mo
Light Solo dev, side project, 1-2 hrs/day 10-15 prompts, occasional debug ~6M $6
Medium Full-time IC, single repo, 4-6 hrs/day 30-50 prompts, daily PRs, code review ~25M $44
Heavy Tech lead, 2-3 repos, 6-8 hrs/day 100+ prompts, reviews every PR, architecture ~62M $112
Super Heavy Principal/Staff eng, CI pipeline, 8-10 hrs/day 200+ prompts, security audits, incident response ~132M $235
Ultra Heavy Platform team lead, org-wide tooling, 10+ hrs/day 300+ prompts, multi-team PRs, scheduled agents across repos, continuous security scanning ~180M $280

Real-World Examples

ActivitySub-AgentModel TierTokens/CallCost/Call
Quick question—Fast~3K$0.002
Implement a featureimplementStandard~20K$0.01
Code review a PRcode-reviewDeep~60K$0.48
Debug a production issuedebugDeep~50K$0.40
Architecture designarchitectDeep~80K$0.64
Security audit a modulesecurity-auditDeep~100K$0.80
Write test suitetest-writerStandard~25K$0.01
Generate docsdocsFast~8K$0.004

Deep model (grok-4.20-0309-reasoning) is 10x the cost but only used for architect, code-review, debug, and security-audit. The fast model handles 80% of work at $0.20/$0.50 per M tokens.

What's Different in This Fork

Ink React Terminal

Full markdown rendering powered by marked-terminal. Vivid syntax highlighting for 25+ languages including Python, JavaScript, Rust, Go, Java, C/C++, Ruby, and more. Headers, bold, italic, tables, code blocks, lists, links, blockquotes — all rendered correctly in every terminal.

TOON Compression

Token-Oriented Object Notation compresses structured tool results 30-50% before they enter conversation context. Reduces costs automatically and transparently.

Persistent Memory

Powered by ai-memory MCP — AlphaOne's persistent memory server (97.8% R@5 on LongMemEval, pure SQLite FTS5, zero cloud dependencies). Session-scoped connections, auto-recall on startup, and compaction summary storage. Your agent remembers across sessions.

Security Hardening

16 red team findings addressed. MCP tool name collision prevention (39 reserved names), description sanitization against prompt injection, proper lifecycle cleanup.

10 Sub-Agents

architect, code-review, debug, implement, refactor, test-writer, docs, quick-fix, data-ops, security-audit — across 3 model tiers.

All-Mode MCP

MCP tools work in plan, ask, and agent modes. Memory recall available everywhere, not just when executing tasks.

Full Grok Model Lineup

15 models from grok-4.20-0309-reasoning ($2/M) to grok-3-mini. All with 2M token context. Default: grok-4-1-fast-non-reasoning ($0.20/M) for instant responses.

Full Configuration

Complete ~/.grok/user-settings.json — copy, paste, replace the API key.

// ~/.grok/user-settings.json
{
  "apiKey": "YOUR xAI Grok API KEY GOES HERE",
  "baseURL": "https://api.x.ai/v1",
  "defaultModel": "grok-4-1-fast-non-reasoning",
  "models": [
    "grok-4.20-0309-reasoning", "grok-4.20-0309-non-reasoning", "grok-4.20-multi-agent-0309",
    "grok-4-1-fast-reasoning", "grok-4-1-fast-non-reasoning",
    "grok-4-fast-reasoning", "grok-4-fast-non-reasoning",
    "grok-4-0709", "grok-code-fast-1",
    "grok-3", "grok-3-mini"
  ],
  "settingsVersion": 2,
  "subAgents": [
    { "name": "architect",      "model": "grok-4.20-0309-reasoning",          "instruction": "Senior software architect..." },
    { "name": "code-review",    "model": "grok-4.20-0309-reasoning",          "instruction": "Thorough code reviewer..." },
    { "name": "debug",          "model": "grok-4.20-0309-reasoning",          "instruction": "Expert debugger..." },
    { "name": "security-audit", "model": "grok-4.20-0309-reasoning",          "instruction": "Application security auditor..." },
    { "name": "implement",      "model": "grok-4-1-fast-reasoning",      "instruction": "Implementation engineer..." },
    { "name": "refactor",       "model": "grok-4-1-fast-reasoning",      "instruction": "Refactoring specialist..." },
    { "name": "test-writer",    "model": "grok-4-1-fast-reasoning",      "instruction": "Test engineer..." },
    { "name": "docs",           "model": "grok-4-1-fast-non-reasoning",  "instruction": "Technical writer..." },
    { "name": "quick-fix",      "model": "grok-4-1-fast-non-reasoning",  "instruction": "Fast patch agent..." },
    { "name": "data-ops",       "model": "grok-4-1-fast-non-reasoning",  "instruction": "Data operations agent..." }
  ]
}

Full sub-agent instructions in user-settings-example.json. See CONFIGURATION.md for the complete guide.

ai-memory MCP Integration (optional)

Add persistent cross-session memory via ai-memory, AlphaOne's MCP-native memory server. Install with brew install alphaonedev/homebrew-tap/ai-memory, then merge into the config above:

{
  "mcp": {
    "servers": [{
      "id": "ai-memory",
      "label": "AI Memory",
      "enabled": true,
      "transport": "stdio",
      "command": "ai-memory",
      "args": ["mcp", "--tier", "semantic"]
    }]
  }
}

Model Catalog

ModelContextInput $/MOutput $/MBest For
grok-4.20-0309-reasoning2M$2.00$6.00Architecture, complex debugging, security audit
grok-4.20-0309-non-reasoning2M$2.00$6.00Fast flagship without thinking tokens
grok-4-1-fast-reasoning2M$0.20$0.50Deep analysis sub-agents
grok-4-1-fast-non-reasoning2M$0.20$0.50Default — instant responses, daily coding

Sub-Agent Tiers

TierModelAgentsCost per M
Deepgrok-4.20-0309-reasoningarchitect, code-review, debug, security-audit$2.00 / $6.00
Standardgrok-4-1-fast-reasoningimplement, refactor, test-writer$0.20 / $0.50
Fastgrok-4-1-fast-non-reasoningdocs, quick-fix, data-ops$0.20 / $0.50

Documentation

Configuration Guide — full setup with model catalog, sub-agents, and cost analysis
Headless JSON Spec — JSONL stream schema for --format json with jq cookbook
Release Signing — macOS codesign + notarization setup
Example Configuration — copy-paste ready template
ai-memory MCP — persistent memory server (grok-cli setup guide)
Sub-Agents Guide — built-in and custom agents
Releases · Changelog

Built with

The interactive console is built with React Ink (Vadim Demedes' React renderer for terminal UIs) on the Bun runtime. Markdown rendering uses marked + marked-terminal with chalk for ANSI colors. Agent loop calls xAI via Vercel AI SDK. Schema validation: zod. Telegram: grammY. Tests: Vitest. Lint/format: Biome.