Grok CLI

AI-Powered Development Agent for Your Terminal

A powerful CLI tool that brings Grok AI directly to your terminal with Claude Code-level intelligence, advanced code analysis, and comprehensive development capabilities.

Installation • Features • Usage • Code Intelligence • Research Foundation • Contributing

❤️ Grok-CLI — The Dev Assistant Built with Love (and a Lot of Neurons)

Because refactoring is better when you're smiling.

Welcome to grok-cli, a tool born from a simple idea: 👉 if we're going to code with an AI, it might as well be an AI that's intelligent, elegant... and good company.

This project was crafted with:

• a modern architecture,
• a pinch of creative madness,
• lots of coffee,
• and above all... all our heart. 💕

🚀 Why Does grok-cli Exist?

Because we were tired of AI assistants that:

• hallucinate more than a poorly-indexed SQL server
• generate code like an intern under pressure
• and refuse to do a serious review without "could you clarify your request?"

So we built something better:

• a sophisticated multi-agent system,
• deep code understanding,
• structured reasoning (ToT + MCTS),
• automatic repair,
• long-term memory,
• offline mode,
• plugins,
• a checkpoint system,
• and even a collaborative mode.

Yes. We enjoyed building this. And now you're going to enjoy using it too.

🧠 1. Multi-Agent System — Because One Brain is Good... Four is Better

grok-cli comes with a small internal team:

• Orchestrator — the conductor, calm and elegant
• Coder — the one who writes fast (too fast? no, just right)
• Reviewer — the one who gets into the details
• Tester — the one who breaks everything to see if it holds
• Refactorer — the one who does feng-shui in your code
• Documenter — the technical poet
• Analyst — the silent sage

They work together, sometimes debating, sometimes in consensus mode. Yes: the CLI literally has team discussions for you.

