Metadata-Version: 2.5
Name: devorch
Version: 0.5.3
Summary: Multi-provider AI coding assistant CLI with 13+ providers
Project-URL: Homepage, https://github.com/Amanbig/DevOrch
Project-URL: Repository, https://github.com/Amanbig/DevOrch
Project-URL: Issues, https://github.com/Amanbig/DevOrch/issues
Author-email: Aman <amanpreetsinghjhiwant@outlook.com>
License: MIT
License-File: LICENSE
Keywords: ai,anthropic,assistant,claude,cli,coding,copilot,deepseek,gemini,gpt,kimi,llm,llmstudio,mistral,openai,openrouter,together
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.25.8
Requires-Dist: duckduckgo-search>=6.0.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: openai>=1.28.0
Requires-Dist: prompt-toolkit>=3.0.28
Requires-Dist: pydantic>=2.7.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich>=13.7.1
Requires-Dist: typer>=0.12.3
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pillow>=10.0.0; extra == 'dev'
Requires-Dist: pyte>=0.8.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: images
Requires-Dist: pillow>=10.0.0; extra == 'images'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">DevOrch</h1>
  <p align="center">
    A multi-provider AI coding assistant CLI — like Claude Code and Gemini CLI, but open source.
  </p>
</p>

<p align="center">
  <a href="https://pypi.org/project/devorch/"><img src="https://img.shields.io/pypi/v/devorch?color=blue&label=PyPI" alt="PyPI"></a>
  <a href="https://pypi.org/project/devorch/"><img src="https://img.shields.io/pypi/pyversions/devorch" alt="Python"></a>
  <a href="https://github.com/Amanbig/DevOrch/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Amanbig/DevOrch" alt="License"></a>
  <a href="https://github.com/Amanbig/DevOrch/stargazers"><img src="https://img.shields.io/github/stars/Amanbig/DevOrch?style=social" alt="Stars"></a>
</p>

---

DevOrch gives you a coding assistant in your terminal that can execute shell commands, edit files, search your codebase, manage terminal sessions, and remember context across conversations — powered by any of 13+ AI providers or your own local models.

## Why DevOrch?

- **Provider freedom** — Switch between OpenAI, Anthropic, Gemini, Mistral, Groq, and 8 more providers (including local models) with a single command. No vendor lock-in.
- **Actually does things** — Runs shell commands, edits files, manages background processes, searches the web. Not just a chatbot.
- **Cross-session project memory** — Per-project persistent memory system automatically recalls architecture decisions, coding preferences, and recent session milestones across sessions.
- **Loop & thrashing safeguards** — Advanced safety layer detects duplicate calls, tool oscillation, and error loops, preventing runaway token drain.
- **Full token & speed transparency** — Real-time prompt/completion token tracking, context compaction metrics, and generation speed (`tok/s`) across 13 providers.
- **Extensible** — Add custom skills as YAML files, connect MCP servers for additional tools, configure permissions per-tool.

## Quick Start

### Install

**Linux and macOS** (no Python needed; the installer sets up an isolated environment and can fetch Python itself):

```bash
curl -fsSL https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.sh | sh
```

**Windows** (PowerShell):

```powershell
irm https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.ps1 | iex
```

