sudocode
Rust-native CLI coding agent for hackers — terminal-native, pipe-composable, scrollback-safe. Built because Claude Code chose non-coders.
Automatically checked · GitHub checked 2026-11-14

Overview
Sudo Code
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 · Measured cost · Get started · Everyday workflows · Architecture · Contribute · Documentation
Design principles
Sudo Code follows two rules. Every feature and every change is judged by both.
- Take the hacker features from Claude Code and Codex CLI.
- 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 statsreports 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).
| 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
defines the workloads, and
performance-policy.json holds
the budgets. scode cache stats
shows your own prompt-cache numbers.
Get started
1. Install
On macOS or Linux:
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; 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 |
| Windows | ARM64, x64 | Extract the matching ZIP and add its directory to PATH |
Downloads are on GitHub Releases.
For an explicit per-user destination, run the downloaded script with
--prefix "$HOME/.local/bin"; --no-sudo prevents sudo use.
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:
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
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 explains
setup and runtime ownership.
Other providers, subscription tokens, proxies, and per-project accounts are
covered in authentication and models.
scode --account PROFILE --model MODEL selects a configured account and model
for one invocation.
3. Check your setup
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 <session-id-or-path> |
| 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 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 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. |
| Settings, providers, and memory | Global ~/.nexus/sudocode/ and project .nexus/sudocode/; see directory and override rules. |
| Skills, plugins, and MCP tools | Plugin and skill guide. |
| Existing CLI tool packages | Install or symlink a whole package under a config root's cli-tools/; see the package contract. |
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.
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 | 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
and deployment boundaries.
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 defines the code-level contract; the Nexus integration architecture documents transport and hosting.
Build and contribute
Use stable Rust and the build prerequisites in CONTRIBUTING.md:
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/ |
| Integrate a frontend | ACP, the TypeScript client, and engine-core |
| Change model or tool execution | engine-host and the workspace map |
| Verify a change and open a PR | Required checks and PR workflow |
| Find planned work and acceptance evidence | Roadmap |
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 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 |
| Credentials, accounts, endpoints, and models | Authentication · Models |
| Approval rules, filesystem scope, and sandboxing | Permissions and sandbox |
| Editor, browser, or application integration | ACP · TypeScript client |
| Skills, plugins, and MCP | Extensions |
| Shared services, Agent identity, and durable storage | Local services · Storage matrix |
| Container deployment | Containers |
| Crate responsibilities and contributor rules | Rust workspace · Contributing |
Browse the documentation index for the full map. Each topic guide owns its detailed configuration and behavior.
License
MIT. Contributors retain their copyright.