devorch 0.4.0__tar.gz → 0.5.0__tar.gz

devorch-0.5.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,60 @@
+name: Bug report
+description: Something is broken or behaves unexpectedly
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! **Remove API keys and other secrets** from anything you paste.
+        For security problems, do not open an issue: see SECURITY.md.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `devorch -p openai`
+        2. Type ...
+        3. See ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: DevOrch version
+      description: Output of `devorch --version` (or `pip show devorch`)
+    validations:
+      required: true
+  - type: input
+    id: provider
+    attributes:
+      label: Provider and model
+      placeholder: openai / gpt-4o
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options: [Linux, macOS, Windows, Other]
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+  - type: input
+    id: terminal
+    attributes:
+      label: Terminal
+      description: For display or input problems (e.g. iTerm2, Windows Terminal, GNOME Terminal, tmux)
+  - type: textarea
+    id: logs
+    attributes:
+      label: Output / logs
+      render: shell

devorch-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/Amanbig/DevOrch/security/advisories/new
+    about: Please report security issues privately, not as a public issue.

devorch-0.5.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Describe the use case, not just the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contribution
+      options:
+        - label: I'd be willing to open a pull request for this

devorch-0.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- What does this change and why? Link the issue it closes (Fixes #123). -->
+
+## Changes
+
+-
+
+## How it was tested
+
+<!-- Tests added/updated, and anything you ran manually. Be explicit about what you did NOT test. -->
+
+## Checklist
+
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] `pytest` passes, with tests for new behaviour (a bug fix has a test that fails without it)
+- [ ] README / `CHANGELOG.md` updated for user-facing changes
+- [ ] No secrets, personal paths or API keys in code, tests, or logs

devorch-0.5.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

{devorch-0.4.0 → devorch-0.5.0}/.github/workflows/ci.yml

@@ -1,8 +1,6 @@
 name: CI
 
 on:
-  push:
-    branches: [main]
   pull_request:
     branches: [main]
 

devorch-0.5.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.5.0
+
+A large feature release: hooks, checkpoints, project settings, image input, streaming, prompt caching,
+cost estimates, and a much more robust terminal UI.
+
+### Upgrade notes
+- **Project hooks and some project settings now need `devorch trust`.** `.devorch/hooks.yaml`, a project's
+  `mcp_servers`, permission `allow` rules and `default_mode: auto` are ignored (with a warning) until you review the
+  files and run `devorch trust`. Editing either file revokes trust.
+- **Ctrl+C no longer quits.** It cancels the current turn; press it twice at an idle prompt (or type `exit`) to quit.
+- **`/undo` now also restores files** the agent changed with `edit` / `filesystem write` (not shell commands).
+- **The REPL clears the visible screen on start** (scrollback is kept). Set `DEVORCH_NO_CLEAR=1` to disable.
+- `devorch run --mode` now defaults to the project setting, falling back to `auto`.
+- Requires `prompt_toolkit>=3.0.28`.
+
+### Added
+- **Hooks**: `PreToolUse` / `PostToolUse` shell hooks (`~/.devorch/hooks.yaml`, `.devorch/hooks.yaml`).
+- **Checkpoints**: file snapshots per turn, restored by `/undo`; `/checkpoints` lists them.
+- **Custom slash commands** from Markdown files (`~/.devorch/commands`, `.devorch/commands`) with `$ARGUMENTS`.
+- **`@file` mentions** with line ranges, directories and tab completion.
+- **Image input**: `@screenshot.png` for vision models across providers; large images are downscaled
+  (optional `devorch[images]`) and old images are pruned from context to save tokens.
+- **`--output json` / `stream-json`** for `ask` and `run`, with usage, tool calls and cost.
+- **Structured `git` tool** (status, diff, log, show, branch, switch, add, commit); no push/reset/force.
+- **Per-project settings** (`.devorch/settings.yaml`) with a trust model.
+- **Streaming** replies for every provider.
+- **Prompt caching** for Anthropic (and `anthropic/*` via OpenRouter); tests guard prompt-prefix stability so
+  OpenAI/DeepSeek/Kimi/Gemini automatic caches keep hitting.
+- **`/cost`** and cost estimates in the per-turn line, `/tokens`, the bottom bar and JSON output; prices are
+  approximate and overridable under `pricing:` in `config.yaml`.
+- **More slash commands**, matching the CLI: `/permissions allow|deny|set|reset`, `/sessions`, `/hooks`, `/trust`,
+  `/untrust`, `/exit`.
+- **`--mode` for `devorch` / `devorch chat`, and `--dangerously-skip-permissions`** on every entry point (same as
+  `--mode auto`: no prompts; dangerous-command blocks and deny rules still apply).
+- **Input surface**: open input box with a coloured mode label, `Shift+Tab` mode cycling, `Ctrl+J` newline, a
+  width-aware placeholder and bottom bar, context-usage gauge.
+
+### Fixed
+- **Anthropic: the base system prompt was overwritten** by plan-mode / loop-advisory system messages.
+- **Tool output crashed the turn** (`MarkupError`) when a command, path, result or diff contained text like `[/x]`,
+  and silently lost brackets (`app/[id]/page.tsx`, `List[int]`). Message helpers now escape their text.
+- Reading a file that merely contained `Error:` was shown as a red failure.
+- Ctrl+C inside a sub-agent was swallowed and the parent kept running.
+- The bottom toolbar re-ran `git` on every keystroke; it is now cached.
+- The bottom toolbar rendered as a bright reversed bar, and was clipped on narrow terminals, hiding the mode.
+- Saving config no longer drops a `pricing:` section.
+- The slash-command dropdown vanished when a command was fully typed (`/cost`, `/models`).
+
+### Changed
+- CI runs on pull requests only.