The installers use [uv](https://docs.astral.sh/uv/) if you have it, otherwise [pipx](https://pipx.pypa.io), otherwise a
private virtual environment (needs Python 3.10+), and as a last resort offer to install uv for you. They never use
`sudo` / administrator rights, print every command they run, and leave your `~/.devorch` config and sessions alone,
including on uninstall. Run it again any time to upgrade. Read them first if you like:
[`install.sh`](install.sh), [`install.ps1`](install.ps1).

```bash
# options (pass them after `sh -s --`)
curl -fsSL https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.sh | sh -s -- --version 0.5.3
curl -fsSL https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.sh | sh -s -- --dry-run     # show, change nothing
curl -fsSL https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.sh | sh -s -- --uninstall
```

```powershell
# options (a script block, because `| iex` cannot take parameters)
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.ps1))) -Version 0.5.3
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.ps1))) -Uninstall
```

Prefer a package manager, or want to install from source?

```bash
pipx install devorch                       # recommended if you already use pipx
uv tool install devorch                    # or uv
pip install devorch                        # into the current environment

git clone https://github.com/Amanbig/DevOrch.git
cd DevOrch && pip install -e .             # from source
```

### Run

```bash
devorch                    # Interactive setup on first run
devorch -p openai          # Use a specific provider
devorch -p local           # Use Ollama (local models)
devorch --continue         # Continue the latest conversation started in this directory (-c)
devorch --resume           # Pick a previous session from a list (this directory's first)
devorch --resume abc123    # Resume a specific session by ID
devorch --version          # Print the version (-V)
devorch doctor             # Check your setup: providers, keys, permissions, project trust, terminal

# Non-interactive (scripting / CI)
devorch ask "explain this project"
devorch ask --skill commit
devorch run review "focus on security"
devorch edit src/auth.py "add input validation"
```

On first run, DevOrch walks you through provider selection and API key setup.

## Features

### 13+ AI Providers

| Cloud | Local / Self-Hosted |
|-------|---------------------|
| OpenAI (GPT-4o, o1) | Ollama (Llama, Mistral, CodeLlama) |
| Anthropic (Claude 4, 3.5) | LM Studio (any GGUF model) |
| Google Gemini (2.0, 1.5 Pro) | Custom (vLLM, TGI, llama.cpp) |
| Groq (ultra-fast Llama, Mixtral) | |
| Mistral (Large, Codestral) | |
| Together AI, OpenRouter, GitHub Copilot, DeepSeek, Kimi | |

Switch anytime with `/providers` (interactive) or `/provider <name>` (direct).

### Built-in Tools

DevOrch can act on your system, not just talk about it:

| Tool | What it does |
|------|-------------|
| `shell` | Execute commands (`npm install`, `pytest`, etc.) |
| `git` | Structured, safe git: status, diff, log, show, branch, switch, add, commit |
| `terminal_session` | Managed background processes with optional GUI window |
| `filesystem` | Read, write, list files |
| `search` / `grep` | Find files and search contents |
| `edit` | Targeted find-and-replace edits |
| `task` | Track progress on multi-step work |
| `memory` | Persistent memory across conversations |
| `websearch` / `webfetch` | Search the web, fetch URLs |

### Streaming

Replies render live as the model generates them (a spinner shows until the first token). Every provider
streams. Streaming is only used in the interactive REPL; `ask`, `run` and `--output json` are unchanged.

### Prompt Caching (Anthropic)

With the Anthropic provider, DevOrch marks the tool definitions + system prompt and the conversation so far
as cacheable. Within a multi-step task each model call re-reads that prefix from Anthropic's cache at roughly
a tenth of the normal input price instead of paying for it again, and `/tokens` shows the cached portion.
Prompts below the model's minimum cacheable size (1024–2048 tokens) are simply not cached. The same markers
are sent for `anthropic/*` models via OpenRouter. OpenAI, DeepSeek, Kimi and Gemini 2.5 cache repeated
prefixes automatically on their side; DevOrch keeps the start of every request byte-identical (stable system
prompt, no timestamps, volatile notes last) so those caches hit, and a test guards that.

### Memory & Project Context
 
DevOrch maintains persistent memory so you never have to repeat context:
 
**1. Per-Project Memory (Cross-Session Recall)**
Stored automatically per repository in `~/.devorch/projects/<project_id>/`:
```bash
/memory                              # View active architectural decisions & session history
/memory add Use uv for package management   # Record an architectural decision
/memory pref Prefer clean async/await       # Record a coding style preference
/memory clear                        # Clear project memory for this repository
```
*Accomplishments are automatically extracted and summarized on session exit with zero raw command leakage.*

**2. Global Memory (Across All Projects)**
Stored in `~/.devorch/memory/`:
```bash
/remember I prefer tabs over spaces
/remember Use ruff for Python linting
/forget                              # Interactively choose a memory to remove
```

### Skills

Reusable prompt templates for common workflows. Use them in chat or directly from the CLI:

```bash
# In chat
/commit       # Generate a descriptive git commit
/review       # Review code changes for bugs
/test         # Run tests and analyze results
/fix          # Fix the last error
/explain      # Explain project structure
/simplify     # Simplify recent code changes

# From the terminal (non-interactive)
devorch run commit
devorch run review "focus on auth module"
devorch run test

devorch skills              # List all available skills
```

Add your own in `~/.devorch/skills/`:

```yaml
# ~/.devorch/skills/deploy.yaml
name: deploy
description: Deploy to production
prompt: |
  Run the deploy script and verify it succeeds.
  Check the deploy logs for any errors.
```

### Custom Slash Commands (Markdown)

Drop a Markdown file in `~/.devorch/commands/` (global) or `<project>/.devorch/commands/` (project;
overrides global and built-ins). The file name becomes the command:

```markdown
<!-- .devorch/commands/pr.md  →  /pr 123 -->
---
description: Review a pull request
---
Review PR $ARGUMENTS: summarize the change, then list bugs and risks.
```

`$ARGUMENTS` is replaced with whatever follows the command; without the placeholder, arguments are
appended to the prompt. Works in chat (`/pr 123`) and from the CLI (`devorch run pr 123`).

### Terminal Sessions

Background processes that persist across DevOrch restarts:

```bash
# Headless — AI monitors output
> terminal_session start command="npm run dev"
  Session 'swift-fox-a3f2' started (PID 12345)

# With GUI — user gets a visible terminal, AI can still read output
> terminal_session start command="bash" gui=true
  Session 'calm-owl-b7e1' started in visible terminal

# Check output / send input / stop
> terminal_session read session_id="swift-fox-a3f2"
> terminal_session send session_id="swift-fox-a3f2" input="rs\n"
> terminal_session stop session_id="swift-fox-a3f2"
```

### Hooks

Run your own shell commands before and after any tool call — block risky actions, auto-format, run linters.
Configure in `~/.devorch/hooks.yaml` (global) or `<project>/.devorch/hooks.yaml` (project hooks only run after `devorch trust`, since they execute shell commands):

```yaml
hooks:
  PreToolUse:
    - matcher: "shell"            # regex on tool name; omit to match all tools
      command: "./scripts/guard.sh"
  PostToolUse:
    - matcher: "edit|filesystem"
      command: "ruff format ."
      timeout: 20                 # seconds, default 30
```

The hook gets a JSON payload on stdin (`event`, `tool_name`, `tool_input`, `tool_output` for post hooks, `cwd`).
Exit `0` to continue; exit `2` to block a `PreToolUse` call (stderr is sent back to the model) or to feed
stderr back after a `PostToolUse`; any other exit code is a non-blocking warning.

### @file Mentions

Reference files or folders inline and DevOrch attaches their contents to the prompt:

```
> explain @core/agent.py
> why does @core/agent.py:100-140 loop?
> summarize @tools/
```

Mention an image (`.png`, `.jpg`, `.gif`, `.webp`; up to 5 MB) to send it to the model:

```
> why does the layout in @screenshots/bug.png look broken?
> devorch ask "describe @diagram.png"
```

Images work with OpenAI, Anthropic, Gemini, OpenRouter, Mistral, Groq, Together, GitHub Copilot, Kimi, and
local/LM Studio/custom endpoints — provided the *model* is vision-capable (otherwise the provider returns an
error). DeepSeek has no image support here, so images are dropped with a warning. Images stay in the
current session's context but are not saved to the session database.

**Token savings:** only the 2 most recent image messages are re-sent on each call; older ones become a
short text note (stored history is untouched). With Pillow installed (`pip install "devorch[images]"`),
images larger than 1568px on the long side are downscaled before sending — typically several MB down to a
few hundred KB, with no visible loss for the model.

Tab completes paths after `@`. Mentions only expand when the path exists (emails and handles are left
alone); binary files are skipped, and large files are truncated.

### Cost Estimates

`/cost` shows the estimated cost of the session per model; the per-turn line, `/tokens`, and the bottom bar show
it too, and `--output json` adds `usage.cost_usd`. Each call is priced at the model that served it, so switching
models mid-session stays correct, cached/cache-write tokens use their own rates, and sub-agent calls are included.

Prices are **approximate list prices** and go stale. Models not in the built-in table are never guessed: they show
`no price` and are left out of the total (local Ollama / LM Studio are free). Add or override prices in
`~/.devorch/config.yaml` (USD per 1M tokens; the key is matched as a prefix of the model id):

```yaml
pricing:
  claude-sonnet-4:
    input: 3.0
    output: 15.0
    cache_read: 0.30     # optional, defaults to the input price
    cache_write: 3.75    # optional, defaults to the input price
```

### Model limits, retries and turn limits

- **History budget follows the model.** Older tool output is compacted at 60% of the model's context window (never
  later than 64k tokens, since every call re-sends the history); a 128k-1M model is no longer squeezed to 16k. Models
  DevOrch doesn't know keep the conservative 16k, and local servers (Ollama, LM Studio) enforce their own context
  size, so they are treated as unknown too. The `ctx` gauge in the bottom bar follows the active model. Add or
  override windows in `~/.devorch/config.yaml` (tokens, matched as a prefix of the model id):

  ```yaml
  context_windows:
    my-fine-tune: 32000
    llama3: 4096          # your Ollama server's num_ctx
  ```
