Copilot

A terminal-based coding agent. It chats through any OpenRouter-compatible gateway, runs an agentic tool loop (read/write/edit files, run shell commands, inspect git diffs) with per-edit approval gating, and can index your workspace for retrieval-augmented context (vector search + BM25, merged via reciprocal-rank fusion).

Setup

1. Install dependencies:

   pip install -r requirements.txt
   

2. Copy .env.example to .env and set your OpenRouter API key:

   cp .env.example .env
   

   Get a key at https://openrouter.ai/keys. The default models are on OpenRouter's free tier, so chatting costs nothing with a valid key. Workspace indexing (/index) uses an embedding model (openai/text-embedding-3-small by default) that is not free and requires OpenRouter credits.

3. Run it:

   python main.py
   

Configuration

All settings are read from .env (see config.py for the full list and defaults) via pydantic-settings. Common overrides:

Variable	Default	Purpose
API_KEY	(empty)	OpenRouter API key (required)
BASE_URL	https://openrouter.ai/api/v1	Gateway endpoint
DEFAULT_MODEL	nvidia/nemotron-3-ultra-550b-a55b:free	Chat model
MODEL_FALLBACKS	nex-agi/nex-n2-pro:free,openrouter/free	Fallback chain on model errors
EMBED_MODEL	openai/text-embedding-3-small	Embedding model for /index
WORKSPACE	current directory	Root directory the agent operates on
VECTOR_DB_PATH	.copilot/chroma	Local Chroma vector store path

Model, API key, and workspace can also be changed at runtime with the /model, /key, and /workspace commands — these persist back to .env.

Usage

Once running, type a message to start an agent turn, or use a command:

Command	Description
/help	Show available commands
/model <name>	Switch active model
/models	List available models
/workspace <path>	Switch active workspace
/index	Index the current workspace for RAG
/key <new-key>	Rotate your API key
/trust	Toggle approve-all mode (skip per-edit confirmation)
/diff	Show git diff of files edited this session
/clear	Clear session history
/exit	Quit

Testing

pytest

tests/test_core_safety.py covers workspace sandboxing, the edit-approval flow, incremental indexing, BM25 caching, RRF merge, and gateway retry/fallback behavior.