(You can sit back, everything's fine.)

🧩 2. Advanced RAG — Elephant Memory, Cheetah Speed

We've built a specialized RAG for code:

• intelligent chunking by language
• code-aware + semantic embeddings
• hybrid TF-IDF / vector search
• "corrective RAG" to avoid off-topic responses
• automatic complex context management

In short, it's as if your project were a book that grok-cli actually reads.

🌳 3. Tree-of-Thought + MCTS — Yes, the CLI Thinks Like an Adult

Here, the AI:

• explores multiple paths
• compares
• scores
• eliminates
• backtracks
• optimizes
• and chooses the best solution with a satisfied smile

With 4 modes:

• shallow
• medium
• deep
• exhaustive (this one might scare you, but in a good way)

🔧 4. APR — Automatic Program Repair

You know that Monday morning dev who fixes your bugs without asking? Neither do we.

But grok-cli does it:

• fault localization (Ochiai, DStar, Tarantula)
• 30+ repair templates
• guided LLM generation
• automatic test validation

And no, it never complains. (Amazing, I know.)

🧠💬 5. Extended Thinking Mode — Long-Duration Thought

Here, grok-cli:

• re-reads itself
• self-critiques
• detects contradictions
• makes another pass
• and gives you the best version of its thinking

It's like a senior dev who re-reads before sending you a commit. (Rare.)

🔀 6. Multi-Model Execution — LLM Speed Dating

Your CLI can query:

• Grok
• Claude
• Gemini
• And more...

And choose:

• the fastest
• the most relevant
• or make a democratic consensus

We wanted models to collaborate instead of fighting.

🗺️ 7. Semantic Code Map — A GPS for Your Project

grok-cli analyzes:

• imports
• calls
• inheritance
• technical layers
• important modules
• change impact

You ask "where's the business logic?" → it shows you. You say "if I change this, what breaks?" → it explains.

It's a GPS, but for devs. No subscription required.

🤝 8. Real-Time Collaboration — Code Together, Even Remotely

With WebSockets:

• multi-user sessions
• message sharing
• file sharing
• annotations
• roles (owner/admin/editor/viewer)
• audit trail
• encryption

Like Google Docs... but for coding. And more serious.

📊 9. Analytics Dashboard — Because a Great Project Deserves Great Graphs

Do you know how many tokens you consume? Which model costs the most? How many tests failed? How many MCTS iterations were done?

Now you do.

And you can export everything to JSON / CSV / Markdown.

🧩 10. Plugin Marketplace — Open Your Door to Creativity

Plugins with:

• Sandbox
• Stable API
• Commands
• Providers
• File tools
• MCP servers

Grok-cli can become whatever you choose to make of it.

📡 11. Offline Mode — Even Without Internet, You're Not Alone

• intelligent cache
• local execution via Ollama / llama.cpp
• request queue
• automatic sync

You keep working. Even on a plane. Even in an elevator. Even at your parents' house.

💾 12. Checkpoint & Undo System — Because Everyone Makes Mistakes

Before dangerous operations: 👉 grok-cli creates a snapshot.

You broke something? 👉 undo

Want to go back? 👉 restore checkpoint

Like Git, but... cuddly.

🎭 13. Personas — Your Personalized Assistants

7 built-in personas:

• senior dev
• code reviewer
• debugger
• security expert
• teacher
• minimalist
• architect

You can create others. Your CLI becomes you. (The well-rested version.)

🧠❤️ 14. Enhanced Memory — A Companion That Learns With You

• summaries
• preferences
• conventions
• habits
• code style
• patterns

Grok-cli remembers. Not to judge you. Just to help you better. ❤️

💞 And All This... Is Coded with Love and Good Vibes.

Every module, every agent, every pipeline... was born in an environment where there was:

• seriousness,
• technical excellence,
• but also a bit of ourselves,
• and a lot of desire to create something beautiful.

Overview

Grok CLI is a conversational AI development agent that transforms your terminal into an intelligent coding assistant. It combines the power of Grok AI with sophisticated code intelligence tools, enabling developers to analyze, refactor, and manage codebases with unprecedented efficiency.

Built on cutting-edge research in LLM-based agents, Tree-of-Thought reasoning, and Retrieval-Augmented Generation (RAG), Grok CLI represents the state-of-the-art in AI-assisted development.

Quick Start

# Run without installing
npx @phuetz/grok-cli@latest

# Or install globally
npm install -g @phuetz/grok-cli

# Start interactive mode
grok

# Or run a single command (headless mode)
grok --prompt "analyze the project structure"

Features

AI Agent Capabilities

| Feature | Description | |---------|-------------| | Agentic Loop | Up to 30 rounds of autonomous tool usage for complex tasks | | Real-time Streaming | Progressive response generation with instant feedback | | Multi-Model Support | Grok-4, Grok-3, Gemini, Claude via custom endpoints | | Token Tracking | Real-time token counting with tiktoken | | Extended Thinking | Deep reasoning mode for complex problems | | Tree-of-Thought | Advanced reasoning with MCTS exploration |

Multi-Agent System

Grok CLI implements a collaborative multi-agent architecture inspired by research on LLM-based Multi-Agent Systems for Software Engineering:

| Agent | Role | |-------|------| | Orchestrator | High-level planning and task decomposition | | Coder | Code generation and implementation | | Reviewer | Code review and quality feedback | | Tester | Test generation and validation | | Refactorer | Safe code refactoring operations | | Documenter | Documentation generation |

Code Intelligence

Comprehensive code intelligence suite inspired by Claude Code:

| Tool | Capabilities | |------|--------------| | AST Parser | Multi-language parsing (TypeScript, JavaScript, Python, Go) with caching | | Symbol Search | Fuzzy search with Levenshtein distance matching across codebases | | Dependency Analyzer | Circular dependency detection, unreachable file finder, dependency graphs | | Code Context | Semantic analysis, quality metrics, design pattern detection | | Refactoring Assistant | Safe rename, extract function/variable, inline, move operations |

RAG-Based Tool Selection

Implements intelligent tool selection based on RAG-MCP research:

| Metric | Without RAG | With RAG | Improvement | |--------|-------------|----------|-------------| | Token Usage | ~5000 | ~2500 | -50% | | Selection Accuracy | ~13% | ~43% | +230% | | Selection Time | N/A | <1ms | Negligible |

Advanced Tools

| Tool | Description | |------|-------------| | Multi-File Editor | Atomic transactional editing with automatic rollback | | Operation History | Full undo/redo with persistence to disk | | Plan Generator | Structured planning with phases and validation | | Codebase Explorer | Project analysis, statistics, tree visualization | | Git Integration | Auto-commits, branch management, PR creation | | Interactive Bash | PTY support for interactive commands (vim, htop) | | Sandboxed Terminal | Secure command execution with namespace isolation | | AI Code Review | Automated bug detection, security analysis, performance issues | | Parallel Executor | Run 8+ agents in parallel with git worktree isolation |

IDE Integrations

| Integration | Description | |-------------|-------------| | VS Code Extension | Full extension with chat sidebar, code actions, completions | | LSP Server | Language Server Protocol for Neovim, Sublime, Emacs | | Embedded Browser | Terminal-based web browsing with DOM inspection | | Voice Control | Native voice commands with wake word ("Hey Grok") |

Team & Collaboration

| Feature | Description | |---------|-------------| | Team Sessions | Real-time collaboration with role-based permissions | | Session Sharing | Share sessions with team members via invite codes | | Audit Logging | Complete audit trail of all actions | | Annotations | Add comments and annotations to shared code |

Analytics & Monitoring

| Feature | Description | |---------|-------------| | Usage Dashboard | Track sessions, messages, tokens, tool calls | | Cost Tracking | Real-time cost estimation by model | | Performance Metrics | Response times (P50, P90, P99), success rates | | Export Reports | Export to JSON, CSV, Markdown |

Plugin System

| Feature | Description | |---------|-------------| | Plugin Marketplace | Discover and install community plugins | | Plugin API | Register commands, tools, providers, hooks | | Sandboxed Execution | Secure plugin isolation | | Version Management | Automatic updates and compatibility checking |

Offline Mode

| Feature | Description | |---------|-------------| | Response Cache | Cache responses for offline use with LRU eviction | | Local LLM | Fallback to Ollama or llama.cpp when offline | | Request Queue | Queue requests when offline, sync on reconnect | | Embedding Cache | Semantic search works offline |

Memory & Personas

| Feature | Description | |---------|-------------| | Enhanced Memory | Long-term memory with semantic search | | Project Context | Automatic learning of project conventions | | Custom Personas | 7 built-in + custom persona creation | | Auto-Selection | Context-aware persona switching |

Checkpoint System

| Feature | Description | |---------|-------------| | File Checkpoints | Snapshot file states before changes | | Undo/Redo | Restore any checkpoint instantly | | Auto-Checkpoint | Automatic checkpoints before dangerous ops | | Diff Viewing | View changes between checkpoints |

Core Tools

| Tool | Description | |------|-------------| | view_file | View files and directories with line ranges | | create_file | Create files with automatic parent directory creation | | str_replace_editor | Intelligent text editing with fuzzy matching and visual diffs | | edit_file | Morph Fast Apply (4,500+ tokens/sec with 98% accuracy) - optimal for large files | | bash | Execute shell commands with persistent cd and timeout | | search | Ultra-fast search with ripgrep backend | | todo_list | Task management with priorities and status tracking | | multi_edit | Edit multiple files in a single atomic operation |

Morph Fast Apply (High-Speed Editing)

For ultra-fast file editing, Grok CLI integrates with Morph Fast Apply:

# Enable Morph Fast Apply
export MORPH_API_KEY=sk-...

# Now the edit_file tool is available with:
# - 4,500+ tokens/sec processing speed
# - 98% accuracy on complex edits
# - Perfect for files over 2000 lines

When to use Morph:

• Large files (>2000 lines) where str_replace_editor would be slow
• Complex multi-point edits in a single operation
• High-throughput batch editing scenarios

The agent automatically prefers edit_file when Morph is configured and the file is large.

Agent Modes

| Mode | Description | |------|-------------| | /code | Focus on code generation and editing | | /plan | Planning mode without side effects | | /ask | Question-answering mode | | /architect | Two-phase design/implementation mode |

Autonomy Levels

Configurable autonomy inspired by Cursor's YOLO mode:

| Level | Description | |-------|-------------| | suggest | Only suggest changes, always confirm | | confirm | Standard confirmation for all operations | | auto | Auto-execute safe operations, confirm dangerous ones | | full | Full autonomy (use with caution) |

YOLO Mode & Cost Protection

YOLO Mode enables full autonomous operation:

# Enable YOLO mode (full autonomy, 400 tool rounds, no cost limit)
YOLO_MODE=true grok

# Or toggle in session
/yolo on

Cost Protection prevents runaway API costs:

# Default: $10 session limit (disabled in YOLO mode)
# Set custom limit:
MAX_COST=25 grok

# Unlimited (use with caution):
MAX_COST=Infinity grok

| Mode | Max Tool Rounds | Session Cost Limit | |------|-----------------|-------------------| | Normal | 50 | $10 | | YOLO | 400 | Unlimited |

The agent will stop and warn you when the cost limit is reached.

Hooks System

Powerful hooks system for extending functionality:

| Hook | Trigger | |------|---------| | PreToolUse | Before tool execution | | PostToolUse | After tool completion | | SessionStart | When session begins | | SessionEnd | When session ends | | Notification | When notifications are sent |

Context Features

| Feature | Description | |---------|-------------| | @ Mentions | @file:, @url:, @image:, @git:, @symbol:, @search: | | Persistent Memory | Project and user-scoped memory in .grok/GROK_MEMORY.md | | Codebase RAG | Semantic code retrieval with embeddings | | Context Manager | Intelligent context compression and prioritization |

MCP Integration

Full Model Context Protocol support for extending capabilities:

// .grok/mcp.json
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

UI Components

Enhanced terminal UI with professional styling:

• 10 animated spinner styles (dots, braille, moon, earth, etc.)
• Progress bars with percentage display
• Step progress indicators
• Status indicators (success, error, warning, info)
• Info panels and tooltips
• Data tables and badges
• Countdown timers
• Streaming diff previews

Code Intelligence

AST Parser

Multi-language Abstract Syntax Tree parsing with intelligent caching:

import { getASTParser } from '@phuetz/grok-cli';

const parser = getASTParser();
const result = await parser.parseFile('src/index.ts');

// Access symbols, imports, exports
console.log(result.symbols);  // Functions, classes, variables
console.log(result.imports);  // All import statements
console.log(result.exports);  // All exports

Supported Languages:

• TypeScript (.ts, .tsx)
• JavaScript (.js, .jsx)
• Python (.py)
• Go (.go)

Symbol Search

Fuzzy symbol search across your entire codebase:

import { getSymbolSearch } from '@phuetz/grok-cli';

const search = getSymbolSearch();
await search.buildIndex('src/');

// Find symbols matching a query
const results = search.search('handleUser', {
  fuzzyThreshold: 0.6,
  maxResults: 10,
  types: ['function', 'class']
});

// Find all usages of a symbol
const usages = await search.findUsages('UserService');

Dependency Analyzer

Detect circular dependencies and analyze project structure:

import { getDependencyAnalyzer } from '@phuetz/grok-cli';

const analyzer = getDependencyAnalyzer();
const result = await analyzer.analyze('src/');

// Check for circular dependencies
console.log(result.circularDependencies);

// Find unreachable files
console.log(result.unreachableFiles);

// Get dependency graph
console.log(result.graph);

Code Context Builder

Build semantic understanding of your code:

import { getCodeContextBuilder } from '@phuetz/grok-cli';

const builder = getCodeContextBuilder();
const context = await builder.buildFileContext('src/utils.ts');

// Quality metrics
console.log(context.metrics.complexity);
console.log(context.metrics.maintainabilityIndex);

// Detected patterns
console.log(context.patterns); // Singleton, Factory, Observer, etc.

// Semantic tags
console.log(context.tags); // test, utility, api, ui, model, controller

Refactoring Assistant

Safe automated refactoring operations:

import { getRefactoringAssistant } from '@phuetz/grok-cli';

const assistant = getRefactoringAssistant();

// Preview changes before applying
const preview = await assistant.preview({
  type: 'rename',
  target: 'oldFunctionName',
  newName: 'newFunctionName',
  scope: 'src/'
});

// Apply refactoring
const result = await assistant.refactor({
  type: 'extractFunction',
  filePath: 'src/utils.ts',
  startLine: 10,
  endLine: 25,
  newName: 'extractedFunction'
});

Supported Operations:

• rename - Rename symbols across files
• extractFunction - Extract code to a new function
• extractVariable - Extract expression to a variable
• extractInterface - Extract type to interface
• inlineFunction - Inline function calls
• moveToFile - Move code to another file

Advanced Features

Tree-of-Thought Reasoning

Based on RethinkMCTS research, implementing Monte Carlo Tree Search for code generation:

import { getTreeOfThoughtReasoner } from '@phuetz/grok-cli';

const reasoner = getTreeOfThoughtReasoner();
const solution = await reasoner.reason(problem, {
  maxIterations: 10,
  explorationWeight: 1.4,
  rethinkOnError: true
});

Key capabilities:

• Selection: Choose most promising thought paths
• Expansion: Generate alternative approaches
• Simulation: Evaluate via code execution
• Backpropagation: Update path scores
• Rethink: Refine erroneous thoughts

Extended Thinking Mode

Deep reasoning inspired by Claude Code's extended thinking:

import { getExtendedThinking } from '@phuetz/grok-cli';

const thinking = getExtendedThinking();
const thoughts = await thinking.think(problem, 'deep'); // shallow, medium, deep

// Token budgets: shallow=5000, medium=20000, deep=100000

Auto-Repair Engine

Automated Program Repair based on AutoCodeRover and SWE-agent:

import { getRepairEngine } from '@phuetz/grok-cli';

const engine = getRepairEngine();
const result = await engine.repair(error, code, {
  maxPatches: 5,
  validateWithTests: true
});

Repair workflow:

1. Bug localization (token-level)
2. Generate candidate patches
3. Validate patches with tests
4. Apply best solution

Agent Pipelines

Chain agents in deterministic workflows:

import { getPipelineRunner } from '@phuetz/grok-cli';

const pipeline = {
  name: "code-review",
  stages: [
    { agent: "explorer", outputCapture: "context" },
    { agent: "code-reviewer" },
    { agent: "test-runner" },
    { agent: "documenter" }
  ],
  passContext: true
};

await getPipelineRunner().run(pipeline);

User command: /pipeline code-review

Skills System

Auto-activating specialized abilities:

<!-- .grok/skills/typescript-expert/SKILL.md -->
---
name: typescript-expert
description: Expert TypeScript developer
triggers: ["typescript", "type error", "generic"]
tools: ["view_file", "search", "str_replace_editor"]
---

You are a TypeScript expert. Focus on:
1. Complex generic types
2. Type inference issues
3. Declaration file problems

User command: /skill typescript-expert

Plan Mode

Structured planning for complex tasks:

import { getPlanGenerator } from '@phuetz/grok-cli';

const planner = getPlanGenerator();

const plan = planner.createPlan(
  'Implement Authentication',
  'Add user authentication to the application',
  'Complete auth flow with login, logout, and session management'
);

planner.addStep({
  title: 'Create User Model',
  priority: 'high',
  risk: 'low',
  estimatedComplexity: 2,
  dependencies: [],
  affectedFiles: ['src/models/user.ts']
});

console.log(planner.generateSummary());

Codebase Explorer

Comprehensive project analysis:

import { exploreCodebase } from '@phuetz/grok-cli';

const { stats, project, tree, report } = await exploreCodebase('./');

console.log(stats.totalFiles);        // Total file count
console.log(stats.filesByLanguage);   // Files per language
console.log(stats.totalLines);        // Total lines of code
console.log(project.type);            // nodejs, python, go, rust, etc.
console.log(tree);                    // ASCII tree view
console.log(report);                  // Full analysis report

Multi-File Editor

Atomic multi-file operations with rollback:

import { getMultiFileEditor } from '@phuetz/grok-cli';

const editor = getMultiFileEditor();

const txId = editor.beginTransaction('Refactor auth module');

editor.addOperation(txId, {
  type: 'edit',
  filePath: 'src/auth.ts',
  edit: { type: 'replace', search: 'oldCode', replace: 'newCode' }
});

editor.addOperation(txId, {
  type: 'create',
  filePath: 'src/auth-utils.ts',
  content: '// New utility file'
});

try {
  await editor.commit(txId);
} catch (error) {
  await editor.rollback(txId);
}

Operation History

Undo/redo with persistent storage:

import { getOperationHistory } from '@phuetz/grok-cli';

const history = getOperationHistory();

await history.undo();
await history.redo();
await history.goToHistoryPoint('operation-id');

const entries = history.getHistory();

Conversation Branching

Fork conversations to explore alternatives:

// /fork "experiment-name" - Create branch from current point
// /branches - List all branches
// /checkout <branch-id> - Switch to branch
// /merge <branch-id> - Merge branch into current

Cost Tracking

Real-time API cost monitoring:

// /cost - Show cost dashboard
// Displays: session cost, daily cost, model breakdown

Installation

Prerequisites

• Node.js 18.0.0 or higher
• ripgrep (optional, recommended for optimal search performance)

  # macOS
  brew install ripgrep
  
  # Ubuntu/Debian
  sudo apt-get install ripgrep
  
  # Windows
  choco install ripgrep

Install Methods

# npm
npm install -g @phuetz/grok-cli

# yarn
yarn global add @phuetz/grok-cli

# pnpm
pnpm add -g @phuetz/grok-cli

# bun
bun add -g @phuetz/grok-cli

Development Setup

git clone https://github.com/phuetz/grok-cli.git
cd grok-cli
npm install
npm run build
npm link

Configuration

API Key Setup

Get your API key from X.AI

Method 1: Environment Variable (Recommended)

export GROK_API_KEY=your_api_key_here

Method 2: .env File

GROK_API_KEY=your_api_key_here

Method 3: Command Line

grok --api-key your_api_key_here

Method 4: User Settings Create ~/.grok/user-settings.json:

{
  "apiKey": "your_api_key_here",
  "baseURL": "https://api.x.ai/v1",
  "defaultModel": "grok-4-latest"
}

Custom Base URL

Use alternative AI providers:

grok --base-url https://your-endpoint.com/v1

Project Settings

Create .grok/settings.json in your project:

{
  "model": "grok-4-latest",
  "maxRounds": 30,
  "autonomyLevel": "confirm",
  "enableRAG": true,
  "parallelTools": true
}

Hooks Configuration

Create .grok/hooks.json:

{
  "hooks": [
    {
      "event": "PostToolUse",
      "pattern": "str_replace_editor|create_file",
      "command": "npx prettier --write ${file} && npx eslint --fix ${file}",
      "description": "Auto-format after edits"
    },
    {
      "event": "SessionStart",
      "command": "npm install && npm run typecheck",
      "description": "Setup on session start"
    }
  ]
}

YOLO Mode Configuration

Create .grok/yolo.json:

{
  "enabled": true,
  "allowList": ["npm test", "npm run lint", "git status"],
  "denyList": ["rm -rf", "git push --force"],
  "maxAutoEdits": 5,
  "maxAutoCommands": 10,
  "safeMode": false
}

Usage

Interactive Mode

# Start in current directory
grok

# Specify working directory
grok -d /path/to/project

# Use specific model
grok --model grok-4-latest

# Resume last session
grok --resume

# Continue from last response
grok --continue

# Load specific session
grok --session <session-id>

Headless Mode

Perfect for CI/CD and scripting:

grok --prompt "analyze package.json and suggest optimizations"
grok -p "run tests and fix any failures" -d /path/to/project

Browser Mode

grok --browser
# Opens web UI at http://localhost:3000

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Shift+Tab | Toggle auto-edit mode | | Ctrl+C | Clear input / Interrupt | | Esc | Cancel current operation |

Slash Commands

| Command | Description | |---------|-------------| | /help | Show help | | /clear | Clear conversation | | /model | Change AI model | | /yolo | Toggle auto-execution mode | | /pipeline | Run automated workflows | | /skill | Activate specialized skills | | /cost | Show cost dashboard | | /fork | Create conversation branch | | /branches | List conversation branches | | /memory | Manage persistent memory | | /parallel | Execute tasks in parallel | | /generate-tests | Generate unit tests | | /scan-todos | Scan for AI comments | | /architect | Toggle architect mode | | /checkpoint | Create/restore checkpoints |

Custom Commands

Create custom commands in .grok/commands/:

<!-- .grok/commands/review-pr.md -->
Review the changes in this PR focusing on:
1. Code quality and best practices
2. Potential bugs or edge cases
3. Test coverage
4. Documentation

Usage: /review-pr

Project Structure

grok-cli/
├── src/
│   ├── agent/                  # AI agent core
│   │   ├── multi-agent/        # Multi-agent collaboration
│   │   ├── parallel/           # Parallel execution
│   │   ├── reasoning/          # Tree-of-thought, MCTS
│   │   ├── repair/             # Auto-repair engine
│   │   ├── thinking/           # Extended thinking
│   │   ├── grok-agent.ts       # Main agent
│   │   ├── architect-mode.ts   # Two-phase architecture
│   │   ├── pipelines.ts        # Agent pipelines
│   │   └── subagents.ts        # Subagent system
│   │
│   ├── tools/                  # Tool implementations
│   │   ├── intelligence/       # Code intelligence suite
│   │   │   ├── ast-parser.ts
│   │   │   ├── symbol-search.ts
│   │   │   ├── dependency-analyzer.ts
│   │   │   ├── code-context.ts
│   │   │   └── refactoring-assistant.ts
│   │   │
│   │   ├── multi-edit.ts       # Multi-file editor
│   │   ├── git-tool.ts         # Git integration
│   │   ├── interactive-bash.ts # PTY support
│   │   └── ...                 # Core tools
│   │
│   ├── context/                # Context management
│   │   ├── codebase-rag/       # RAG for codebase
│   │   ├── semantic-map/       # Semantic indexing
│   │   ├── context-manager.ts  # Context compression
│   │   └── codebase-map.ts     # Repository mapping
│   │
│   ├── memory/                 # Persistent memory
│   │   └── persistent-memory.ts
│   │
│   ├── skills/                 # Skills system
│   │   └── skill-manager.ts
│   │
│   ├── hooks/                  # Hooks system
│   │   └── hook-system.ts
│   │
│   ├── mcp/                    # MCP integration
│   │   └── mcp-client.ts
│   │
│   ├── ui/                     # Terminal UI (Ink/React)
│   │   └── components/
│   │
│   ├── services/               # Services
│   │   ├── plan-generator.ts
│   │   └── codebase-explorer.ts
│   │
│   └── utils/                  # Utilities
│       ├── autonomy-manager.ts
│       ├── cost-tracker.ts
│       ├── model-router.ts
│       └── ...
│
├── dist/                       # Compiled output
└── package.json

Tech Stack

| Category | Technology | |----------|------------| | Runtime | Node.js 18+ | | Language | TypeScript 5.3 | | UI | React 18 + Ink 4 | | CLI | Commander.js 12 | | AI Client | OpenAI SDK 5.10 | | Search | ripgrep-node | | Tokens | tiktoken | | MCP | @modelcontextprotocol/sdk | | PTY | node-pty (optional) |

Security

• Confirmation before destructive actions - All file and bash operations require approval
• Visual diff preview - See changes before applying
• Automated security scanning - npm audit and TruffleHog
• Input validation - Timeouts, buffer limits, round limits
• No hardcoded secrets - Environment variables and settings files
• Autonomy levels - Fine-grained control over auto-execution
• Command allow/deny lists - YOLO mode guardrails

Research Foundation

Grok CLI is built on cutting-edge research in AI-assisted software development:

LLM Agents for Code Generation

| Paper | Key Contribution | |-------|------------------| | Survey on Code Generation with LLM-based Agents | Comprehensive survey of 152 references on autonomous code agents | | Paper2Code: Multi-Agent Framework | Three-phase approach: Planning → Analysis → Generation | | ADAS: Automated Design of Agentic Systems | Meta Agent Search for designing new agents | | LLM-Based Multi-Agent Systems for SE | Multi-agent collaboration patterns |

Advanced Reasoning

| Paper | Key Contribution | |-------|------------------| | RethinkMCTS: Monte Carlo Tree Search for Code | 74% improvement vs simple CoT on complex problems | | Chain of Preference Optimization | Aligning Chain-of-Thought with Tree-of-Thought | | LongRoPE: Extending Context to 2M Tokens | Progressive context extension strategies |

RAG and Retrieval

| Paper | Key Contribution | |-------|------------------| | RAG-MCP | Tool selection via retrieval (basis for our RAG tool selection) | | ToolLLM | Tool learning with 16,000+ APIs | | RAG for Large Scale Code Repos | Enterprise-scale code retrieval strategies | | Corrective RAG (CRAG) | Adaptive retrieval with correction mechanisms |

Automated Program Repair

| Paper | Key Contribution | |-------|------------------| | AutoCodeRover | Autonomous bug localization and repair | | SWE-agent | State-of-the-art on SWE-bench | | LeDex: Training LLMs to Self-Debug | Improved self-explanation and debugging |

Benchmarks

| Benchmark | Description | |-----------|-------------| | SWE-bench | Real-world software engineering tasks | | SWE-bench Verified | Human-verified subset (500 problems) | | SWE-Bench Pro | Private benchmark to prevent data contamination | | Berkeley Function Calling Leaderboard | Tool use benchmarking |

Best Practices

| Resource | Description | |----------|-------------| | Building Effective Agents - Anthropic | Official guidance on agent design | | Claude Code Best Practices | Practical patterns for AI coding assistants |

Competitive Comparison

| Feature | Grok CLI | Claude Code | Aider | Gemini CLI | Cursor | |---------|----------|-------------|-------|------------|--------| | Terminal-native | YES | YES | YES | YES | NO | | Hooks system | YES | YES | NO | NO | YES | | Multi-edit | YES | YES | YES | NO | YES | | Architect mode | YES | NO | YES | NO | NO | | PTY support | YES | NO | NO | YES | NO | | Custom commands | YES | YES | NO | NO | NO | | Subagents | YES | YES | NO | NO | YES | | Auto-commit | YES | YES | YES | YES | NO | | Voice input | YES | NO | YES | NO | NO | | MCP support | YES | YES | NO | YES | NO | | Agent pipelines | YES | YES | NO | NO | NO | | Tree-of-Thought | YES | YES | NO | NO | NO | | Codebase RAG | YES | YES | YES | YES | YES | | Checkpoints | YES | YES | NO | NO | NO | | VS Code Extension | YES | YES | NO | NO | YES | | LSP Server | YES | NO | NO | NO | NO | | Sandboxed Terminal | YES | NO | NO | NO | YES | | AI Code Review | YES | NO | NO | NO | YES | | 8+ Parallel Agents | YES | YES | NO | NO | YES | | Team Collaboration | YES | NO | NO | NO | YES | | Analytics Dashboard | YES | NO | NO | NO | NO | | Plugin Marketplace | YES | NO | NO | NO | YES | | Offline Mode | YES | NO | NO | NO | NO | | Custom Personas | YES | NO | NO | NO | NO | | Enhanced Memory | YES | YES | NO | NO | NO | | GitHub Integration | YES | YES | YES | NO | NO |

Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development

npm install          # Install dependencies
npm run dev          # Development mode
npm run build        # Build project
npm run lint         # Run linter
npm run typecheck    # Type checking
npm test             # Run tests

Documentation

• Architecture Documentation - Detailed system design
• RAG Tool Selection - Tool selection algorithm
• Research Improvements - Research-based improvements
• Competitor Analysis - Feature comparison
• Security Policy - Security guidelines
• Changelog - Version history

License

MIT License - see LICENSE for details.

Acknowledgments

• X.AI for the Grok API
• OpenAI for the compatible SDK
• Anthropic for Claude Code inspiration and research
• Vadim Demedes for Ink
• BurntSushi for ripgrep
• The research community for foundational work on LLM agents
• The open-source community

Built with passion by the Grok CLI community

Report Bug • Request Feature