- **Output limit.** Anthropic requests use the model's own output limit (up to 64k when streaming, 16k otherwise)
  instead of a fixed 4096, and you get a warning if a reply was cut off by the limit.
- **Retries.** Rate limits (429), server errors (5xx), overloads and dropped connections are retried up to 3 times with
  backoff (honouring `Retry-After`). Nothing is retried once part of the answer has streamed, and auth or bad-request
  errors fail immediately.
- **`--max-turns N`** on `ask`, `run` and `edit` sets how many model/tool steps the agent may take (default 15, 15, 10).

### Continuing and resuming sessions

Every session remembers the directory it was started in. `devorch --continue` (`-c`) reopens the most recent
non-empty conversation from the current directory; if there is none it tells you and starts a new one. A bare
`devorch --resume` shows a picker of this directory's sessions (labelled by what you first asked) with an option to
widen it to every directory, and `/resume` does the same without leaving DevOrch. Sessions created by earlier versions have
no recorded directory, so `--continue` cannot find them, but they still appear in the picker's "all directories"
view and can be resumed by ID. `devorch sessions list --here` lists only this directory's sessions.

### Prompt Shortcuts

| Key | Action |
|-----|--------|
| `Enter` | Send |
| `Alt+Enter` / `Ctrl+J` | New line (Ctrl+J works in every terminal) |
| `Shift+Tab` | Cycle mode: ASK → AUTO → PLAN |
| `Tab` / `/` / `@` | Complete commands, skills and file paths |
| `↑` / `Ctrl+R` | Previous prompts / search history |
| `Ctrl+C` | Cancel the running turn (twice at an idle prompt to exit) |