devorch-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+We want DevOrch to be a friendly, welcoming project for everyone, whatever their background or experience.
+
+## Our standards
+
+Expected:
+
+- Be respectful and patient, especially with people who are new.
+- Give and accept constructive feedback; critique the work, not the person.
+- Assume good faith, and ask when something is unclear.
+- Keep discussion on topic and credit other people's work.
+
+Not acceptable:
+
+- Harassment, insults, personal attacks, or discriminatory language or jokes.
+- Trolling, deliberately derailing threads, or spamming.
+- Publishing someone else's private information.
+- Any other conduct that would reasonably be considered inappropriate in a professional setting.
+
+## Scope
+
+This applies in all project spaces (issues, pull requests, discussions, commits) and when someone is
+representing the project in public.
+
+## Enforcement
+
+Maintainers may edit or remove comments, close or lock threads, and ban people who do not follow these
+standards. To report a problem privately, contact the maintainer at the address listed in the `authors`
+field of `pyproject.toml`. Reports are treated confidentially.
+
+This policy is inspired by the [Contributor Covenant](https://www.contributor-covenant.org).

devorch-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to DevOrch
+
+Thanks for helping out! DevOrch is a multi-provider AI coding assistant CLI, and contributions of all sizes
+are welcome: bug reports, docs, tests, new providers, tools and features.
+
+By participating you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). To report a security problem,
+see [SECURITY.md](SECURITY.md) instead of opening a public issue.
+
+## Getting set up
+
+```bash
+git clone https://github.com/Amanbig/DevOrch.git
+cd DevOrch
+python -m venv .venv && source .venv/bin/activate      # or: uv venv && source .venv/bin/activate
+pip install -e ".[dev]"                                 # or: uv pip install -e ".[dev]"
+
+pytest                  # the whole suite; no network or API keys needed
+ruff check .            # lint
+ruff format .           # format (CI runs `ruff format --check .`)
+devorch                 # run your working copy
+```
+
+Python 3.10+ is required; CI runs the tests on Linux, macOS and Windows for 3.10-3.13, so avoid
+platform-specific assumptions (paths, shells, terminal behaviour) and keep type hints 3.10-compatible.
+
+## Workflow
+
+1. Open an issue first for anything large, so we can agree on the approach.
+2. Create a branch per change (`feat/...`, `fix/...`, `docs/...`, `chore/...`).
+3. Keep PRs focused: one feature or fix per PR.
+4. Use clear, conventional-style commit messages (`feat(hooks): ...`, `fix(ui): ...`).
+5. Open a PR against `main`. CI must pass (lint + tests on all platforms).
+
+A good PR includes:
+
+- **Tests** for new behaviour and for the bug it fixes. A regression test should fail without your fix.
+- **Docs**: update the README for user-facing changes and add a line to `CHANGELOG.md`.
+- An honest description: what changed, why, what you did **not** test.
+
+## Where things live
+
+See [`DEVORCH.md`](DEVORCH.md) and the project structure in the README. In short: `cli/` (commands, REPL, UI),
+`core/` (agent loop, executor, hooks, memory, sessions), `providers/` (one file per LLM provider), `tools/`
+(built-in tools), `config/` (settings, permissions, project settings), `tests/`.
+
+### Adding a provider
+
+Subclass `LLMProvider` in `providers/<name>.py`, implement `generate()`, and register it in
+`providers/__init__.py`. Set the capability flags honestly: `supports_images` and `supports_streaming`
+(`generate()` then accepts `on_text` and streams deltas). OpenAI-compatible APIs can reuse `chat_create` /
+`post_chat` and `openai_user_content` from `providers/base.py`. Add tests with a mocked client.
+
+### Adding a tool
+
+Subclass `Tool` in `tools/`, give it a pydantic `args_schema`, register it in `build_tools` /
+`start_repl`, and describe what the user sees in `utils/tool_display.py`. If it changes files, make sure
+checkpoints can snapshot it (`core/checkpoints.py`). Tools that can do damage need permission handling in
+`config/permissions.py`.
+
+### Adding a slash command
+
+Add it to `SLASH_COMMANDS` in `cli/constants.py` (that feeds the dropdown and `/help`) and handle it in the
+REPL in `cli/main.py`; put non-trivial logic in `cli/repl_commands.py` so it can be tested. A test fails if a
+command appears in the dropdown without a handler.
+
+## Testing notes
+
+- Tests must not touch your real `~/.devorch`: monkeypatch `Path.home()` and the config paths (see
+  `tests/test_repl_commands.py` for a fixture).
+- Do not assert on `--help` text; it is colourised and wrapped differently per terminal. Inspect the
+  registered options instead.
+- Terminal UI behaviour (layout, colours, key bindings) is tested on a virtual terminal with
+  `tests/_screen.py` (uses `pyte`), so it can be verified without a real terminal.
+- Mock the model: provider tests use fake clients, never live APIs.
+
+## Releasing (maintainers)
+
+1. Bump the version in `pyproject.toml` **and** `cli/constants.py`, and add the `CHANGELOG.md` entry.
+2. Merge to `main`, then push a `vX.Y.Z` tag. The publish workflow builds, uploads to PyPI and creates the
+   GitHub release. Published versions cannot be reused, so double-check before tagging.

