DevOrch

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.

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

# Recommended
pipx install devorch

# Or with pip
pip install devorch

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

Run

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>/:

/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/:

/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:

# 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/:

# ~/.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:

<!-- .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:

# 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):

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):

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

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:

# ~/.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 entirely

Project Settings

Commit 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.

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:

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:

# 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

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

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

# 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

# ~/.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 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

Project Structure

DevOrch/
├── cli/
│   ├── main.py           # App wiring, REPL, sessions/config commands
│   ├── constants.py      # VERSION, banners, slash-command registry, styles
│   └── commands/
│       ├── _shared.py    # Shared helpers (agent builder, tool setup, etc.)
│       ├── ask.py        # devorch ask
│       ├── run.py        # devorch run
│       └── edit.py       # devorch edit
├── core/             # Agent, executor, memory, MCP, skills, modes
├── config/           # Settings, permissions
├── providers/        # AI provider implementations
├── tools/            # Built-in tools (shell, edit, search, etc.)
├── schemas/          # Pydantic models
├── utils/            # Logging, display helpers
└── tests/            # Test suite

Roadmap

• Streaming responses
• Image input
• @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

---

Built by Aman — star the repo if you find it useful!