Website • Releases • Docs • Issues
A model-agnostic AI coding agent for the terminal. Works like Claude Code but supports any LLM provider — commercial APIs, open source models, or self-hosted instances.
npm install -g @dugleelabs/copair
copair
| Provider | Type |
|---|---|
| Anthropic (Claude) | Native |
| OpenAI (GPT-4o, o1, etc.) | Native |
| Google Gemini (incl. 2.0/3.0 thought signatures) | Native |
| Ollama, vLLM, LM Studio, etc. | OpenAI-compatible |
Switch models mid-session with /model <name>. Context is summarized automatically before switching.
Create ~/.copair/config.yaml:
version: 1
default_model: claude-sonnet
providers:
anthropic:
api_key: ${ANTHROPIC_API_KEY}
models:
claude-sonnet:
id: claude-sonnet-4-20250514
openai:
api_key: ${OPENAI_API_KEY}
models:
gpt-4o:
id: gpt-4o
ollama:
type: openai-compatible
base_url: http://localhost:11434/v1
models:
llama3:
id: llama3.1:8b
supports_tool_calling: falsecopair # start with default model
copair --model gpt-4o # start with a specific model
copair --resume # resume most recent session
copair --resume latest # same as above
copair --resume auth-fix # resume session by identifier
copair --verbose # show INFO/WARN logs
copair --debug # show all logs including DEBUG
→ Full configuration reference
→ Local models setup (Qwen 3.5, etc.)
The agent has direct access to your codebase:
| Tool | Description |
|---|---|
Read |
Read file contents with line offset/limit |
Write |
Write file contents, creates parent dirs |
Edit |
Exact string replacement (errors on non-unique match) |
Grep |
Regex search across files |
Glob |
File pattern matching |
Bash |
Execute shell commands with timeout |
Git |
git status, diff, log, commit |
WebSearch |
Search via Tavily, Serper, or SearXNG |
UpdateKnowledge |
Add entries to project knowledge base |
For models without native tool calling, Copair falls back to prompt-based tool extraction.
permissions:
mode: ask # ask | auto-approve | deny
allow_commands: # bash commands that skip the prompt
- git status
- git diff
- npm testIn ask mode you can approve once or always-allow for the session. Shell operators (;, &&, |, etc.) are never auto-approved even if the base command matches.
Run a single task non-interactively — prompt in, structured JSON result out, no TTY:
copair --headless "fix the failing test in src/foo.ts" --model qwen-7b
echo "summarize src/index.ts" | copair --headless --model qwen-7bstdout carries exactly one JSON result document; stderr carries the streaming text (unless --quiet); --events <path> writes a JSONL mechanism-event stream. The result and event shapes are committed as versioned JSON Schema under schemas/.
After each response:
[tokens: 1,234 in / 567 out | session: 5,678 in / 2,345 out | ~$0.12]
On exit, a per-model cost breakdown is shown. Supports all OpenAI, Anthropic, and Google pricing. Falls back to tiktoken estimation when the API doesn't report usage.
| Command | Description |
|---|---|
/help |
List all available commands |
/model <name> |
Switch model mid-session |
/clear |
Clear conversation history |
/cost |
Show session token usage and cost |
/workflow <name> |
Run a workflow |
/commands |
List custom commands |
/session list |
List all sessions for current project |
/session resume <id> |
Resume a previous session |
/session rename <name> |
Rename current session |
/session delete <id> |
Delete a stored session |
/session save |
Force save current session |
/session info |
Show current session metadata |
Custom commands are markdown files with frontmatter — drop them in ~/.copair/commands/ or .copair/commands/. Commands support nesting, positional arguments, and $VAR / {{var}} interpolation. They return their expanded markdown directly to the agent. → Custom commands
Sessions persist across exits. On startup, Copair checks for previous sessions in .copair/sessions/ and offers to resume or start fresh. Sessions are auto-named from your git branch, first message, and files touched.
Previous sessions:
1. auth-middleware-refactor-a3f2 (2h ago, 42 msgs, claude-sonnet)
2. fix-login-bug-b7c1 (1d ago, 18 msgs, gemini-pro)
3. Start fresh
Select [1-3]:
On exit, sessions are summarized using a local model (via Ollama if available) or the active model. Resumed sessions inject the summary as context instead of replaying full message history.
Session files are stored in .copair/sessions/ (gitignored automatically). Each session has a UUID directory containing session.json, messages.jsonl, and optionally summary.md.
# Optional session config in ~/.copair/config.yaml
context:
summarization_model: qwen-7b # model alias for summaries
max_sessions: 20 # max sessions per project
knowledge_max_size: 8192 # max bytes for knowledge baseCopair maintains a project-level knowledge base at COPAIR_KNOWLEDGE.md in your project root. The agent adds entries when it learns project-specific facts (conventions, patterns, architecture decisions). This file is committed to git and shared with your team.
The knowledge base is automatically included in the system prompt for all sessions in that project. Entries are timestamped and pruned when the file exceeds the configured max size.
Multi-step YAML workflows that combine agent prompts, shell commands, and branching logic.
/workflow test-fix
/workflow test-fix test_command=pytest
Workflows support: prompt, shell, command, condition, and output step types. Ctrl+C cancels at any step. → Workflow docs
Extend the agent with any Model Context Protocol server. MCP tools are discovered at startup and namespaced as server-name:tool-name.
mcp_servers:
- name: filesystem
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"]→ MCP docs
Supports Tavily, Serper, and self-hosted SearXNG. Anthropic models use native built-in search automatically.
web_search:
provider: tavily
api_key: ${TAVILY_API_KEY}npm (requires Node.js 20+):
npm install -g @dugleelabs/copair
Homebrew (macOS/Linux):
brew install dugleelabs/tap/copair
Standalone binary (no Node.js required):
Download the latest SEA binary for your platform from GitHub Releases:
copair-darwin-arm64(macOS Apple Silicon)copair-darwin-x64(macOS Intel)copair-linux-x64(Linux x64)
chmod +x copair-darwin-arm64
mv copair-darwin-arm64 /usr/local/bin/copairCopair includes a plugin system for extending its behavior. Plugins can intercept and modify LLM requests, observe responses, and override provider routing. The plugin API is used internally and is not yet publicly documented.
# config.yaml
plugins:
- "./my-plugin.js"
- "@scope/my-plugin-package"Copair Pro is a commercial edition built on top of the open-source core, offering additional features for teams and enterprises.
Copair exports a library API for building on top of the core:
import { bootstrapCLI, PluginManager } from '@dugleelabs/copair';
import type { CopairPlugin } from '@dugleelabs/copair';MIT