A multi-provider AI coding assistant CLI — like Claude Code and Gemini CLI, but open source.
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.
- 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.
Linux and macOS (no Python needed; the installer sets up an isolated environment and can fetch Python itself):
curl -fsSL https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.ps1 | iexThe installers use uv if you have it, otherwise pipx, 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.ps1.
# options (pass them after `sh -s --`)
curl -fsSL https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.sh | sh -s -- --version 0.5.4
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# options (a script block, because `| iex` cannot take parameters)
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.ps1))) -Version 0.5.4
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Amanbig/DevOrch/main/install.ps1))) -UninstallPrefer a package manager, or want to install from source?
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 sourcedevorch # 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.
The extension in vscode-extension/ puts DevOrch in the side bar: chat with Ask / Auto /
Plan modes (Ask confirms each edit or command in the panel), / skills and commands, @ file suggestions, and your
conversations for the open folder. It needs the devorch command, so install that first. Install the .vsix from the
latest release (Extensions → ⋯ → Install from VSIX).
| 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).
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 |
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.
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.
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>/:
/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 repositoryAccomplishments are automatically extracted and summarized on session exit with zero raw command leakage.
2. Global Memory (Across All Projects)
Stored in ~/.devorch/memory/:
/remember I prefer tabs over spaces
/remember Use ruff for Python linting
/forget # Interactively choose a memory to removeReusable prompt templates for common workflows. Use them in chat or directly from the CLI:
# 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 skillsAdd your own in ~/.devorch/skills/:
# ~/.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.Drop a Markdown file in ~/.devorch/commands/ (global) or <project>/.devorch/commands/ (project;
overrides global and built-ins). The file name becomes the command:
<!-- .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).
Background processes that persist across DevOrch restarts:
# 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"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):
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 30The 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.
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 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):
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-
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
ctxgauge 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):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 Nonask,runandeditsets how many model/tool steps the agent may take (default 15, 15, 10).
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.
| 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%).
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").
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.
Extend DevOrch with external tool servers:
# ~/.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:
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 entirelyCommit shared defaults to your repo in <project>/.devorch/settings.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.
| 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 |
Fine-grained control over what DevOrch can do:
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 commandsOr use /auth in-chat to set API keys without restarting.
DevOrch works as a scriptable CLI too — no REPL needed:
# 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 instructionsdevorch 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 resultWith --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.
ask can keep a conversation going across runs, which is how the VS Code extension chats:
devorch ask --save-session --output json "start by reading the auth module" # result includes "session_id"
devorch ask --resume <session_id> "now add a test for the login path"
devorch ask --continue "and the logout path" # the latest session in this directory
devorch sessions list --here --output json # id, title, provider, model, messages, updated_at
devorch sessions messages <session_id> # the conversation as JSON
devorch skills --output json # name, description, sourceA resumed session keeps its own provider and model unless you pass --provider / --model. Sessions made this
way show up in devorch --resume too.
--approvals stdio (with --output stream-json) is for editors that show their own permission prompt. DevOrch
writes {"type": "permission_request", "id": 1, "tool": "shell", "command": "...", "reason": null} and waits for
{"id": 1, "choice": "once|session|always|deny"} on stdin; no answer means deny. Use it with --mode ask.
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.
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.
| 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 |
# 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-...# ~/.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"~/.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
Contributions are welcome! See CONTRIBUTING.md for the full guide (setup, workflow, how to add a provider, tool or slash command, testing notes). The short version:
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
- Security issues: report them privately, see SECURITY.md
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
├── vscode-extension/ # The VS Code extension (TypeScript)
├── install.sh # One-line installers (Linux/macOS, Windows)
├── install.ps1
├── tests/ # Test suite
├── scripts/ # Developer scripts (not installed)
└── docs/
- Streaming responses
- Image input
-
@filementions (multi-file context) - Plugin marketplace
- VS Code extension
- Agent-to-agent delegation
- Python 3.10+
- Works on Linux, macOS, and Windows
Built by Aman — star the repo if you find it useful!