Built because Claude Code chose non-coders.

There was a time when Claude Code was a real coding agent — opinionated, fast, debuggable. The pivot toward onboarding the 99% changed that: hidden options because "users might misclick", forced auto-updates overriding pinned versions, new surface shipping while core surface stayed broken, heavy-user issues going unanswered.

Sudo Code is what happens when a heavy user gives up asking and starts building.

Rust-native CLI. Inline only — never hijacks your terminal. Pipe-composable — works with your shell, doesn't replace it. Model-agnostic — your subscription, your choice. Open source — your fork, your call.

Every row is a productivity differentiator, not a status one. The left column pushes productivity further by engineering the interaction; the right column saves cognitive load by trusting the tool. Sudo Code optimizes the first axis — which is why we expose full process by default. Not for staring. For scan-and-catch when something is off, and zero ceremony when it's not.

The end-state of this workflow is one heavy user shipping at the productivity of a small team. The arc looks like 1 session → 7-10 parallel sessions → copilot-worker fleets of 100+ agents. At stage 1 you drive one agent. At stage 2 you parallelise long unattended tasks — until mental bandwidth caps around ten. At stage 3 a copilot agent reviews worker agents; you supervise the copilot, the copilot does the per-agent direction, and the fleet scales past anything one person could track. Sudo Code is the agent unit at every stage. The collaboration plane that makes stage 3 real is described in Position in the larger picture below.

If the right column is you, this isn't your tool — and that's not a problem to solve. Claude Code, Cursor, GitHub Copilot are excellent for the 99%; use those. Sudo Code is opinionated against the right column on purpose. We don't ship modes that bridge the gap, and we don't apologize for that.

Two columns: what we'll always do, what we'll never do. These aren't aspirations — they're constraints that shape every PR.

Sudo Code is a unit, not a hub. It plugs into a larger collaboration plane through one shared primitive: the chat-with-me mailbox on the nexus VFS. Orchestration, multi-agent UI, fleet management — none of that is our job. Sudo Code is the well-behaved agent unit that other surfaces can drive: a human in a sudowork chat, a hydra-style orchestrator, another sudocode running as copilot, a peer agent like Claude or Codex on ACP. Same primitive, same plane.

flowchart LR
    subgraph Orch["Orchestrator — NOT sudocode<br/>(sudowork main · hydra UI)"]
      O["ManagedAgentService<br/>start_session_v1 · cancel · get_session"]
    end

    subgraph Units["Agent units — sudocode is one of these"]
      direction TB
      H["👤 human"]
      SC["scode pid<br/>copilot OR worker role"]
      CL["claude pid (via ACP)"]
      CX["codex pid (via ACP)"]
    end

    subgraph Plane["nexus VFS plane"]
      MB["chat-with-me DT_STREAMs<br/>/agents/{name}/chat-with-me<br/>/proc/{pid}/chat-with-me<br/><br/>sys_watch + sys_write<br/>kernel stamps 'from' field"]
    end

    O -. spawn .-> SC
    O -. spawn .-> CL
    O -. spawn .-> CX

    H <--> MB
    SC <--> MB
    CL <--> MB
    CX <--> MB

Sudo Code is interchangeable with claude / codex / a human at the mailbox primitive. It does not sit in the orchestrator box.

Same scode binary is a copilot, a worker, or a standalone CLI — chosen by which FsBackend impl the runtime routes through:

flowchart TB
    subgraph Runtime["sudocode runtime (Rust)"]
      direction LR
      SES["SessionStore"]
      CFG["ConfigLoader"]
      FOPS["file_ops helpers"]
    end

    TRAIT["FsBackend trait<br/>(one trait · three impls)"]

    SES --> TRAIT
    CFG --> TRAIT
    FOPS --> TRAIT

    TRAIT --> B1["StdFsBackend<br/>host std::fs"]
    TRAIT --> B2["NexusVfsFsBackend<br/>gRPC → remote kernel"]
    TRAIT --> B3["KernelFsBackend&lt;Kernel&gt;<br/>in-process syscalls"]

    B1 -.deployed in.-> M1["standalone CLI<br/>(scode on hacker's laptop)"]
    B2 -.deployed in.-> M2["edge / dev CLI<br/>(scode → remote nexus)"]
    B3 -.deployed in.-> M3["sudocode-host binary<br/>(prod managed agent)"]

Hydra — today a TypeScript VS Code extension shelling out to tmux + git worktrees to spawn Claude / Gemini / Codex — gets thin once sudocode-host lands:

