sudoprivacy/sudocode

What Sudo Code is

Sudo Code is a Rust‑native command‑line AI coding assistant aimed at power users who spend most of their time inside a terminal (tmux, ssh, VS Code’s integrated terminal, etc.). It talks to large‑language‑model APIs (Anthropic, OpenAI, xAI, Gemini, or any compatible provider) but does not lock you into any vendor – you supply your own API keys and the binary talks to them over the open ACP protocol.

The tool runs inline in the shell: it never takes over the screen, never opens a full‑screen TUI, and can be piped like any other Unix command. It can be used interactively (a REPL) or in one‑shot mode, and it can also expose a head‑less ACP server for editors, browsers, or other services to drive it.

Who it’s for

Ideal user	Not a good fit
Engineers who live in the terminal and want full visibility into the agent’s actions (e.g., reading the exact source lines the agent touches).	Beginners looking for a point‑and‑click coding assistant.
People who manage many parallel AI‑driven tasks and want to script or pipe them.	Users who need a graphical UI or a “just give me the answer” experience.
Teams that own their stack, pin versions, and want zero‑telemetry defaults.	Anyone who prefers the tool to hide its inner workings.

Core design principles (what it always does)

• Open‑source, MIT‑licensed – the whole codebase is visible and can be forked.
• Model‑agnostic – you bring your own API keys; the binary works with any supported provider.
• Headless‑first – the same binary powers the REPL, one‑shot CLI, and the ACP server.
• Local‑first & no telemetry – prompts stay on your machine unless you explicitly forward them.
• Inline only – output is plain ANSI text; scrollback, tmux panes, and SSH sessions stay untouched.
• Stable, version‑pinned surface – no silent updates; semver guarantees.
• Everything is a file – configuration, session logs (JSONL), and plugins live on the filesystem, making them easy to inspect, awk, or replay.

What it never does

• No hidden premium tier or pay‑wall – the binary is the full product.
• No full‑screen TUI; it never hijacks your terminal screen.
• No built‑in multi‑agent dashboard – orchestration is left to external tools (e.g., the Sudowork platform or the Hydra orchestrator).
• No forced auto‑updates or telemetry.
• No closed‑source vendor lock‑in.

How it works (high‑level architecture)

1. CLI / REPL – scode can be started interactively or invoked with a prompt string, producing plain text, JSON, or streaming SSE output.
2. Runtime – a Rust runtime handles sessions, permissions, sandboxing, and configuration. It loads a FsBackend implementation that determines where files live:
   • StdFsBackend – local filesystem (stand‑alone CLI).
   • NexusVfsFsBackend – remote VFS via gRPC (edge/dev mode).
   • KernelFsBackend – in‑process kernel‑style syscalls (managed‑agent mode).
3. Tools & Plugins – built‑in helpers for bash, file I/O, grep, web search, etc., plus a plugin system for custom “skills”.
4. Model adapters – thin wrappers that translate ACP calls to the APIs of Anthropic, OpenAI, xAI, Gemini, or a mock backend.
5. ACP server – scode acp serve exposes the agent over WebSocket/HTTP so editors or web UIs can interact with it.

Typical usage patterns

# Start an interactive REPL (uses your env‑provided token)
export CLAUDE_CODE_OAUTH_TOKEN="sk‑ant‑…"
scode

# One‑shot, pipe‑friendly usage
scode "explain this function" | bat
scode "list failing tests" --output-format json | jq '.tests[]'

# Resume a saved session (sessions are stored as JSONL files)
cat plan.md | scode --resume <session-id>

# Run as a headless server for an editor integration
scode acp serve --port 8080

# Quick health check
scode doctor

Installation

• One‑liner script – curl …/install.sh | sh downloads a pre‑built binary for macOS or Linux, verifies its SHA‑256 checksum, and installs it to a system directory (or $HOME/.local/bin if sudo isn’t available). Windows users can grab the zip from the Releases page.
• From source – git clone … && cd sudocode/rust && cargo build --release produces ./target/release/scode.

Extensibility

• Plugins/Skills – drop a compiled plugin into the designated directory and invoke it from the CLI; documentation lives in docs/plugins.md.
• Permissions & sandbox – fine‑grained control over what the agent can read/write, described in docs/permissions-and-sandbox.md.
• Authentication – multiple auth modes (OAuth token, API key, proxy) are detailed in docs/authentication.md.

Roadmap & ecosystem

Sudo Code is positioned as a single agent unit that other Sudowork components (the Hydra orchestrator, VS Code extensions, etc.) can drive via a shared mailbox primitive (chat‑with‑me stream on the Nexus VFS). Future plans (see sudo-code-roadmap.html) include tighter integration with the Nexus VFS, richer plugin APIs, and scaling from a single interactive session to fleets of 100+ agents managed by a copilot‑agent.

---

License: MIT – contributors keep their own copyright, no CLA required.