The input sits in an open box with a quiet grey border and gutter; only the mode label is coloured (blue ASK,
amber AUTO, yellow PLAN), so the mode that decides whether tools run unasked is always visible without a loud frame.
The gutter follows multi-line and wrapped input, and the placeholder and bottom bar fit your terminal width (the
mode, model and token count are never clipped; the path, branch and key hints are dropped first on narrow terminals).

DevOrch clears the visible screen when the interactive REPL starts (your scrollback is kept). Set
`DEVORCH_NO_CLEAR=1` to turn that off.

The bottom bar shows the directory, git branch, model, mode, session tokens and how full the context window is
(`ctx 42%` — compaction starts at 100%).

### Cancelling a turn

**Ctrl+C** while DevOrch is working cancels just that turn (a running shell command is killed) and keeps
your session; any tool call that was cut short is recorded as cancelled so the conversation stays valid.
`/undo` reverts the turn's file changes. At an idle prompt, press **Ctrl+C twice** (or type `exit`) to
quit. In `ask` / `run`, Ctrl+C exits with status 130 (`--output json` reports `"error": "interrupted"`).

### Checkpoints & Undo

Before the agent modifies a file with `edit` or `filesystem write`, DevOrch snapshots the original.
`/undo` removes the last turn from the conversation **and restores those files** (files the agent
created are deleted). `/checkpoints` lists what changed per turn. Changes made through `shell`
commands are not tracked.

