svx — Simulate, Verify, Execute

A safety layer for coding agents. Before any action touches your codebase, svx simulates the outcome, verifies it against safety policies, and gives a clear verdict.

Core principle: simulation is for proposal; verification is for commitment.

Why

Coding agents (Claude Code, Copilot, Cursor, Aider) make mistakes — destructive commands, wrong git operations, irreversible changes. Current safety is either "human watches everything" (doesn't scale) or static blocklists (no context). svx adds intelligent, context-aware simulation.

Install

pip install -e .

Usage

Check a command before running it

svx check "git push --force origin main"

  svx ~ git push --force origin main
  ────────────────────────────────────────────────────────
  Verdict:  BLOCK
  Risk:     CRITICAL
  Force-push to main — rewrites remote history
  Effects:
    → Remote branch 'main' will be overwritten
    → Commits on remote not in local will become unreachable
  Reasons:
    ! BLOCKED: Force push to main/master is not allowed
  Suggestions:
    > Do not run this command.
    > Consider a safer alternative.

Safe commands pass through

svx check "git status"

  svx ~ git status
  ────────────────────────────────────────────────────────
  Verdict:  ALLOW
  Risk:     NONE
  git status: read-only or low-risk operation

Chained commands — each one analyzed

svx check "git add . && git commit -m 'fix' && git push --force origin master"

svx analyzes each command in the chain independently. If any step is blocked, the whole chain is blocked.

JSON output for programmatic use

svx check "git reset --hard HEAD" --json

Claude Code hook integration

svx can run as a pre-tool hook for Claude Code, automatically intercepting every shell command:

svx hook  # reads tool input from stdin

View audit log

svx audit --tail 20

What it catches

Command	Verdict	Why
git push --force origin main	BLOCK	Force push to main — irreversible, rewrites history
git reset --hard HEAD~3	CONFIRM	Destroys uncommitted changes
git clean -fd	CONFIRM	Permanently deletes untracked files
git branch -D feature	CONFIRM	Force-deletes branch, may lose unmerged work
rm -rf build/	CONFIRM	Recursive delete, untracked files unrecoverable
kill -9 1234	CONFIRM	Force-kills process, unsaved state lost
git push origin feature	ALLOW	Normal push, reversible
git status	ALLOW	Read-only
npm install lodash	ALLOW	Reversible package install

How it works

Command → Parse → Snapshot world state → Simulate outcome → Verify safety → Verdict

1. Parse: Break the command into program, subcommand, flags, targets
2. Snapshot: Capture current git state, file existence, sizes, tracking status
3. Simulate: Predict effects using dry-run flags and heuristic analysis (no LLM calls)
4. Verify: Score risk based on reversibility, blast radius, data loss, and policies
5. Verdict: ALLOW, CONFIRM, or BLOCK — with reasons and suggestions
6. Audit: Log every decision with full provenance

Policies

Safety rules are defined in policies/default.yaml:

blocks:
  force_push_to_main: true
  delete_root: true

confirmations:
  irreversible_actions: true
  data_loss: true
  force_flags: true

thresholds:
  max_blast_radius_without_confirm: 5

Project Scoping

SVX only guards projects you opt into — like git only works inside a .git/ repo:

cd my-project
svx init                    # creates .svx/ directory
svx init --mode strict      # confirm risky ops
svx init --mode vibe        # only block catastrophic (default)

Operations outside .svx/ projects are auto-allowed.

Modes

• vibe (default): Only BLOCK verdicts deny. CONFIRM verdicts auto-allow with logging. For when you trust the agent but want catastrophic-only protection.
• strict: Both BLOCK and CONFIRM verdicts require approval. For sensitive repositories.

Exit codes

• 0 — ALLOW
• 1 — CONFIRM (needs user approval)
• 2 — BLOCK (should not run)

Architecture

• No LLM calls — pure deterministic analysis in v0.1
• Uses real data — git dry-runs, file stats, not guesswork
• Fast — runs in <100ms for most commands
• Provenance — every decision logged with full context

License

MIT