# 🚀 Recoder-Code

> **Complete AI-powered development platform** - Chat with 40+ AI models (with tool calling), build projects, and automate your workflow

[![npm version](https://img.shields.io/npm/v/recoder-code.svg)](https://www.npmjs.com/package/recoder-code)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)

## ✨ Features

- 🤖 **40+ AI Models** - Access GPT-4, Claude, Gemini, DeepSeek, Qwen, and more through OpenRouter
- 🛠️ **Tool Calling Support** - Advanced models with native function calling & agentic workflows
- 🔌 **17 Pre-configured MCP Servers** - Git, GitHub, Playwright, Filesystem, and more work out of the box
- 📁 **File Operations** - Create, edit, and manage files directly from chat
- 🔧 **Project Builder** - Build complete applications with AI assistance
- ⚡ **Fast & Free** - Multiple free models with tool support included
- 🎯 **Smart Defaults** - Works out of the box with minimal configuration
- 🔄 **Interactive Mode** - Real-time chat interface with syntax highlighting
- 🔒 **Sandbox Mode** - Optional Docker or macOS isolation for safe code execution
- 🌐 **Multi-Platform** - Windows, macOS, and Linux support

## 🚀 Quick Start

### Installation

```bash
npm install -g recoder-code
```

### Quick Setup (First-Time Users)

On first run, Recoder Code will automatically start an interactive setup wizard:

```bash
recoder-code
```

The wizard will guide you through:
- **API Key Setup**: Get a free key from [OpenRouter](https://openrouter.ai/keys) (30 seconds)
- **Model Selection**: Choose from 30+ free and premium AI models
- **Optional Settings**: Enable sandbox mode, IDE integration, etc.

That's it! You're ready to start coding with AI.

**Re-run setup anytime:**
```bash
recoder-code /setup
```

### Usage

**Interactive Mode** (recommended):
```bash
recoder-code
```

**One-shot Commands**:
```bash
# Simple query
recoder-code "create a hello world in python"

# Build a project
recoder-code "build a REST API with Express.js"

# Use specific model
recoder-code --model anthropic/claude-3.5-sonnet "analyze this codebase"
```

## 📚 Examples

### Create a Web App
```bash
recoder-code "create a todo app with React and Tailwind CSS"
```

### Analyze Code
```bash
recoder-code "review my authentication system and suggest improvements"
```

### Debug Issues
```bash
recoder-code "why is my async function not working in app.js?"
```

## 🎯 Key Commands

```bash
recoder-code                    # Start interactive chat
recoder-code --setup            # First-time configuration
recoder-code --help             # Show all options
recoder-code --list-models      # List available AI models
recoder-code --stats            # View usage statistics

# 🆕 OpenRouter Model Explorer
recoder-code --openrouter-explore                    # Explore all models with details
recoder-code --openrouter-tools                      # Find tool-capable models
recoder-code --openrouter-endpoints "model/name"     # View provider endpoints
recoder-code --openrouter-feature tools              # Filter by feature
```

## 🔌 MCP Server Integration

Recoder Code includes **17 pre-configured MCP servers** that enhance AI capabilities:

### Essential Servers (Work Out of the Box)
- **Git MCP** - Accurate git operations, eliminates hallucination
- **GitHub MCP** - Manage repos, issues, PRs without leaving your environment
- **Filesystem MCP** - Safe file operations with permission control
- **Fetch MCP** - HTTP requests and web content access
- **DuckDuckGo MCP** - Free web search, no API key required
- **GitMCP Docs** - Access documentation from any GitHub repository

### Additional Capabilities
- **Playwright & Puppeteer** - Browser automation and testing
- **PostgreSQL & SQLite** - Database operations
- **Brave Search** - Privacy-focused web search (API key needed)
- **Google Drive & Slack** - External integrations
- **Memory Bank & Knowledge Graph** - Context retention
- **Sequential Thinking** - Structured problem-solving

### View MCP Servers
```bash
recoder-code /mcp list              # Show all configured servers
recoder-code /mcp desc              # Show server descriptions
recoder-code /mcp add <name> <cmd>  # Add custom MCP server
```

**Learn more**: See [MCP Server Documentation](docs/mcp-server.md) for detailed setup and configuration.

**Quick Reference**: See [DEFAULT_MCP_SERVERS.md](DEFAULT_MCP_SERVERS.md) for complete server list and examples.



### Interactive Mode Commands

Once in interactive mode, use these commands:
- `/help` - Show all available commands
- `/model` - Switch AI models on the fly
- `/setup` - Re-configure API keys
- `/clear` - Clear conversation history
- `/stats` - View usage statistics
- `/chat save <name>` - Save conversation checkpoint
- `/approval-mode` - Change approval requirements (plan/default/auto-edit/yolo)
- `/sandbox` - Check sandbox status
- `/quit` - Exit (or use Ctrl+C)

## 🔍 OpenRouter Model Explorer (New!)

Recoder Code now includes powerful tools to explore and compare OpenRouter models:

### Explore All Models

```bash
# See all available models with detailed information
recoder-code --openrouter-explore

# Filter by category (programming, chat, etc.)
recoder-code --openrouter-explore --openrouter-category programming

# Filter by features
recoder-code --openrouter-feature tools      # Models with tool calling
recoder-code --openrouter-feature vision     # Models with image understanding
recoder-code --openrouter-feature streaming  # Models with streaming support
```

### View Provider Endpoints

Check pricing, availability, and uptime for any model:

```bash
# See all providers offering Claude
recoder-code --openrouter-endpoints "anthropic/claude-3.5-sonnet"

# Compare DeepSeek providers
recoder-code --openrouter-endpoints "deepseek/deepseek-chat-v3.1"
```

**Endpoint information includes:**
- Provider names and online status
- Real-time uptime statistics
- Pricing per million tokens (input/output)
- Context length and token limits
- Quantization details
- Supported parameters

### Find Tool-Capable Models

List all models supporting tool/function calling for agentic workflows:

```bash
recoder-code --openrouter-tools
```

### Programmatic Access

```javascript
import { getOpenRouterClient } from 'recoder-code-core';

const client = getOpenRouterClient();

// List all models
const models = await client.listModels();

// Get tool-capable models
const toolModels = await client.getModelsWithFeature('tools');

// View model endpoints
const endpoints = await client.listModelEndpoints('anthropic/claude-3.5-sonnet');
```

**Learn more:** See [OPENROUTER_FEATURES.md](./OPENROUTER_FEATURES.md) for complete documentation and examples.

## 🔧 Configuration

### First-Time Setup

When you run `recoder-code` for the first time, you'll be automatically guided through an interactive setup wizard:

1. **API Key Configuration**: Get a free key from [OpenRouter](https://openrouter.ai/keys) (takes 30 seconds)
   - Choose from OpenRouter, OpenAI, or custom provider
   - Enter your API key (stored securely in `~/.recoder-code/.env`)
   - Select your default AI model

2. **Model Selection**: Choose from 30+ models including:
   - Free models (DeepSeek, Qwen, Mistral, etc.)
   - Premium models (GPT-4, Claude, Gemini)

3. **Optional Features**: Configure sandbox mode, IDE integration, and more

Your configuration is stored securely and never published with your code.

```bash
OPENROUTER_API_KEY=sk-or-v1-...
```

### Model Selection

Recoder Code supports 30+ AI models through OpenRouter:

```bash
# List all available models
recoder-code --models

# Switch model interactively
recoder-code
> /model

# Use specific model
recoder-code --model anthropic/claude-3.5-sonnet "your prompt"
```

**Popular Free Models with Tool Calling:**
- `deepseek/deepseek-chat-v3.1:free` - Fast, excellent for coding (128K context)
- `qwen/qwen3-coder-480b-a35b:free` - 480B MoE optimized for agentic coding (262K context)
- `qwen/qwen3-235b-a22b:free` - 235B MoE with thinking mode (131K context)
- `z-ai/glm-4.5-air:free` - Lightweight MoE for agents with tool use (131K context)
- `deepseek/deepseek-v3-0324:free` - 685B MoE for complex tasks (164K context)
- `google/gemini-2.0-flash-exp:free` - Fast multimodal with function calling (1M+ context)
- `alibaba/tongyi-deepresearch-30b-a3b:free` - Optimized for research & multi-step reasoning (131K context)

**Premium Models:**
- `anthropic/claude-3.5-sonnet` - Best for complex reasoning (200K context)
- `openai/gpt-4o` - Great all-rounder with vision (128K context)
- `openai/gpt-4-turbo` - Advanced reasoning and coding (128K context)

### Sandbox Mode (Optional Security Feature)

Recoder Code includes optional **sandbox isolation** for running AI-generated code safely:

```bash
# Enable Docker sandbox (recommended)
export RECODER_SANDBOX=docker
recoder-code

# Or use macOS Seatbelt (macOS only, lightweight)
export RECODER_SANDBOX=sandbox-exec
recoder-code

# Make it permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export RECODER_SANDBOX=docker' >> ~/.bashrc
```

**Benefits:**
- 🔒 Isolates code execution from your system
- ✅ Prevents accidental system changes
- 🧪 Creates reproducible environments
- 🛡️ Adds security for untrusted code

When sandbox is enabled, you'll see `🔒 docker` or `🔒 macOS Seatbelt` in the footer instead of "💻 Interactive Mode".

**Setup Requirements:**
- Docker: Install [Docker Desktop](https://docs.docker.com/get-docker/) (all platforms)
- macOS Seatbelt: Built-in on macOS, no installation needed

See [SANDBOX_SETUP_GUIDE.md](./SANDBOX_SETUP_GUIDE.md) for detailed setup instructions.

### Advanced Options

```bash
# Use faster model
recoder-code --fast "quick question"

# Use cheapest model
recoder-code --cheap "simple task"

# Enable streaming
recoder-code --stream "long response"

# Debug mode
RECODER_DEBUG=true recoder-code "test query"
```

## 🌟 Why Recoder-Code?

- ✅ **No Configuration Hell** - Works immediately after setup
- ✅ **40+ AI Models** - Switch between free and premium models instantly
- ✅ **Tool Calling Support** - Advanced agentic workflows with function calling
- ✅ **Free Tier Available** - Use free models without a credit card
- ✅ **File Operations** - AI can create and edit files directly
- ✅ **Sandbox Mode** - Optional secure code execution with Docker
- ✅ **Session History** - Conversations are automatically saved
- ✅ **Fallback Support** - Auto-switches models if primary fails
- ✅ **Production Ready** - Used in real development workflows

## 📖 Documentation

- [Sandbox Setup Guide](./SANDBOX_SETUP_GUIDE.md) - **NEW!** Secure code execution
- [Model Selection Guide](./MODEL_SELECTION.md)
- [Interactive Guide](./INTERACTIVE_GUIDE.md)
- [Production Deployment](./PRODUCTION_GUIDE.md)
- [Contributing](./CONTRIBUTING.md)

## 🐛 Troubleshooting

### "Command not found"
```bash
npm install -g recoder-code
```

### "API Key Required"
```bash
recoder-code --setup
```

### "Module not found"
```bash
npm install -g recoder-code --force
```

## 💡 Pro Tips

1. **Use Free Models First** - DeepSeek and others are free and fast
2. **Enable Streaming** - Get responses faster with `--stream`
3. **Save Sessions** - Your chats are auto-saved in `~/.recoder-code/`
4. **Keyboard Shortcuts** - Use `Ctrl+C` to stop, `Ctrl+D` to exit
5. **Debug Mode** - Set `RECODER_DEBUG=true` for detailed logs

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

```bash
# Clone the repo
git clone https://github.com/caelum0x/recoder-code.git

# Install dependencies
npm install

# Run locally
node cli/run.js "test query"
```

## 📜 License

MIT © [Recoder Code Team](https://github.com/caelum0x)

## 🔗 Links

- [NPM Package](https://www.npmjs.com/package/recoder-code)
- [GitHub Repository](https://github.com/caelum0x/recoder-code)
- [OpenRouter (Get API Key)](https://openrouter.ai)
- [Report Issues](https://github.com/caelum0x/recoder-code/issues)

## ⭐ Star Us!

If you find Recoder-Code useful, please star the repo on GitHub! It helps others discover the project.

---

**Made with ❤️ by developers, for developers**