{devorch-0.4.0 → devorch-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: devorch
-Version: 0.4.0
+Version: 0.5.0
 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
@@ -26,7 +26,7 @@ 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.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
@@ -34,10 +34,14 @@ 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">
@@ -58,20 +62,6 @@ Description-Content-Type: text/markdown
 
 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.
 
-## Screenshots
-
-| Startup | Chat |
-|---------|------|
-| ![Startup](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/startup.png) | ![Chat](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/chat.png) |
-
-| Provider Selection | Model Selection |
-|--------------------|-----------------|
-| ![Providers](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/providers.png) | ![Models](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/models.png) |
-
-| Tool Execution | Terminal Session |
-|----------------|-----------------|
-| ![Tools](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/tools.png) | ![Terminal](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/terminal.png) |
-
 ## 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.
@@ -135,7 +125,8 @@ DevOrch can act on your system, not just talk about it:
 
 | Tool | What it does |
 |------|-------------|
-| `shell` | Execute commands (`git status`, `npm install`, etc.) |
+| `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 |
@@ -144,6 +135,21 @@ DevOrch can act on your system, not just talk about it:
 | `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:
@@ -198,6 +204,22 @@ prompt: |
   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:
@@ -217,6 +239,111 @@ Background processes that persist across DevOrch restarts:
 > 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
+```
+
+### 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:
@@ -253,6 +380,35 @@ 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 |
@@ -311,7 +467,35 @@ devorch memory clear            # Clear project memory
 devorch init                    # Generate or update DEVORCH.md repository instructions
 ```
 
-All non-interactive commands support `--provider`, `--model`, `--mode`, `--mcp`, and `--no-mcp`.
+### 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
 
@@ -341,13 +525,19 @@ All non-interactive commands support `--provider`, `--model`, `--mode`, `--mcp`,
 | `/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 |
+| `/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 and manage tool permission settings |
+| `/permissions` | Show permissions; change them with `/permissions allow\|deny [--session] <tool> <pattern>`, `set <tool> <allow\|deny\|ask>`, `reset` |
+| `/sessions` | `list [n]`, `show <id>`, `delete <id>` (resume with `devorch --resume <id>`) |
+| `/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
@@ -417,28 +607,21 @@ mcp_servers:
 
 ## Contributing
 
-Contributions are welcome! Here's how to get started:
+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
-# Clone and install in development mode
 git clone https://github.com/Amanbig/DevOrch.git
 cd DevOrch
 pip install -e ".[dev]"
 
-# Run linting
-ruff check .
-ruff format .
-
-# Run tests
-pytest
+ruff check . && ruff format .   # lint and format
+pytest                          # tests (no network or API keys needed)
 ```
 
-### Guidelines
-
-- Run `ruff check .` and `ruff format .` before submitting
-- Add tests for new features
-- Keep PRs focused — one feature or fix per PR
-- Update the README if adding user-facing features
+- 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
 
@@ -463,8 +646,9 @@ DevOrch/
 
 ## Roadmap
 
-- [ ] Streaming responses
-- [ ] Multi-file context awareness
+- [x] Streaming responses
+- [x] Image input
+- [x] `@file` mentions (multi-file context)
 - [ ] Plugin marketplace
 - [ ] VS Code extension
 - [ ] Agent-to-agent delegation