scv-core 0.1.9

Provider-independent agent loop and extension traits for SCV
Documentation

SCV

SCV is a small, fast, extensible agent runtime for the terminal. It keeps the agent loop simple, puts model and tool authority in a separate server process, and provides a responsive Rust TUI for coding work.

Project status: SCV is an early v0.1 implementation. Its protocol and configuration may change before 1.0. Run it in version-controlled workspaces and review every approval.

What works

  • Streaming OpenAI-compatible model calls and function tools
  • Built-in workspace-scoped read, atomic write, and bash tools
  • Native tool adapters for installed claude, codex, and pi agents
  • Progressive-disclosure Markdown skills from user and project directories
  • Configurable, bounded context selection and deterministic compaction
  • Server-enforced approvals, timeouts, output caps, and cancellation
  • A Unix-socket daemon with a Ratatui client, plus a stdio server for one-shot clients
  • Interactive TUI plus a headless scv exec mode
  • Linux and macOS support on ARM64 and x86-64

Install

SCV requires Rust 1.88 or newer and /bin/bash.

cargo install --locked --git https://github.com/PeiyuanQi/scv

Until release archives are published, build from source:

git clone https://github.com/PeiyuanQi/scv.git
cd scv
cargo build --release --locked

The package installs two binaries: scv and the standalone protocol entry point scv-server.

Update an installed SCV binary from crates.io with:

scv update

The registry index can be selected in ~/.scv/config.toml:

[update]
index_url = "https://mirrors.ustc.edu.cn/crates.io-index"

SCV_CARGO_INDEX_URL or scv update --index-url URL can override that value. SCV passes the URL to Cargo and does not handle registry credentials itself. When the user-level daemon is active, the update command restarts it after the new binary is installed. Connected TUI clients automatically reconnect and create a fresh session.

To publish from a clean checkout, authenticate with cargo login and publish the workspace in dependency order (Cargo will refuse a package whose local dependencies are not already on crates.io):

cargo publish --locked -p scv-core
cargo publish --locked -p scv-protocol
cargo publish --locked -p scv-provider-openai
cargo publish --locked -p scv-tools
cargo publish --locked -p scv-server
cargo publish --locked -p scv-tui
cargo publish --locked -p scv-cli

The server is a JSONL backend for local clients. It is normally started by the TUI or by an embedding client and is not the user-facing daemon:

scv server --stdio

The stdio protocol is intentionally local and one-session-per-connection.

Daemon and ClawBot / WeChat iLink

SCV has one long-running daemon. Run it attached to the terminal with scv run --workspace /path/to/workspace, or let the user service supervise the same process:

scv start --workspace /path/to/workspace
scv status
scv restart --workspace /path/to/workspace
scv stop

Daemon starts use the server's on-risk approval policy by default. Pass --approval-policy always or --approval-policy never before start or restart when that invocation needs a different explicit policy. SCV runs the daemon as the current user. If the user has no currently valid sudo authorization, an interactive start asks whether to continue with reduced capability; --allow-sudo asks sudo to authenticate the current user's existing policy first. This flag cannot grant sudoers membership or turn the daemon into a root service, and non-interactive starts without verified sudo authorization fail with an actionable error.

With no subcommand, scv starts the TUI and connects to the local server socket. It does not start a private server child. If the daemon is unavailable, SCV reports the socket path and suggests scv start or scv run. Model and provider overrides are sent when the TUI creates its session, so a running daemon can serve sessions using different models or providers without a daemon restart:

scv --model gpt-4.1-mini
scv --provider local --model llama3.1 --base-url http://localhost:11434/v1

Authenticate the WeChat ClawBot bridge once with scv clawbot login. The QR login stores the bearer token at $SCV_HOME/clawbot/accounts/<account>.json (normally under ~/.scv) with mode 0600; the token is never printed. Start the bridge explicitly with scv clawbot run --workspace /path/to/workspace. Remove an account with scv clawbot logout. See the ClawBot design and API contract.

