OpenRouter Agent — Free AI Coding Assistant for VS Code

Use Claude, GPT-4o, Gemini, DeepSeek, and 300+ AI models directly in VS Code — free.
No subscription. No lock-in. Bring your own OpenRouter API key (free tier available).

The free AI coding assistant for VS Code and Cursor. Ask questions about your codebase, generate step-by-step plans, or let the Agent autonomously read files, write code, and run terminal commands — with your approval. Works with Claude, GPT-4o, Gemini, DeepSeek, and 300+ models via a single OpenRouter API key.

Why OpenRouter Agent?

Most AI coding assistants lock you into one provider, one model, and a monthly subscription. OpenRouter Agent is different:

Features

🤖 300+ AI models — Claude 3.5 Sonnet, GPT-4o, Gemini 2.0 Flash, DeepSeek, Llama, Mistral, and more. Swap models per conversation without leaving VS Code.

💸 Free models included — dozens of high-quality :free models (including openrouter/owl-alpha, google/gemini-flash, meta-llama and others) — no billing required.

🧠 Auto model routing — enable Auto mode and the extension automatically picks the best model from your pool for each message, based on mode, message type, and vision needs.

🔧 Agent mode — the AI reads your workspace files, proposes changes, and runs terminal commands. Every write and command requires your explicit approval. Destructive commands always prompt.

📋 Ask & Plan modes — read-only workspace Q&A and step-by-step planning without touching files or running commands.

📎 Image, PDF & file attachments — paste screenshots (Win+Shift+S → Ctrl+V), attach PDFs, images, or source files. Vision-capable models analyze them directly.

🗂️ @ file mentions — type @ in the composer to search and select workspace files as you type; the selected file's content is read and included automatically, and shows as a clickable teal chip in your message.

🔗 Clickable file mentions — when the AI mentions a file that exists in your workspace (e.g. agents.md), it becomes a clickable link that opens the file in a real editor tab.

📊 Live activity log — a compact, collapsible step-by-step progress panel shows exactly what the agent is doing, how long it's taken, and what files it's reading or writing — with per-type icons and a ticking elapsed timer.

✅ "Worked for X" summary — when the agent finishes, a collapsible ✓ Worked for 1:45 · 25 steps summary sits above the answer so you can audit the work.

🔒 Privacy-first — API key stored in VS Code secure storage, never in settings. File access is workspace-scoped. No telemetry.

Install

VS Code

1. Open Extensions (Ctrl+Shift+X)
2. Search OpenRouter Agent → Install

Cursor

1. Open Extensions (Ctrl+Shift+X)
2. Search OpenRouter Agent → Install — or install directly from Open VSX

Terminal

# VS Code
code --install-extension ZihadHosan.openrouter-agent

# Cursor
cursor --install-extension ZihadHosan.openrouter-agent

Manual install (.vsix or building from source) → see docs/DEVELOPMENT.md.

Quick Start

1. Install the extension and reload VS Code.
2. Set your API key — Ctrl+Shift+P → OpenRouter: Set API Key → paste a key from openrouter.ai/keys. The free tier gives you access to 50+ free models immediately.
3. Open chat — press Ctrl+Alt+L (Mac: Cmd+Alt+L), click OpenRouter in the status bar, or use the Command Palette.
4. Pick a mode and model — choose Ask, Plan, or Agent and select any model from the in-chat catalog (or use Auto to let the extension pick).

💡 New to OpenRouter? Create a free account at openrouter.ai, grab an API key, and use any :free model at zero cost.

Modes

🔍 Ask Mode

Best for explaining code, reading files, and quick answers.

• Reads and lists workspace files automatically via list_files, read_file, read_glob
• Does not write files or run terminal commands
• Great for: "explain this function", "find all API calls", "summarize this codebase"

📋 Plan Mode

Best for designing before you code.

• Produces ordered step-by-step plans with files to change and risks
• No tools run — commands are listed for you to run manually
• Great for: "plan a migration from REST to GraphQL", "how should I refactor this module"

