# Sudo Code

Sudo Code

License: MIT Rust Platform: macOS, Linux, Windows Protocol: ACP

**The hacker features of Claude Code and Codex CLI, in one Rust agent that spends as little memory, CPU and tokens as possible.** Sudo Code (`scode`) reads your codebase, edits files and runs commands with the model, account and permissions you choose. Use it in a terminal, from a script, or from an editor through the **Agent Communication Protocol (ACP)**. All three share one agent engine. [Principles](#design-principles) · [Measured cost](#measured-cost) · [Get started](#get-started) · [Everyday workflows](#everyday-workflows) · [Architecture](#architecture) · [Contribute](#build-and-contribute) · [Documentation](#documentation)

Sudo Code running in a terminal

## Design principles Sudo Code follows two rules. Every feature and every change is judged by both. 1. **Take the hacker features from Claude Code and Codex CLI.** 2. **Keep performance and cost efficient to the extreme.** ### 1. Hacker features from Claude Code and Codex CLI Sudo Code takes the power-user features of both tools and runs them on any model provider. You stay in control: you choose the model, account, permissions and version, and you can interrupt any work. No feature is hidden because someone might misuse it. | Feature | From | | --- | --- | | Skills, plugins, hooks and MCP servers; reads `.claude-plugin` manifests | Claude Code | | Sub-agents, background tasks, context inspection, compaction and resume | Claude Code | | `!` shell commands whose output becomes part of the conversation | Claude Code | | Enter steers a running turn; Tab queues the next message | Codex CLI | | `read-only`, `workspace-write` and `danger-full-access` permission modes | Codex CLI | | Markdown, table, code-color and Mermaid rendering | Codex CLI | | `AGENTS.md` project instructions; reads `.codex-plugin` manifests | Codex CLI | On top of these, Sudo Code adds a provider, account or proxy per project; an ACP server with a browser UI for editors and apps; and peer Agents through Nexus. Output stays inline in your terminal, so native scrollback, pipes and tmux keep working. There is no telemetry unless you opt in. ### 2. Efficiency to the extreme Agents often run several at a time, on the same machine as a local model. Every MiB the agent holds is taken from model weights and KV cache, and every prompt token sent without a cache hit is paid for again. Sudo Code treats memory, CPU and tokens as budgets: - **Memory and CPU are gated.** Every change to the terminal interface is measured in a real terminal against a fixed baseline. It fails if it exceeds a hard ceiling or shows a statistically confident regression. - **The prompt cache stays warm.** Provider caches match only a byte-exact prefix. Each session saves its system prompt and reuses it through turns, compaction, restarts and forks; the date stays out of the system prompt, and tools keep a fixed order. Tests capture the actual outgoing requests and check that the prefix holds. - **Cost is visible.** Each turn shows its cache read and write share in the status line. `scode cache stats` reports cache reuse across sessions and classifies each cache break by cause. ## Measured cost One `scode` process, release build, on Linux CI. A scripted model streams over local HTTP, so network and model time are excluded. Each value is the median of seven paired runs; ranges span seven workloads: short and long replies, a 12 KB Markdown reply, foreground and background tasks, and a 30-turn session ([source run, 2026-10-28](https://github.com/sudoprivacy/sudocode/actions/runs/40774198468)). | Metric | Measured | Budget | | --- | ---: | ---: | | Peak memory (RSS) | 30–35 MiB | 80 MiB | | Memory growth over 30 turns | 1.8 MiB | 16 MiB | | Typing latency, key to echo (P95), including while streaming | 3–4 ms | 50 ms | | CPU per turn (stream a reply while typing, pasting and resizing) | 0.20–0.26 s | 0.8 s | | CPU while idle at the prompt | ≤ 10 ms per second | — | | Terminal output while idle | 0 bytes | 0 bytes | | First text on screen after the model starts streaming | 59–78 ms | 3 s | | Cancel, Esc to a ready prompt (P95) | 81 ms | 200 ms | | Resize redraw (P95) | 41 ms | 100 ms | | Paste (P95) | 2–3 ms | 100 ms | Startup: `scode --version` takes a median 16 ms on an Intel Mac, against 5 ms for a minimal Rust binary. Every release candidate must start in under 100 ms on Linux, macOS and Windows. Downloads are 11–17 MB per platform. Prompt cache in real use: on one maintainer's machine, 49 Anthropic sessions (6,887 requests) read 88.5% of their cached prompt tokens back from the cache and wrote only 11.5% anew. These numbers cover the `scode` process alone; the tools it runs, the model server and Nexus are measured separately. RSS includes shared pages. The [performance gate](e2e/terminal-resize/README.md#release-performance-gate) defines the workloads, and [`performance-policy.json`](e2e/terminal-resize/performance-policy.json) holds the budgets. [`scode cache stats`](CONTRIBUTING.md#measuring-prompt-cache-behaviour) shows your own prompt-cache numbers. ## Get started ### 1. Install On **macOS or Linux**: ```sh curl -fsSL https://raw.githubusercontent.com/sudoprivacy/sudocode/main/install.sh | sh ``` The installer selects the host architecture and verifies the archive's SHA-256 against the release checksum manifest. To inspect it first, download [`install.sh`](install.sh); `sh install.sh --help` lists its options. | Platform | Release architectures | Installation options | | --- | --- | --- | | macOS | Apple silicon, Intel | Shell installer or release archive | | Linux | ARM64, x64 | Shell installer, release archive, or [Debian/Ubuntu package](docs/linux-deb-install.md) | | Windows | ARM64, x64 | Extract the matching ZIP and add its directory to `PATH` | Downloads are on [GitHub Releases](https://github.com/sudoprivacy/sudocode/releases/latest). For an explicit per-user destination, run the downloaded script with `--prefix "$HOME/.local/bin"`; `--no-sudo` prevents sudo use. [Installation and updates](docs/usage.md#installation-and-updates) covers version pinning, the China mirror, and `scode update`. ### 2. Configure a model and open your project This example uses an **Anthropic API key** and the `sonnet` model alias: ```sh export ANTHROPIC_API_KEY='your-api-key' cd /path/to/your/repository scode --auth api-key --model sonnet --permission-mode workspace-write ``` Try a concrete task: > Find where requests are authenticated. Explain the flow, then add a regression > test for an expired token. This example selects `workspace-write`: file writes stay inside the workspace and shell mutations request approval. The CLI's default permission mode is `danger-full-access`. See [permissions and sandboxing](docs/permissions-and-sandbox.md) for the exact boundaries and the optional Linux sandbox. On a fresh interactive launch, choose **single-agent** or **multi-agent** mode. Single-agent mode needs no separate Nexus service. Multi-agent mode reuses a configured Nexus connection or prepares shared local services. Use `scode setup` to change that choice; [shared local services](docs/shared-services.md) explains setup and runtime ownership. Other providers, subscription tokens, proxies, and per-project accounts are covered in [authentication](docs/authentication.md) and [models](docs/models.md). `scode --account PROFILE --model MODEL` selects a configured account and model for one invocation. ### 3. Check your setup ```sh scode doctor scode --help ``` `doctor` reports configuration and authentication diagnostics; `--help` lists the current command surface. ## Everyday workflows Run these commands from the repository you want to work on: | Goal | Command | | --- | --- | | Start an interactive session | `scode` | | Run a task and exit | `scode -p "Explain how authentication works in this repository"` | | Get one JSON result for a script | `scode -p --output-format json "Summarize the current changes"` | | Stream complete messages as JSON lines | `scode -p --output-format stream-json "Review the current diff"` | | Resume the most recent interactive session | `scode --resume` | | List saved sessions | `scode --resume list` | | Resume a specific session | `scode --resume ` | | Start the ACP server over stdio | `scode acp` | | Start the browser UI and ACP WebSocket server | `scode acp serve --port 8080` | | Inspect configuration | `scode config` | | Inspect recorded prompt-cache behavior | `scode cache stats` | | Check for an update | `scode update --check` | The browser UI is at `http://localhost:8080/`; ACP WebSocket clients connect to `ws://localhost:8080/ws`. The [ACP guide](docs/acp.md) covers client integration, permissions, and session controls. ### While the agent is working | Action | Default interactive control | | --- | --- | | Add guidance to the current task | Type a message and press **Enter**. Delivery occurs at a safe model boundary. | | Save a message for the next turn | Type it and press **Tab**; slash completion retains its Tab behavior. | | Deliver pending messages now | Press **Esc** when messages are pending. | | Cancel the current turn | **Ctrl+C**, or **Esc** when no messages are pending. | The [input guide](docs/usage.md#steering-queueing-and-cancellation) explains draft preservation, queue recall and cancellation. Use `/tasks` to inspect background work and `/context` to inspect context usage. ### Bring project context and tools | Context or extension | Where to start | | --- | --- | | Repository instructions | `AGENTS.md` in your project; see [interactive commands](docs/usage.md#interactive-repl). | | Settings, providers, and memory | Global `~/.nexus/sudocode/` and project `.nexus/sudocode/`; see [directory and override rules](docs/usage.md#global-and-project-directories). | | Skills, plugins, and MCP tools | [Plugin and skill guide](docs/plugins.md). | | Existing CLI tool packages | Install or symlink a whole package under a config root's `cli-tools/`; see [the package contract](docs/usage.md#cli-packages). | CLI package discovery advertises package names and their `tools/` paths. The agent inspects and invokes existing entrypoints through its shell tool; discovery does not execute package code or turn arbitrary files into model tools. ## Architecture The terminal UI and ACP adapter share a command/event boundary. Model calls, tool execution, and session behavior live behind it. ```mermaid flowchart TB Terminal["Terminal and shell scripts"] --> CLI["scode CLI"] Clients["Editors and Sudowork"] --> ACP["ACP server: stdio / WebSocket"] Browser["Embedded browser UI"] --> ACP CLI --> Boundary["engine-core: commands and events"] ACP --> Boundary Boundary --> Engine["engine-host + runtime"] Engine --> Models["Model provider"] Engine --> Tools["File / shell tools and extensions"] Engine --> Data["Workspace and session data"] Engine -. "Shared runtime" .-> Nexus["Nexus: peers and managed Agents"] ``` | Component | Responsibility | | --- | --- | | **Sudo Code** | The agent engine, terminal interface, ACP adapter, and local shared-service lifecycle. | | **[Sudowork](https://sudowork.sudoprivacy.com)** | A desktop UI that can use Sudo Code as an execution engine. | | **Nexus** | Storage, authenticated communication, and managed runtime services for connected Agents. | Standalone `scode` works without a separate Nexus daemon. A cohosted deployment runs the engine inside `nexusd-cohost`; its storage, identity, and model-routing requirements are defined in the [Agent storage contract](docs/design/agent-context-storage-matrix.html#agent-delivery-contract) and [deployment boundaries](docs/permissions-and-sandbox.md). Delegation and peer communication have different lifetimes: | Mechanism | Scope | | --- | --- | | `agent_spawn` | A model tool that delegates a child task in the current process. | | `agent_list` and `send` | Model tools for discovering and messaging peer Agents. An inbox receipt confirms the write, not that a peer has acted. | | Nexus `ManagedAgentService` | Creates and controls independent managed Agent sessions. | The [engine boundary](rust/crates/engine-core/src/lib.rs) defines the code-level contract; the [Nexus integration architecture](https://s.shareone.vip/s/nexus-integration-architecture) documents transport and hosting. ## Build and contribute Use stable Rust and the build prerequisites in [CONTRIBUTING.md](CONTRIBUTING.md#prerequisites): ```sh git clone https://github.com/sudoprivacy/sudocode.git cd sudocode/rust cargo build --locked --release -p rusty-sudocode-cli --bin scode ./target/release/scode --help ``` The binary is `rust/target/release/scode` (`scode.exe` on Windows). Credentials are needed for live model calls; compiling the CLI does not require them. | If you want to… | Start here | | --- | --- | | Change terminal input or rendering | [`rust/crates/rusty-sudocode-cli/`](rust/crates/rusty-sudocode-cli/) | | Integrate a frontend | [ACP](docs/acp.md), the [TypeScript client](sdk/typescript/README.md), and [`engine-core`](rust/crates/engine-core/src/lib.rs) | | Change model or tool execution | [`engine-host`](rust/crates/engine-host/src/lib.rs) and the [workspace map](rust/README.md) | | Verify a change and open a PR | [Required checks](CONTRIBUTING.md#required-checks) and [PR workflow](CONTRIBUTING.md#pull-request-guidelines) | | Find planned work and acceptance evidence | [Roadmap](sudo-code-roadmap.html) | User-facing changes use real PTY workflows; rendering changes also have browser interaction and scoped performance checks. The managed acceptance hook selects applicable local checks, CI covers complementary hosts, and `main` lands through the merge queue. See the [test policy](CONTRIBUTING.md#test-policy) for details. Issues and discussion are welcome in any language. Canonical project documentation is in English. ## Documentation | You need… | Reference | | --- | --- | | Terminal usage, sessions, background tasks, and context | [Usage](docs/usage.md) | | Credentials, accounts, endpoints, and models | [Authentication](docs/authentication.md) · [Models](docs/models.md) | | Approval rules, filesystem scope, and sandboxing | [Permissions and sandbox](docs/permissions-and-sandbox.md) | | Editor, browser, or application integration | [ACP](docs/acp.md) · [TypeScript client](sdk/typescript/README.md) | | Skills, plugins, and MCP | [Extensions](docs/plugins.md) | | Shared services, Agent identity, and durable storage | [Local services](docs/shared-services.md) · [Storage matrix](docs/design/agent-context-storage-matrix.html) | | Container deployment | [Containers](docs/container.md) | | Crate responsibilities and contributor rules | [Rust workspace](rust/README.md) · [Contributing](CONTRIBUTING.md) | Browse the [documentation index](docs/README.md) for the full map. Each topic guide owns its detailed configuration and behavior. ## License [MIT](LICENSE). Contributors retain their copyright.