grok-cli-acp

v0.1.2

Published

a month ago

grok-cli in rust with acp access

0High
0Medium
0Low

cobble59

Xai grok Zed ACP

Grok CLI - Enhanced AI Assistant with Gemini-like Experience

A powerful command-line interface for interacting with Grok AI via X API, featuring a beautiful interactive experience inspired by Gemini CLI.

🎉 New in v0.1.2:
Session Persistence - Save and resume conversations
Hierarchical Configuration - Project-specific settings
Enhanced Context Discovery - Multi-editor support (.zed/rules, .claude.md, etc.)
Extension System - Custom hooks and plugins
See Quick Reference for details.
🔧 Latest Update:
Chat Logging: Automatic conversation logging with search and replay capabilities
Fixed "failed to deserialize response" error in Zed integration. See FIXES.md for details.

🚀 Features

🆕 New Features (v0.1.2)

Session Persistence - Save and resume conversations with /save, /load, and /list commands
Hierarchical Configuration - Project-local settings override system defaults (.grok/config.toml)
Enhanced Context Discovery - Multi-editor support: .zed/rules, .claude.md, .cursor/rules, and more
Context File Merging - Automatically merges all available context files with source annotations
Extension System - Extend functionality with custom hooks and plugins
Project-Aware AI - Agent automatically understands your project conventions

✨ Beautiful Interactive Experience

Adaptive ASCII Art Logo - Stunning terminal graphics that adapt to your screen size
Rich Interactive Mode - Gemini CLI-inspired interface with context-aware prompts
Smart Banners & Tips - Helpful startup guidance and contextual information
Colorful Output - Professional color scheme with gradient effects
Progress Indicators - Visual feedback for all operations

💬 Advanced Chat Capabilities

Interactive Sessions - Persistent conversations with context tracking
Automatic Tool Execution - Grok can now create files and directories automatically!
Chat Logging - Automatic conversation logging with full history
Session Search - Search through all past conversations
History Replay - Review and analyze previous sessions
System Prompts - Customize AI behavior for specialized tasks
Temperature Control - Adjust creativity levels (0.0-2.0)
Token Management - Real-time context usage monitoring

💻 Code Intelligence

Code Explanation - Understand complex codebases instantly
Code Review - Get detailed feedback with security focus
Code Generation - Create code from natural language descriptions
Multi-language Support - Works with any programming language

🔧 Developer Tools

Health Diagnostics - Comprehensive system and API monitoring
Configuration Management - Flexible TOML-based settings
Zed Editor Integration - Agent Client Protocol (ACP) support
Network Resilience - Starlink-optimized with retry logic

🎨 Visual Demo

  ░██████╗░██████╗░░█████╗░██╗░░██╗
  ██╔════╝░██╔══██╗██╔══██╗██║░██╔╝
  ██║░░██╗░██████╔╝██║░░██║█████═╝░
  ██║░░╚██╗██╔══██╗██║░░██║██╔═██╗░
  ╚██████╔╝██║░░██║╚█████╔╝██║░╚██╗
  ░╚═════╝░╚═╝░░╚═╝░╚════╝░╚═╝░░╚═╝

┌─────────────────────────────────────────────────────┐
│                 Welcome to Grok CLI                │
├─────────────────────────────────────────────────────┤
│ Tips for getting started:                          │
│ 1. Ask questions, edit files, or run commands.     │
│ 2. Be specific for the best results.               │
│ 3. /help for more information.                     │
│ 4. Try: "Create a new Rust project structure"      │
└─────────────────────────────────────────────────────┘

Grok (grok-3) [demo | 100% context left | 0 messages] >

🤖 Automatic File Operations

NEW! Grok CLI now supports automatic file and directory creation during chat! Simply ask naturally and Grok will execute the operations for you.

Available Tools

write_file - Create or overwrite files with content
read_file - Read file contents
replace - Find and replace text in files
list_directory - List directory contents
glob_search - Find files matching patterns
save_memory - Save facts to long-term memory
run_shell_command - Execute shell commands (cargo, git, etc.)