### MCP (Model Context Protocol)

Extend DevOrch with external tool servers:

```yaml
# ~/.devorch/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "ghp_xxx"
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
```

MCP tools appear alongside built-in tools automatically.

**Manage MCP servers live in chat:**

```
/mcp                          # Show connected servers and their tools
/mcp add github npx -y @modelcontextprotocol/server-github
/mcp start github             # Reconnect a server from config
/mcp stop github              # Disconnect and remove its tools
```

**Filter MCP servers per CLI run:**

```bash
devorch ask --mcp github "review open PRs"   # Use only the github server
devorch ask --mcp github --mcp filesystem "..."  # Use specific servers
devorch run commit --no-mcp                  # Skip MCP entirely
```

### Project Settings

Commit shared defaults to your repo in `<project>/.devorch/settings.yaml`:

```yaml
default_mode: ask                 # ask | auto | plan
default_provider: anthropic
providers:
  anthropic:
    default_model: claude-sonnet-4-20250514
mcp_servers:                      # merged over ~/.devorch/config.yaml
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
permissions:
  shell:
    allow: ["pytest*", "ruff *"]
    deny: ["git push*"]
```

Precedence: CLI flags > project settings > `~/.devorch/config.yaml`. The file is found from the current
directory upward. API keys are never read from it, and project values are never written back to your
global config.

**Trust:** a cloned repo must not be able to grant itself power. Project `hooks.yaml` is covered too and is ignored until trusted. Without trust, `deny` rules, provider/model
and `default_mode: ask|plan` apply, but `mcp_servers`, `allow` rules, `default_mode: auto` and project hooks are ignored
(you get a warning). Review the files and run `devorch trust` to enable them; trust is tied to a hash of
`settings.yaml` + `hooks.yaml`, so any change to either needs `devorch trust` again. `devorch untrust` revokes it.

### Modes

| Mode | Behavior |
|------|----------|
| **ASK** (default) | Asks permission before each tool execution |
| **AUTO** | Executes tools automatically (dangerous commands still blocked) |
| **PLAN** | Shows a plan before executing, asks for approval |

### Permission System

Fine-grained control over what DevOrch can do:

```bash
devorch permissions list                    # View current rules
devorch permissions set shell allow         # Always allow shell
devorch permissions allow shell "git *"     # Allow specific patterns
devorch permissions deny shell "rm -rf *"   # Block dangerous commands
```

Or use `/auth` in-chat to set API keys without restarting.

## Non-Interactive CLI Commands

DevOrch works as a scriptable CLI too — no REPL needed:

```bash
# Ask a one-shot question
devorch ask "what does this codebase do?"
devorch ask --skill review "focus on security"
devorch ask --mode plan "refactor the auth module"

# Run a skill directly (shorthand for ask --skill)
devorch run commit
devorch run test "only unit tests"
devorch run review --no-mcp

# Edit a file with an instruction
devorch edit src/auth.py "add input validation to login"
devorch edit README.md "update the installation section"
devorch edit app/models.py "add created_at field" --mcp sqlite

# List available skills
devorch skills

# Browse providers and models directly from terminal
devorch providers               # View all 13 providers & configuration status
devorch models                  # View models for active provider
devorch models anthropic        # View models for a specific provider

# Inspect or manage project memory
devorch memory                  # View project decisions and recent accomplishments
devorch memory add "Use pytest" # Record a decision from the terminal
devorch memory clear            # Clear project memory

# Repository initialization
devorch init                    # Generate or update DEVORCH.md repository instructions
```

