vmCode

A CLI-based AI coding assistant capable of codebase search, file editing, computer use, and web search.

Features

• Multiple LLM Provider Support: OpenAI, Anthropic, OpenRouter, GLM, Gemini, Kimi, MiniMax, and local models
• Tool-Based Interaction: Code search (rg), file editing, directory operations, and web search
• Multiple Modes: Edit (full access), Plan (read-only), and Learn (documentation style)
• Parallel Execution: Run multiple tools concurrently for efficiency
• Conversation History: Markdown logging with context compaction
• Approval Workflows: Safety checks for dangerous commands

vmCode Free Tier

The vmcode_free provider is included as a convenient default option for new users. It uses free LLM models with no API key required.

How It Works

When using vmcode_free, your conversations are routed through vmCode's proxy server to access free LLM models:

• All chat messages, code snippets, and file content are sent to the proxy
• The proxy forwards requests to the underlying LLM provider
• This enables free access without requiring individual API keys

Use Cases

• Quick testing - Try vmCode immediately without configuration
• Evaluation - Test the tool before committing to a paid provider
• Development - Non-sensitive work where convenience is preferred

Recommended Setup

For production work or sensitive code, we recommend using other providers. Type /provider to see all options

Installation

Option 1: npm install (Recommended)

# Install globally (requires Python 3.9+)
npm install -g vmcode-cli

# Run vmcode
vmcode

Or use npx without installing:

npx vmcode-cli

What Gets Installed

The npm package automatically:

1. Checks for Python 3.9+ on your system
2. Installs Python dependencies via pip
3. Creates config.yaml from config.yaml.example if missing
4. Sets up the vmcode command globally

Requirements:

• Node.js 14+ (for npm)
• Python 3.9+ (for the application)
• pip (to install Python dependencies)

If Python is not found, the installer will guide you through installing it.

Option 2: Git Clone

# Clone the repository
git clone https://github.com/vincentm65/vmCode-CLI.git
cd vmCode-CLI

# Install Python dependencies
pip install -r requirements.txt

# Run vmcode
python src/ui/main.py

Requirements:

• Python 3.9+
• pip (to install Python dependencies)

Configuration

Setting API Keys

You have three options to set your API keys:

Option 1: Interactive Commands (Recommended)

Run the app and use the built-in commands:

> /key sk-your-api-key-here
> /provider openai

Option 2: Edit config.yaml Directly

Edit config.yaml in the project root and add your keys:

# OpenAI
OPENAI_API_KEY: "sk-your-key-here"
OPENAI_MODEL: gpt-4o-mini

# Anthropic (Claude)
ANTHROPIC_API_KEY: "sk-ant-your-key-here"
ANTHROPIC_MODEL: claude-3-5-sonnet-20241022

# Or any other supported provider...

Note: config.yaml is automatically created from config.yaml.example on first run and is in .gitignore to protect your secrets.

Option 3: Environment Variables

Set environment variables (they take precedence over config.yaml):

export OPENAI_API_KEY="sk-your-key-here"
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

vmcode

Available Environment Variables

• ANTHROPIC_API_KEY - Anthropic (Claude) API key
• OPENAI_API_KEY - OpenAI API key
• GLM_API_KEY - GLM (Zhipu AI) API key
• GEMINI_API_KEY - Google Gemini API key
• OPENROUTER_API_KEY - OpenRouter API key
• KIMI_API_KEY - Kimi (Moonshot AI) API key
• MINIMAX_API_KEY - MiniMax API key

Commands

• /provider <name> - Switch LLM provider
• /model <name> - Set model for current provider
• /key <api_key> - Set API key for current provider
• /mode <edit|plan|learn> - Switch interaction mode
• /config - Show all configuration settings
• /help - Display all available commands

/help Menu:

Project Structure

vmCode-CLI/
├── bin/
│   ├── npm-wrapper.js  # npm entry point
│   ├── rg              # ripgrep binary (Linux/macOS)
│   └── rg.exe          # ripgrep binary (Windows)
├── config.yaml         # Your API keys and settings (not in git)
├── config.yaml.example # Configuration template
├── requirements.txt    # Python dependencies
├── package.json        # npm package definition
├── .npmignore          # npm package exclusions
├── .gitignore          # git exclusions
├── src/
│   ├── core/           # Core orchestration and state management
│   ├── llm/            # LLM client and provider configurations
│   ├── ui/             # CLI interface and commands
│   └── utils/          # Utilities (file ops, search, validation)
└── tests/              # Test suite (for development)

Security

• config.yaml is excluded from git via .gitignore
• Never commit API keys or sensitive configuration
• Use environment variables for CI/CD or shared environments

Development

vmCode is currently in active development. Production readiness is in progress with focus on:

• Comprehensive test coverage
• Documentation
• Error handling improvements
• Performance optimizations