@dugleelabs/copair 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duglee Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+<p align="center">
+  <img src="https://assets.dugleelabs.com/Copair_Logo_cc1a297c94.png" width="160" alt="Copair Logo" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/copair"><img src="https://img.shields.io/npm/v/copair" alt="npm version"></a>
+  <a href="https://github.com/dugleelabs/copair/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/copair" alt="license"></a>
+  <a href="https://github.com/dugleelabs/copair/actions"><img src="https://img.shields.io/github/actions/workflow/status/dugleelabs/copair/pull_request.yaml?branch=main&label=CI" alt="CI"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/copair" alt="node version"></a>
+</p>
+
+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 copair
+copair
+```
+
+## Providers
+
+| 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.
+
+## Quick Setup
+
+Create `~/.copair/config.yaml`:
+
+```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: false
+```
+
+```
+copair                    # 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](docs/configuration.md)  
+→ [Local models setup (Qwen 3.5, etc.)](docs/local-models.md)
+
+## Built-in Tools
+
+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
+
+```yaml
+permissions:
+  mode: ask          # ask | auto-approve | deny
+  allow_commands:    # bash commands that skip the prompt
+    - git status
+    - git diff
+    - npm test
+```
+
+In `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.
+
+→ [Permission docs](docs/configuration.md#permission-modes)
+
+## Token Tracking
+
+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.
+
+## Slash Commands
+
+| 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](docs/commands.md)
+
+## Sessions
+
+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`.
+
+```yaml
+# 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 base
+```
+
+## Knowledge Base
+
+Copair 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.
+
+## Workflows
+
+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](docs/workflows.md)
+
+## MCP Servers
+
+Extend the agent with any [Model Context Protocol](https://modelcontextprotocol.io) server. MCP tools are discovered at startup and namespaced as `server-name:tool-name`.
+
+```yaml
+mcp_servers:
+  - name: filesystem
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+```
+
+→ [MCP docs](docs/mcp.md)
+
+## Web Search
+
+Supports Tavily, Serper, and self-hosted SearXNG. Anthropic models use native built-in search automatically.
+
+```yaml
+web_search:
+  provider: tavily
+  api_key: ${TAVILY_API_KEY}
+```
+
+→ [Web search docs](docs/web-search.md)
+
+## License
+
+MIT