### Machine-readable output

```bash
devorch ask --output json "list the TODOs in this repo" | jq .result
devorch run review --output stream-json    # NDJSON: one event per tool call, then the result
```

With `--output json` stdout contains a single JSON object (`result`, `is_error`, `error`, `provider`,
`model`, `duration_ms`, `usage`, `tool_calls`); UI output goes to stderr and the exit code is non-zero
on failure, so it is safe to use in scripts and CI. `stream-json` emits `tool_call` events as they happen
followed by a final `result` event. Available on `ask` and `run`.

All non-interactive commands support `--provider`, `--model`, `--mode`, `--mcp`, `--no-mcp` and
`--dangerously-skip-permissions`. `devorch` / `devorch chat` take `--mode` and `--dangerously-skip-permissions`
too, so you can start the REPL in a given mode.

### Skipping permission prompts

```bash
devorch --dangerously-skip-permissions        # start the REPL in AUTO mode
devorch ask --dangerously-skip-permissions "run the tests and fix failures"
devorch --mode plan                           # or start in plan / ask mode
```

`--dangerously-skip-permissions` is the same as `--mode auto`: **no prompts at all**, so the agent can edit files
and run commands unasked. It is not a full bypass: the built-in dangerous-command blocks (`rm -rf *`, `sudo`, ...)
and your own `deny` rules still apply, and project hooks still run. It conflicts with `--mode ask|plan`, and it
overrides a project's `default_mode`. In the REPL, `/auto` and `/ask` switch the same behaviour on and off, and
`/permissions allow --session shell pytest*` skips prompts for just one kind of command.

## All Slash Commands

| Command | Description |
|---------|-------------|
| `/help` | Show categorized commands and shortcuts |
| `/mode [plan\|auto\|ask]` | Show or switch execution mode |
| `/plan` `/auto` `/ask` | Quick switch execution mode |
| `/models` | Search and browse models with 15/page pagination |
| `/model <name>` | Switch model directly or launch search |
| `/providers` | Search and browse providers with interactive pagination |
| `/provider <name>` | Switch provider directly or launch search |
| `/tokens` | Show session token usage, prompt/completion split, and costs |
| `/copy` | Copy last assistant response directly to clipboard |
| `/paste` | Enter multi-line paste mode for large text or code (`Alt+Enter` also inserts newlines) |
| `/status` | Show current provider, model, execution mode, and loaded context |
| `/auth [provider]` | Set or update API key for any provider |
| `/memory` | Show project memory (`/memory add <dec>`, `/memory pref <p>`, `/memory clear`) |
| `/remember <text>` | Save a note or convention to global memory |
| `/forget` | Delete a global memory interactively or by query |
| `/init` | Generate or update a `DEVORCH.md` project context file |
| `/skills` | List available skills |
| `/skill <name>` | Run a skill directly |
| `/commit` `/review` `/test` `/fix` `/explain` `/simplify` | Skill shortcuts |
| `/session` | Current session ID, model, and message count |
| `/history` | Full conversation history in this session |
| `/clear` | Clear history (saves accomplishments to project memory) |
| `/compact` | Summarize and compact conversation history to save tokens |
| `/save` | Save conversation history to a file |
| `/undo` | Undo last message and agent turn, restoring any files it edited |
| `/checkpoints` | List files changed by the agent this session, per turn |
| `/mcp` | Show MCP server status |
| `/mcp add <name> <cmd> [args]` | Connect a new MCP server mid-session |
| `/mcp start <name>` | Reconnect a server from config |
| `/mcp stop <name>` | Disconnect a server and remove its tools |
| `/config` | Show configuration settings |
| `/permissions` | Show permissions; change them with `/permissions allow\|deny [--session] <tool> <pattern>`, `set <tool> <allow\|deny\|ask>`, `reset` |
| `/sessions` | `list [n] [here]`, `show <id>`, `delete <id>` |
| `/resume` | Switch to another saved session (`/resume` opens a picker, `/resume <id>` goes straight to it) |
| `/doctor` | Check your setup (same as `devorch doctor`) |
| `/hooks` | Show active hooks and whether project hooks are trusted |
| `/trust` / `/untrust` | Trust (or stop trusting) this project's `.devorch` settings and hooks |
| `/cost` | Estimated session cost per model |
| `/exit` | Exit DevOrch (also `exit`, `quit`, or Ctrl+C twice) |
| `/tasks` | Show multi-step task list and execution progress |