🤖 Agent Mode

Best for multi-step autonomous work with your approval.

Default permission level: OpenRouter: Agent Permissions in the Command Palette.

Model Catalog & Auto Mode

OpenRouter Agent gives you access to 300+ models from a searchable in-chat catalog:

• Browse — search by name, filter by Free or Paid
• Pick any model for a single conversation
• Auto mode — enable at least 3 models with the teal toggles, then Enable Auto. The extension scores and picks the best model for each message (vision-aware, mode-aware)
• Per-message pricing shown in the composer footer so you always know the cost
• Balance badge shows your OpenRouter credit balance in real time

Popular free models available:

• openrouter/owl-alpha (default)
• google/gemini-2.0-flash-lite:free
• meta-llama/llama-3.3-70b-instruct:free
• deepseek/deepseek-r1:free
• mistralai/mistral-7b-instruct:free

Attachments

Attach images, PDFs, and text/code files to any message:

• Text/code files and PDFs are sent inline — the model analyzes them directly
• Images and PDFs require a vision-capable model (Claude, GPT-4o, Gemini) — or use Auto with a vision model in your pool
• In Agent mode, you can ask about other workspace files in the same conversation alongside attachments

Keyboard Shortcut

Commands

Settings

Open Settings (Ctrl+,) and search openrouterAgent.

Chat History

• Conversations save automatically across VS Code sessions
• History dropdown — switch between sessions; each session remembers its model
• + new chat — starts fresh on the default model
• Delete session or Clear current chat at any time

Frequently Asked Questions

Is OpenRouter Agent free?
Yes. The extension itself is free and open-source (MIT). You can use it at zero cost with any of the 50+ free models on OpenRouter (models with the :free suffix). Paid models (Claude, GPT-4o, Gemini Pro, etc.) cost only what you actually use — there is no subscription or monthly fee.

Does it work in Cursor IDE?
Yes. OpenRouter Agent works in both VS Code and Cursor. Install it from the VS Code Marketplace or the Cursor extension panel — setup is identical.

What AI models can I use?
Any model available on OpenRouter — 300+ models including Claude 3.5 Sonnet, GPT-4o, Gemini 2.0 Flash, DeepSeek R1, Llama 3.3, Mistral, and many more. Free models are available immediately with a free OpenRouter account.

How is Auto mode different from picking a model manually?
Auto mode scores every model in your pool for each individual message — taking into account the mode (Ask/Plan/Agent), message length, and whether you have image attachments — and routes to the best fit automatically. You build the pool; the extension decides per-message.

Is my code sent to the cloud?
Only the content you explicitly include in your message is sent to OpenRouter (and forwarded to the chosen model provider). Your API key is stored in VS Code's secure secret storage and never appears in settings or logs. File access is limited to your open workspace folder. There is no telemetry.

Can it write and run code autonomously?
In Agent mode, yes — but with mandatory approval gates. Every file write and every terminal command shows an approval card in chat that you must confirm before anything happens. Destructive commands (like rm -rf) always prompt regardless of your permission settings. You are always in control.

What is the difference between Ask, Plan, and Agent mode?
Ask reads your workspace and answers questions (read-only). Plan produces step-by-step written plans without touching any files. Agent can read, write, and run commands with your approval.

Troubleshooting

Privacy & Security

• API key: stored in VS Code secret storage — never in settings.json or logs
• File access: strictly scoped to your open workspace folder
• Writes and commands: require explicit user approval in Agent mode
• Destructive commands: always prompt, regardless of permission settings
• External links: VS Code confirm dialog before any browser opens
• No telemetry: zero analytics or tracking

Full disclosure: PRIVACY.md

Development

Building from source, F5 debug, contributor guide:

docs/DEVELOPMENT.md

Release checklist (VSIX + Marketplace publish):

docs/RELEASE.md

Changelog

CHANGELOG.md

License

MIT — see LICENSE.