EVA-CLI

AI-powered terminal assistant with intelligent text editing and comprehensive tool integration. Talk to AI, edit files, browse the web, and automate tasks directly from your terminal.

Quick Start

1. Install

npm install -g eva-prompt

2. Setup

eva setup

Follow the prompts to add your AI provider API key (Claude, GPT-4, Gemini, etc.)

3. Start Chatting

eva

That's it! EVA will automatically configure essential tools like file operations, git, web browsing, and more.

Basic Usage

Chat Commands

eva                          # Start interactive chat
eva -m claude-4-sonnet      # Use specific AI model
eva -d /path/to/project     # Set working directory

In-Chat Commands

/models                     # Switch AI providers
/tools                      # View available tools  
/clear                      # Clear chat history
/help                       # Show all commands

What's Included

EVA comes pre-configured with powerful tools:

• File Operations - Read, write, search, edit files
• Git Integration - Commit, push, branch, merge
• Web Browsing - Playwright browser automation (default), search, scrape, interact with websites
• Code Search - Fast project-wide code search
• Memory - Remember conversation context
• Desktop Automation - Control your Mac/Windows desktop
• Database Tools - Query SQLite, PostgreSQL

AI Providers

EVA supports all major AI providers:

• Claude (Anthropic) - Best for coding and analysis
• GPT-4 (OpenAI) - General purpose excellence
• Gemini (Google) - Multimodal capabilities
• Grok (X.AI) - Real-time web knowledge
• Local Models (Ollama) - Private, offline AI

Set your API key:

export ANTHROPIC_API_KEY="your-key"
# or use: eva setup

Examples

Analyze Code

> help me understand this codebase
> what are the main components?
> suggest improvements to the auth system

Edit Files

> create a new React component for user profiles
> add error handling to the API calls
> refactor this function to be more readable

Git Automation

> review my changes and commit with a good message
> /commit-and-push

Web Research

> search for the latest React best practices
> summarize this documentation page

🧪 Testing Chain-of-Tools (REAL Implementation)

EVA now includes a production-ready Chain-of-Tools system that uses actual PyTorch weights from trained models. No more fake random numbers!

Quick Test

# Test if your Chain-of-Tools is using REAL weights
npx tsx examples/test-cotools-real.ts

Expected Results:

• ✅ PASSED = Using real trained weights (production-ready!)
• ❌ FAILED = Need to train a model first
• 💥 CRASHED = Environment setup issue

Train Your Model First

# Train a Chain-of-Tools model
eva cotools train --model 4B --epochs-judge 3 --epochs-retriever 5

# Train different sizes
eva cotools train --model 8B --epochs-judge 5 --epochs-retriever 10
eva cotools train --model 14B --epochs-judge 3 --epochs-retriever 5

Test Different Model Sizes

The system automatically tests multiple Qwen3 model configurations:

• 4B: 2560 hidden dimensions, 512 intermediate
• 8B: 4096 hidden dimensions, 1024 intermediate
• 14B: 5120 hidden dimensions, 1536 intermediate
• 32B: 6144 hidden dimensions, 2048 intermediate

What Gets Tested

1. PyTorch Bridge - Real model loading from checkpoints
2. Weight Validation - Architecture matches Qwen3 specs
3. Tool Judge - Equation 3 from CoTools paper (real neural inference)
4. Tool Retriever - Equations 6-8 from CoTools paper (real similarity)
5. Hidden States - Authentic Qwen3 representations (no simulation)

Architecture Validation

The test verifies your model has the correct weight structure:

✅ judge.W_gate: 2560x512 validated
✅ judge.W_up: 2560x512 validated  
✅ judge.W_down: 512x1 validated
✅ query.W_gate: 2560x256 validated
✅ shared.W_dim: 2560 elements validated

Troubleshooting

No trained weights found:

eva cotools train --model 4B --epochs-judge 3

PyTorch/transformers missing:

pip install torch transformers

Architecture mismatch:

• Check model was trained with correct Qwen3 configuration
• Verify hidden dimensions match your model size

Your Chain-of-Tools system will only use real trained weights - no fallbacks to random numbers!

🔧 Advanced Configuration

Environment Variables

# AI Providers
export ANTHROPIC_API_KEY="sk-ant-your-key"
export OPENAI_API_KEY="sk-your-key"  
export GOOGLE_API_KEY="your-key"
export GROK_API_KEY="your-key"

# Optional Integrations
export GITHUB_TOKEN="ghp_your_token"      # GitHub integration
export BRAVE_API_KEY="your-key"           # Web search
export DATABASE_URL="postgresql://..."    # Database access

Tool Management

# Add specific tools
eva mcp add github
eva mcp add brave_search
eva mcp add postgres

# View tool status  
eva mcp list
eva mcp test github

# Provider-optimized setup
eva mcp setup --provider anthropic

Local AI with Ollama

# Install Ollama from ollama.ai
eva ollama download qwen3:8b
eva -m qwen3:8b

Custom Instructions

Create .eva/EVA.md in your project:

# Instructions for EVA

Use TypeScript for new files.
Follow the existing code style.
Add tests for new features.

Hyperspace Network

Access distributed AI models:

eva setup --hyperspace-enable

🆘 Need Help?

• Setup Issues: Run eva setup again
• Tool Problems: Check /tools or eva mcp list
• API Errors: Verify your API keys with /api-keys
• Documentation: See MCP_SETUP_GUIDE.md

📚 Links

• Full Documentation
• MCP Setup Guide
• Examples

EVA-CLI: AI-powered productivity in your terminal 🚀