SCV

One agent to find them all, one agent to guide them.

A fast, native agent runtime that lives on your machine, leads your coding agents, and answers from your terminal, Feishu, Slack, and WeChat.

English · 简体中文

Install · Quickstart · Chat channels · Agents · Docs

SCV is a small agent runtime written in Rust. One long-running daemon holds your sessions, tools, and approvals, and you talk to it from a terminal UI or from Feishu/Lark, WeChat, or Slack on your phone. It handles quick questions itself, finds the right coding agent for real work (Claude Code, Codex, and others), briefs it, runs it as a background job, and messages you when it is done.

Highlights

Chat from your phone

Scan a QR code to pair Feishu/Lark or WeChat, or connect a Slack app you set up by hand. SCV answers only you by default, reads the photos, files, and videos you send, and sends files back. Long work runs in the background while you keep chatting; results and yes/no questions arrive as messages. SCV keeps a log of your chat, so a conversation carries on across restarts and it can look back when you mention something older; /new starts a fresh one. On Feishu and Slack, a thread is a conversation of its own: SCV answers inside the thread, on a session of its own.

One agent, many agents

One agent tool delegates to Claude Code, Codex, Grok Build, DeepSeek Harness, pi, Gemini CLI, Qwen Code, OpenCode, GitHub Copilot CLI, Cursor CLI, Amp, Kimi Code, or a nested SCV, over the Agent Client Protocol where available, each job optionally in a git worktree of its own. Your prefer list and use_for notes pick who does what, each agent's default model and effort (and a separate effort for hard tasks) set how, and agent_wait, agent_status, and agent_cancel manage background jobs. Ask for a review and a fresh agent on another harness checks the work on a structured verdict, round by round, before SCV reports it as approved, in its own words. SCV learns each agent's models and effort levels from the agent itself and passes them exactly, instead of guessing names that change with every release. A built-in delegating skill teaches it how to brief an agent and what to do when a call fails, and scv agents check shows every agent working.

A workbench for every agent

The terminal UI is a dashboard: a chat tab per workspace, and agent views that follow each delegated agent live (what it says, the commands it runs, the approvals it waits on) and take your prompts for its conversation. A sidebar shows every workspace's jobs with their state and why: working, waiting for you, idle, quiet for too long, or interrupted. Start jobs of your own, stop them, answer their approvals while you watch, and resume a job a restart cut off in the agent's own conversation; your queued prompts come back too. Take an idle Codex conversation over in its own terminal (Ctrl+O, or scv jobs attach), or stop the job running its turn and take it over (Ctrl+O twice, or --interrupt), type into it, and detach while it keeps running. scv jobs does the same from the command line, and says of each job whether its conversation can be taken over, or why not.

Private homes, private keys

Each agent signs in once with scv agents login and runs in its own home under ~/.scv/agents/<name>. It never reads your personal ~/.claude or ~/.codex, and never inherits your *_API_KEY variables. Claude Code is two of those agents: claude bills an Anthropic API key SCV stores in its home, and claude-ai uses the owner's Claude subscription login, which Claude Code owns in a separate home. SCV pins the selected billing identity on every launch: claude calls https://allrouter.cc and claude-ai calls https://api.anthropic.com.

Updates without dropping work

scv restart --when-idle waits until the work that asked for it has reported back and no background job is still running, then restarts into the new release. A watchdog checks that the new version comes up with its chat accounts connected and, where the config layout allows, rolls back if it does not. That is how SCV ships its own releases from chat, asking you first only when a release would pass its daily limit of versions per crate.

You stay in charge

The server, not the client, enforces one approval policy. By default (auto), tools and agents run without asking, each delegated agent starts in its own full-autonomy mode, and SCV stops a run that reports a mode the policy did not choose. SCV denies a force-push to main and asks you before a direct cargo publish. mode = "on-risk" brings the questions back: reads run, while writes, shell commands, and agents ask first. File tools stay in the workspace, commands and agents have timeouts (a background agent job may run without one only if you allow it) and output caps, and chat stays tool-free until you grant tools to your own account.

Native, small, extensible

A Rust daemon, a terminal UI, headless scv exec, and a versioned JSONL protocol. Deterministic context budgeting, any OpenAI-compatible Responses endpoint, Markdown skills, and Rust traits for providers, tools, and policies. Linux and macOS.

Install

cargo install scv-cli --locked

You need Rust 1.88 or newer and /bin/bash. This installs scv and scv-server, a standalone protocol entry point. To track main instead, run cargo install --locked --git https://github.com/PeiyuanQi/scv.

Quickstart

1. Configure a model. SCV speaks the OpenAI-compatible Responses API.

scv config init                  # writes a starter ~/.scv/config.toml
$EDITOR "$(scv config path)"     # put your API key and model in it

2. Start the daemon on the folder that holds your projects, then talk to it. scv start runs the daemon as a systemd user service; without systemd, such as on macOS, keep scv run --workspace ~/code open in a terminal instead.

scv start --workspace ~/code
scv                              # the terminal UI, in the current directory
scv exec "Explain this repository"   # or one headless prompt

3. Connect your phone. We recommend Feishu (or Lark, its international edition). SCV keeps one WebSocket connection open to it, so your messages arrive at once. WeChat also works, but SCV has to poll its API for new messages, and in our use it answers noticeably slower.

scv channels login feishu        # scan the QR code (or: lark, wechat)
scv channels run feishu --workspace ~/code --remote-tools owner
scv channels status              # Channels: 1 of 1 enabled accounts connected