## Configuration

### API Keys

```bash
# Secure keychain storage
devorch set-key openai
devorch set-key anthropic

# Or in-chat
/auth openai

# Or environment variables
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=...
export GROQ_API_KEY=gsk_...
export MISTRAL_API_KEY=...
export OPENROUTER_API_KEY=sk-or-...
export TOGETHER_API_KEY=...
export GITHUB_TOKEN=ghp_...
export DEEPSEEK_API_KEY=sk-...
export MOONSHOT_API_KEY=sk-...
```

### Config File

```yaml
# ~/.devorch/config.yaml
default_provider: openai

providers:
  openai:
    default_model: gpt-4o
  anthropic:
    default_model: claude-sonnet-4-20250514
  custom_vllm:
    default_model: meta-llama/Meta-Llama-3-70B-Instruct
    base_url: http://localhost:8000/v1

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "ghp_xxx"
```

### Directory Layout

```
~/.devorch/
├── config.yaml          # Provider settings, MCP servers
├── permissions.yaml     # Tool permission rules
├── sessions.db          # Chat history (SQLite)
├── memory/              # Persistent memories
│   ├── MEMORY.md
│   └── *.md
├── skills/              # Custom skill definitions
│   └── *.yaml
└── sessions/            # Terminal session logs
    ├── registry.json
    └── *.log
```

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide (setup, workflow, how to add a
provider, tool or slash command, testing notes). The short version:

```bash
git clone https://github.com/Amanbig/DevOrch.git
cd DevOrch
pip install -e ".[dev]"

ruff check . && ruff format .   # lint and format
pytest                          # tests (no network or API keys needed)
```

- Keep PRs focused: one feature or fix per PR, with tests, and update the README/CHANGELOG for user-facing changes
- Please follow the [Code of Conduct](CODE_OF_CONDUCT.md)
- Security issues: report them privately, see [SECURITY.md](SECURITY.md)

### Project Structure

Everything installs as one `devorch` package (`python -m devorch` is the same as the `devorch` command):

```
DevOrch/
├── devorch/
│   ├── __init__.py       # __version__ (the single source of the version)
│   ├── __main__.py       # python -m devorch
│   ├── cli/
│   │   ├── main.py       # App wiring, REPL, sessions/config commands
│   │   ├── constants.py  # banners, slash-command registry, styles
│   │   └── commands/     # ask, run, edit and shared helpers
│   ├── core/             # Agent, executor, memory, MCP, skills, modes, sessions
│   ├── config/           # Settings, permissions, project settings
│   ├── providers/        # AI provider implementations
│   ├── tools/            # Built-in tools (shell, edit, search, git, ...)
│   ├── schemas/          # Data models
│   └── utils/            # Logging, display helpers
├── tests/                # Test suite
├── scripts/              # Developer scripts (not installed)
└── docs/
```

## Roadmap

- [x] Streaming responses
- [x] Image input
- [x] `@file` mentions (multi-file context)
- [ ] Plugin marketplace
- [ ] VS Code extension
- [ ] Agent-to-agent delegation

## Requirements

- Python 3.10+
- Works on Linux, macOS, and Windows

## License

[MIT](LICENSE)

---

<p align="center">
  Built by <a href="https://github.com/Amanbig">Aman</a> — star the repo if you find it useful!
</p>
