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

sudocode

Overview

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 · Measured cost · Get started · Everyday workflows · Architecture · Contribute · 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.

FeatureFrom
Skills, plugins, hooks and MCP servers; reads .claude-plugin manifestsClaude Code
Sub-agents, background tasks, context inspection, compaction and resumeClaude Code
! shell commands whose output becomes part of the conversationClaude Code
Enter steers a running turn; Tab queues the next messageCodex CLI
read-only, workspace-write and danger-full-access permission modesCodex CLI
Markdown, table, code-color and Mermaid renderingCodex CLI
AGENTS.md project instructions; reads .codex-plugin manifestsCodex 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).

MetricMeasuredBudget
Peak memory (RSS)30–35 MiB80 MiB
Memory growth over 30 turns1.8 MiB16 MiB
Typing latency, key to echo (P95), including while streaming3–4 ms50 ms
CPU per turn (stream a reply while typing, pasting and resizing)0.20–0.26 s0.8 s
CPU while idle at the prompt≤ 10 ms per second—
Terminal output while idle0 bytes0 bytes
First text on screen after the model starts streaming59–78 ms3 s
Cancel, Esc to a ready prompt (P95)81 ms200 ms
Resize redraw (P95)41 ms100 ms
Paste (P95)2–3 ms100 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.

PlatformRelease architecturesInstallation options
macOSApple silicon, IntelShell installer or release archive
LinuxARM64, x64Shell installer, release archive, or Debian/Ubuntu package
WindowsARM64, x64Extract 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:

GoalCommand
Start an interactive sessionscode
Run a task and exitscode -p "Explain how authentication works in this repository"
Get one JSON result for a scriptscode -p --output-format json "Summarize the current changes"
Stream complete messages as JSON linesscode -p --output-format stream-json "Review the current diff"
Resume the most recent interactive sessionscode --resume
List saved sessionsscode --resume list
Resume a specific sessionscode --resume <session-id-or-path>
Start the ACP server over stdioscode acp
Start the browser UI and ACP WebSocket serverscode acp serve --port 8080
Inspect configurationscode config
Inspect recorded prompt-cache behaviorscode cache stats
Check for an updatescode 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

ActionDefault interactive control
Add guidance to the current taskType a message and press Enter. Delivery occurs at a safe model boundary.
Save a message for the next turnType it and press Tab; slash completion retains its Tab behavior.
Deliver pending messages nowPress Esc when messages are pending.
Cancel the current turnCtrl+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 extensionWhere to start
Repository instructionsAGENTS.md in your project; see interactive commands.
Settings, providers, and memoryGlobal ~/.nexus/sudocode/ and project .nexus/sudocode/; see directory and override rules.
Skills, plugins, and MCP toolsPlugin and skill guide.
Existing CLI tool packagesInstall 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"]
ComponentResponsibility
Sudo CodeThe agent engine, terminal interface, ACP adapter, and local shared-service lifecycle.
SudoworkA desktop UI that can use Sudo Code as an execution engine.
NexusStorage, 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:

MechanismScope
agent_spawnA model tool that delegates a child task in the current process.
agent_list and sendModel tools for discovering and messaging peer Agents. An inbox receipt confirms the write, not that a peer has acted.
Nexus ManagedAgentServiceCreates 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 renderingrust/crates/rusty-sudocode-cli/
Integrate a frontendACP, the TypeScript client, and engine-core
Change model or tool executionengine-host and the workspace map
Verify a change and open a PRRequired checks and PR workflow
Find planned work and acceptance evidenceRoadmap

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 contextUsage
Credentials, accounts, endpoints, and modelsAuthentication · Models
Approval rules, filesystem scope, and sandboxingPermissions and sandbox
Editor, browser, or application integrationACP · TypeScript client
Skills, plugins, and MCPExtensions
Shared services, Agent identity, and durable storageLocal services · Storage matrix
Container deploymentContainers
Crate responsibilities and contributor rulesRust 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.