Quick start

SCV's first provider speaks the OpenAI-compatible Chat Completions API.

export OPENAI_API_KEY="your-key"
cd /path/to/your/project
scv

Use another compatible model or endpoint:

scv --model gpt-4.1-mini --base-url https://api.openai.com/v1

Run one non-interactive prompt. Risky tools are denied unless --yes is present:

scv exec "Explain this repository"
scv exec --yes "Run the tests and fix the failure"

In the TUI, Enter sends, Ctrl+J inserts a newline, Esc cancels, Ctrl+O toggles the latest tool result, and /help lists the compact command set.

Configuration

User configuration lives at ~/.scv/config.toml (or $SCV_HOME/config.toml); copy config.example.toml there to get started. A workspace may add .scv/config.toml, but project configuration cannot redirect provider credentials or replace native-agent executables.

[provider]
model = "gpt-4.1-mini"
base_url = "https://api.openai.com/v1"
api_key = "sk-your-key"
api_key_env = "OPENAI_API_KEY" # optional fallback

[context]
max_tokens = 128000
reserve_output_tokens = 8192

[tools]
approval_policy = "on-risk"
command_timeout_seconds = 120

[agents.codex]
command = "codex"
args = ["exec"]

Precedence is CLI, environment, explicit SCV_CONFIG, project configuration, user configuration, then defaults. Unknown keys fail startup. See docs/configuration.md for the complete schema and trust rules.

Extending SCV

The built-in provider uses the OpenAI Responses API at /responses, with streaming text and function-call events. The core exposes small Rust traits for providers, tools, context policies, approval gates, and event sinks. Registering a new Tool does not require a change to the agent loop or TUI.

Skills use .scv/skills/<name>/SKILL.md in a project or ~/.scv/skills/<name>/SKILL.md for the user. Set SCV_HOME to relocate all user configuration and skills. Only skill metadata enters the initial prompt; the model loads full instructions through the contained read_skill tool when needed.

The built-in agent_claude, agent_codex, and agent_pi tools launch those installed CLIs directly, without shell interpolation. They are optional, approval-gated, cancellable subprocess adapters and share the same output and timeout limits as other process tools.

Architecture

SCV is a Cargo workspace with deliberately narrow packages:

  • scv-core: loop and extension traits;
  • scv-protocol: versioned wire types with no runtime policy;
  • scv-provider-openai: streaming provider transport;
  • scv-tools: filesystem, process, skill, and nested-agent tools;
  • scv-server: configuration, sessions, permissions, and protocol dispatch;
  • scv-tui: terminal client and headless protocol client.

The TUI connects to the local Unix-socket daemon; scv-server --stdio exposes the same server library to one-shot local clients. Start with the final v0.1 architecture, then see the protocol, context, tools, TUI, and security model.

Security

SCV is not an OS sandbox. bash and nested agents run with your user permissions and inherited environment after approval. File tools reject absolute paths, parent traversal, and symlink escapes, but an approved process can access anything your account can access. Use a container or operating-system sandbox for untrusted repositories. See SECURITY.md and the full security model.

Development

Read AGENTS.md before using a coding agent in this repository. Use a sibling git worktree for parallel or unrelated work. Keep final-state design documents in docs/ aligned with behavior changes, including cross-cutting agent-loop, protocol, security, or architecture work. Reasonable redesign and cleanup are part of feature work when they leave the project clearer, smaller, safer, or more efficient. Prefer one complete end-to-end implementation of the requested outcome, including tests and documentation, over artificial vertical slices. Commit or push only at an explicit delivery boundary.

cargo fmt --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
cargo deny check advisories bans licenses sources
cargo build --release --locked
git diff --check

Tests use scripted providers and fake executables; they do not require a live API key. The test and performance contract is in docs/quality.md, with measured results and an honest feature comparison in the v0.1 evaluation. Contributions are welcome—read CONTRIBUTING.md first.

License

Licensed under the Apache License 2.0.