flowchart LR
    subgraph Today["Today — hydra is a hack on system tools"]
      direction TB
      T1["VS Code extension<br/>(TypeScript)"]
      T2["tmux pane persistence"]
      T3["git worktree isolation"]
      T4["spawned claude / gemini / codex<br/>via shell"]
      T1 --> T2 --> T3 --> T4
    end

    subgraph Future["After sudocode-on-nexus-vfs ships"]
      direction TB
      F1["VS Code sidebar<br/>(thin — UI only)"]
      F2["ManagedAgentService<br/>start_session_v1()"]
      F3["WorkspaceBoundaryHook<br/>(VFS-enforced isolation)"]
      F4["scode / claude / codex<br/>as agent units"]
      F5["chat-with-me DT_STREAM<br/>(persistence + raft replication)"]
      F1 --> F2 --> F3 --> F4 --> F5
    end

    Today ==>|"hydra internals rewritten, becomes thin"| Future

Sudo Code is the agent unit underneath that whole future picture. For the engineering plan to get there, see sudo-code-roadmap.html § Goal 4.

curl -fsSL https://raw.githubusercontent.com/sudoprivacy/sudocode/main/install.sh | sh

install.sh downloads the prebuilt scode binary for the host platform (macOS arm64/x64, Linux x64/arm64) and verifies a SHA-256 checksum. On macOS Apple Silicon: /opt/homebrew/bin. On macOS x64 and Linux: /usr/local/bin, prompting for sudo only when stdin is a TTY. When the preferred system directory is unwritable and sudo is unavailable, the script installs to $HOME/.local/bin. Windows users grab the zip from the Releases page.

Overrides:

• SCODE_VERSION=v0.1.5 sh install.sh — pin a specific release.
• sh install.sh --no-sudo — install to $HOME/.local/bin.
• SCODE_INSTALL_DIR=$HOME/.local/bin sh install.sh — explicit per-user install.
• sh install.sh --prefix /usr/local — explicit prefix.

China mirror (checksums still verified against GitHub):

SCODE_MIRROR=https://sudowork-download-1309794936.cos.ap-beijing.myqcloud.com/sudocode/release/latest \
  curl -fsSL https://raw.githubusercontent.com/sudoprivacy/sudocode/main/install.sh | sh

git clone https://github.com/sudoprivacy/sudocode.git
cd sudocode/rust
cargo build --release
# Binary at ./target/release/scode

Requires a recent stable Rust 2021 toolchain.

# Pick an auth mode (see docs/authentication.md)
export CLAUDE_CODE_OAUTH_TOKEN="sk-ant-oat-..."

# Interactive REPL
scode

# One-shot prompt — pipe-composable, like every unix tool
scode "explain this codebase" | bat
scode "list failing tests" --output-format json | jq '.tests[]'

# Read a plan from stdin, resume a prior session
cat plan.md | scode --resume <session-id>

# Headless ACP server for editors / web clients
scode acp serve --port 8080

# Health check
scode doctor

For day-to-day workflows see docs/usage.md.

flowchart LR
    subgraph Clients
      Term([Terminal user])
      Editor([Editor / IDE])
      Browser([Browser / Web UI])
      Service([Backend service])
    end

    Term -->|REPL · one-shot| CLI
    Editor -->|ACP stdio| STDIO[scode acp]
    Browser -->|WebSocket + HTML| WS[scode acp serve --port N]
    Service -->|WebSocket / JSON-RPC| WS

    CLI[scode CLI / REPL] --> RT
    STDIO --> RT
    WS --> RT

    RT[Runtime<br/>session · permissions · sandbox · config] --> API[API Client<br/>SSE streaming]
    RT --> TOOLS[Tools]
    RT --> MCP[MCP servers]
    RT --> PLUG[Plugins / Skills]

    TOOLS --> T1[Bash · Read · Write · Edit]
    TOOLS --> T2[Grep · Glob · WebSearch · WebFetch]

    API --> P1[Anthropic]
    API --> P2[OpenAI / Codex]
    API --> P3[xAI · Gemini]
    API --> P4[Proxy / Mock]

The Cargo workspace is described in rust/README.md.

• sudo-code-roadmap.html — goals, design notes, engineering sequencing.
• docs/usage.md — REPL, one-shot, JSON output, resume, doctor.
• docs/authentication.md — auth modes and credentials.
• docs/permissions-and-sandbox.md — permission modes, Linux sandbox.
• docs/acp.md — ACP transports and the embedded Web UI.
• docs/models.md — aliases, provider-specific handling.
• docs/plugins.md — authoring and using scode plugins.
• docs/container.md — building and running inside a container.
• sudo-code-roadmap.html Goal 2 — what claude-code parity means and how it is tracked (reference sources, resolution taxonomy, sync markers).
• docs/mock-parity-harness.md — the deterministic mock backend and harness.
• rust/README.md — Cargo workspace map.

See CONTRIBUTING.md. Contributors keep their copyright — no CLA, no assignment, no waivers. Commit directly.

Chinese-speaking hackers: open issues and PRs in Chinese on the GitHub issue tracker if it's faster for you. The canonical docs (this README, ROADMAP, contracts) stay in English so there's one source of truth, but conversations in any language are welcome.

Released under the MIT License. See the per-crate license fields in rust/Cargo.toml.

Sudo Code is maintained by the Sudo Privacy community as the agent unit underneath the Sudowork collaboration platform.