Slack works too, through an app you create once from SCV's manifest with Socket Mode on (setup). scv channels login slack --slack-owner-user-id U0123456789 then reads its bot and app-level tokens at hidden prompts.

--remote-tools owner equals shell access from your chat account. It gives your own account every SCV tool, with approvals granted automatically. Leave it out and SCV chats with you tool-free.

4. Sign in the agents it delegates to, then check that each one works as SCV runs it.

scv agents login claude          # once per agent, in SCV's private home
scv agents login codex
scv agents status
scv agents check                 # version, models, and one short call each
scv agents doctor --workspace .   # offline project Rust/toolchain diagnostics

Delegated coding agents resolve installed Rust tools for the selected project before they start, even when the daemon's PATH only finds an older system Rust. Toolchain files and Cargo's Rust requirements are checked; unavailable or incompatible tools produce a diagnostic. The agents keep private homes and Cargo state. See project Rust environments for selection rules and limits.

Everyday commands

Project orchestration is optional and independent of one-off agent calls. Create a project explicitly with an existing absolute workspace; the daemon then persists an append-only event log under $SCV_HOME/state/projects/ and starts its supervised project orchestrator. Add tasks with dependencies, record the agent run IDs and heartbeats, and use scv project report to inspect only observed state. The daemon compacts the event tail into a private snapshot as it grows; project events reports when older sequences have been compacted. Missing heartbeats make a run and its task stale after five minutes; the orchestrator never infers progress from agent prose or starts an agent without an explicit run command.

What it looks like

An illustration of a Feishu chat with SCV:

You  The checkout test in shop/ has failed since this morning.
     Find out why and fix it, please.
SCV  Handed it to Codex in shop/ as job-1. I'll message you when it
     reports back.
You  Meanwhile, how much disk is left on this machine?
SCV  412 GB free of 1 TB on /.

                           · · · 14 minutes later · · ·

SCV  Codex finished job-1. The test assumed the machine's clock was on
     UTC; it now pins the time zone, and all 212 tests pass. The fix is
     one line in tests/checkout.rs, not committed yet.
You  Nice. Send me the diff.
SCV  Here it is.
SCV  [file] checkout-timezone.diff

SCV answers the quick question itself while Codex works, relays Codex's report without being asked, and sends the diff as a file. Before a step that cannot be undone, work can also ask you yes or no in the chat with scv confirm; SCV's own release flow asks this way when a release would pass its daily limit of versions per crate.

How it works

   Feishu/Lark · WeChat                        Terminal
     (your phone)                              (scv TUI)
          │ bot account, QR sign-in               │ Unix socket
          ▼                                       ▼
 ┌─ scv daemon ──────────────────────────────────────────────────┐
 │  chat bridges ─► sessions ─► agent loop ─► OpenAI-compatible  │
 │                                              model endpoint   │
 │  supervisor · approvals · context budget · planned restarts   │
 └───────────────────────────────┬───────────────────────────────┘
                                 │ tools, gated by approval policy
                                 ▼
     read · write · bash · web_fetch · read_skill · chat_attach
     agent ─► Claude Code · Codex · Grok Build · DeepSeek Harness · pi ·
              Gemini · Qwen · OpenCode · Copilot · Cursor · Amp · Kimi · SCV
              over ACP, the agent's CLI, or SCV's protocol, in private homes

The daemon owns every session, tool, and approval. The TUI and each chat account speak the same versioned protocol, so a message from your phone runs exactly like a turn in the terminal. See the architecture.

Configuration

Everything SCV keeps lives under ~/.scv (or --scv-home), and the one file you edit is config.toml:

[provider]
active = "openai"

[providers.openai]
kind = "openai-compatible"
model = "gpt-4.1-mini"
base_url = "https://api.openai.com/v1"
api_key = "sk-your-key"
# reasoning_effort = "high"   # with a reasoning model: how hard SCV's own model thinks

[policy]
mode = "auto"                 # the default: tools and agents run without asking
# mode = "on-risk"            # reads run; writes, shell, and agents ask first

[agent]
prefer = ["codex", "claude"]  # who gets delegated work first
on_busy = "queue"             # queue, wait, steer, or fail
steer_fallback = "queue"
max_queued_turns = 4

[agents.claude]
use_for = "coding"
model = "opus[1m]"            # a value `scv agents check` lists for claude
effort = "xhigh"
on_busy = "steer"             # per-agent override; falls back to queue

[agents.grok]
use_for = "current events, and anything that needs posts on X"
effort = "medium"             # when a call names no effort
hard_task_effort = "high"     # what the main agent passes for a hard task

[notify]
owner = ["feishu:default"]    # where unprompted notices go

scv config show prints every path and setting with where it came from, secrets hidden. The full schema and trust rules are in docs/configuration.md.

Safety

SCV is not a sandbox: commands and delegated agents run with your user's permissions, and by default without asking you. Work in version-controlled workspaces, switch [policy] to on-risk when you want to read what you approve, and use a container for untrusted code. SCV is pre-1.0, so its protocol and configuration may still change. See the security model, and report vulnerabilities as SECURITY.md describes.

Documentation

Contributing

Contributions are welcome. Build from source and run the checks:

git clone https://github.com/PeiyuanQi/scv.git && cd scv
cargo build --workspace --locked
cargo fmt --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
cargo deny check advisories bans licenses sources  # CI always runs it
cargo build --release --locked
git diff --check

Tests use scripted providers and fake agents, so they need no API key. CONTRIBUTING.md covers running a development daemon beside your real one, and AGENTS.md holds the rules coding agents follow in this repository.

License

SCV is licensed under the Apache License 2.0. See NOTICE.