Example Usage

# Start interactive mode
grok

# Then ask naturally:
You: Create a new Rust project with main.rs and a README
You: Write a hello world program to src/main.rs
You: Create a .gitignore file for Rust projects
You: List all .rs files in the project

How It Works

You make a request that involves file operations
Grok responds with tool calls
The CLI automatically executes them in your current directory

You see confirmation for each operation:

Grok is executing operations...
  ✓ Successfully wrote to src/main.rs
  ✓ Successfully wrote to README.md
All operations completed!

Security

All operations are restricted to your current working directory and subdirectories
No access to system files or parent directories
Tool execution requires explicit requests (not triggered by accident)



## 📦 Installation

### Prerequisites
- Rust 1.70+ (install from [rustup.rs](https://rustup.rs/))
- X/Grok API key from [x.ai](https://x.ai)

### Build from Source
```bash
git clone https://github.com/microtech/grok-cli
cd grok-cli
cargo build --release

Initialize Configuration

# Create default configuration
grok config init

# Set your API key
grok config set api_key "your-api-key-here"

Or use environment variable:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export GROK_API_KEY="your-api-key-here"
# or
export X_API_KEY="your-api-key-here"

🎯 Quick Start

Interactive Mode (Default)

# Start beautiful interactive session
grok

# Start without banner
grok --hide-banner

# Save and load sessions (NEW!)
> /save my-session
> /load my-session
> /list

# Project-specific config (NEW!)
mkdir .grok
echo 'default_temperature = 0.3' > .grok/config.toml

# Multi-editor context support (NEW!)
echo "# Gemini rules" > GEMINI.md
echo "# Claude rules" > .claude.md
mkdir .zed && echo "# Zed rules" > .zed/rules
# Grok merges ALL context files automatically!

Single Commands

# Ask a question
grok chat "Explain Rust ownership"

# Interactive chat with system prompt
grok chat --interactive --system "You are a Rust expert"

# Code operations
grok code explain src/main.rs
grok code review --focus security *.rs
grok code generate --language rust "HTTP server with error handling"

# System diagnostics
grok health --all
grok config show

🎪 Interactive Commands

Once in interactive mode, use these special commands:

| Command | Description | |---------|-------------| | /help | Show available commands | | /model [name] | Change AI model (grok-3, grok-2-latest, etc.) | | /system [prompt] | Set system prompt for specialized behavior | | /history | View conversation history | | /status | Show session information | | /clear | Clear screen and show logo | | /reset | Clear conversation history | | /quit | Exit interactive mode |

📜 Chat History Management

View and manage your conversation logs:

# List all saved chat sessions
grok history list

# View a specific session
grok history view <session-id>

# Search through all conversations
grok history search "authentication"

# Clear all chat history
grok history clear --confirm

Chat sessions are automatically logged to ~/.grok/logs/chat_sessions/ in both JSON and human-readable text formats. Configure logging behavior with environment variables:

GROK_CHAT_LOGGING_ENABLED=true              # Enable/disable logging
GROK_CHAT_LOG_DIR=/path/to/logs            # Custom log directory
GROK_CHAT_LOG_MAX_SIZE_MB=10               # Max size before rotation
GROK_CHAT_LOG_ROTATION_COUNT=5             # Number of logs to keep

See docs/CHAT_LOGGING.md for complete documentation.

⚙️ Configuration

Create ~/.config/grok-cli/config.toml:

[api]
default_model = "grok-3"
default_temperature = 0.7
timeout_secs = 30

[ui]
hide_banner = false          # Show ASCII logo
hide_tips = false           # Show helpful tips
colors = true               # Enable colored output
unicode = true              # Enable emoji and Unicode

[ui.interactive]
prompt_style = "rich"       # "simple", "rich", or "minimal"
show_context_usage = true   # Show token/context info
check_directory = true      # Warn about home directory usage
startup_animation = true    # Animate logo display

[ui.footer]
hide_cwd = false           # Show current directory
hide_model_info = false    # Show model and context usage
hide_status = false        # Show session status

[network]
starlink_optimizations = true  # Enable satellite internet optimizations
max_retries = 3               # Network retry attempts
base_retry_delay = 2          # Base delay between retries

🌐 Starlink Optimization

Grok CLI includes specialized optimizations for satellite internet users:

Smart Retry Logic - Exponential backoff with jitter
Connection Drop Detection - Recognizes satellite handoff patterns
Timeout Management - Adaptive timeouts based on connection quality
Error Recovery - Graceful handling of intermittent connectivity

🎭 Zed Editor Integration

Grok CLI supports the Agent Client Protocol (ACP) for seamless Zed editor integration.

For complete setup instructions, see ZED_INTEGRATION.md

Quick Setup

# Initialize configuration (required first)
grok config init --force

# Set your API key
grok config set api_key YOUR_API_KEY

# Test capabilities
grok acp capabilities

Recommended: STDIO Mode

Add to your Zed settings.json:

{
  "language_models": {
    "grok": {
      "version": "1",
      "provider": "agent",
      "default_model": "grok-2-latest",
      "agent": {
        "command": "grok",
        "args": ["acp", "stdio"],
        "env": {
          "GROK_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Alternative: Server Mode

# Start ACP server
grok acp server --port 3000

# Test connection
grok acp test --address 127.0.0.1:3000

Add to Zed settings.json:

{
  "language_models": {
    "grok": {
      "version": "1",
      "provider": "agent",
      "agent": {
        "endpoint": "http://127.0.0.1:3000"
      }
    }
  }
}

🎨 Customization

Available Models

grok-3 - Latest and most capable model
grok-2-latest - Previous generation model
grok-code-fast-1 - Optimized for code tasks
grok-vision-1212 - Supports image analysis

Prompt Styles

Rich - Full context with model, directory, and usage info
Simple - Clean prompt with basic info
Minimal - Just a simple arrow prompt

Color Themes

The CLI uses a professional color scheme:

🔵 Blue - Grok branding and headers
🟢 Green - Success messages and confirmations
🟡 Yellow - Warnings and important notes
🔴 Red - Errors and critical issues
🟣 Magenta - Interactive prompts and accents
🔄 Cyan - Information and tips
⚫ Dimmed - Secondary text and details

📊 Health Monitoring

Comprehensive health checks for optimal performance:

# Check everything
grok health --all

# Specific checks
grok health --api      # API connectivity
grok health --config   # Configuration validation

Health metrics include:

✅ API key validation
🌐 Network connectivity
⚡ Response latency
📊 Model availability
🔧 Configuration integrity

🚨 Troubleshooting

Common Issues

"failed to deserialize response" Error

This error has been fixed in the latest version. If you're still experiencing it:

# Rebuild the project
cargo clean
cargo build --release

# Reinitialize configuration
grok config init --force

See FIXES.md for complete details about this fix.

API Key Problems

# Verify key is set
grok config get api_key

# Set if missing
grok config set api_key YOUR_KEY

# Test connectivity
grok health --api

Network Issues

# Enable verbose logging
grok --verbose chat "test"

# Check network health
grok health --all

# Enable Starlink optimizations if needed
grok config set network.starlink_optimizations true

Configuration Problems

# Validate config
grok config validate

# Reset to defaults
grok config init --force

Zed Integration Issues

See the comprehensive troubleshooting section in ZED_INTEGRATION.md

Debug Mode

# Enable debug output
RUST_LOG=debug grok --verbose chat "test"

# For ACP/Zed debugging
RUST_LOG=debug grok acp stdio

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/microtech/grok-cli
cd grok-cli
cargo test
cargo clippy

📚 Documentation

ZED_INTEGRATION.md - Complete Zed editor integration guide
FIXES.md - Recent bug fixes and solutions
SETUP.md - Detailed setup instructions
TESTING_TOOLS.md - Testing documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by Gemini CLI for the interactive experience
Built with the Agent Client Protocol for Zed integration
Powered by X.ai Grok API for AI capabilities

📞 Support

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Contact: [email protected]

Made with ❤️ for the Rust and AI community