VineScale docs

VineScale is a safety gate for AI coding agents: Claude Code, Codex, Cursor, Antigravity and Grok Build. Before the agent runs a command, edits a file or calls a database tool, the gate works out what the action would touch. It then lets it through, asks you first, or blocks it, with one line that says why. It runs on your machine, makes no network calls while it decides, and never reads secret values.

VineScale is in free beta. We're testing it, working out the kinks and fixing what testers report, so expect rough edges and use it as an extra check, not your only one. About the beta and how to send feedback.

How do I install VineScale?

The quickest way is the one-line command for your system, below. It installs vine and adds the gate to every supported agent it finds. Every way below installs into your own user folders. None needs admin rights, sudo or a Windows permission prompt, and none asks you to download a file in your browser.

With a one-line command (recommended)

macOS and Linux, into ~/.local/bin:

curl -fsSL https://vinescale.com/get.sh | sh

Windows PowerShell, into %LOCALAPPDATA%\Programs\VineScale:

irm https://vinescale.com/get.ps1 | iex

Both commands fetch the newest release's script from VineScale's plugin repository, which holds the plugin, the Scoop bucket and the signed release builds. Both scripts carry the checksum of every build, check the download against it, and then run vine install, which adds the gate's hooks to ~/.claude/settings.json and to each other agent it finds on your machine (below). Your own settings and hooks stay as they were, and a backup of the old file is kept next to it. To add the hooks to one project only, run vine install --project . in that project instead.

As a Claude Code plugin

In Claude Code, run:

/plugin marketplace add vinescale/plugin
/plugin install vinescale@vinescale

Then start a new session. The plugin downloads the right build of vine for your machine into its own data folder at session start, checks its SHA-256 checksum, and runs the gate before every Bash, Edit, MultiEdit, Write, NotebookEdit and MCP tool call. Updating the plugin updates vine; removing the plugin removes both.

The plugin doesn't put the vine command on your PATH, so you can't build an index with it alone. The gate still works by names, such as your default branch, your home folder and hosts called prod. To build an index too, use the one-line command instead of the plugin.

With Scoop on Windows

scoop bucket add vinescale https://github.com/vinescale/plugin
scoop install vinescale
vine install

This installs a user-scope copy, with no admin rights. A winget package isn't available yet.

Codex, Cursor, Antigravity and Grok Build

Install vine with the one-line command or Scoop above. vine install adds the gate to every one of these agents it finds in your home folder. To add it to one agent, for example after you install that agent later:

vine install --agent codex

Use cursor, antigravity or grok for the others, or all. Add --project . to add it to one project only. Then:

• Codex: the hook goes in ~/.codex/hooks.json. Run /hooks in Codex and trust VineScale's hook; Codex skips a new hook until you do.
• Cursor: the hook goes in ~/.cursor/hooks.json, before shell commands, MCP calls and file writes. Restart Cursor.
• Antigravity: the hook goes in ~/.gemini/config/hooks.json. Start a new conversation.
• Grok Build: the hook goes in ~/.grok/hooks/vinescale.json. Start a new session.

Codex and Grok Build can't stop to ask you, and Cursor doesn't for file writes. Where VineScale would ask, it blocks in those agents instead and tells the agent to hand the step to you.

Check a release

Each release on GitHub has a SHA256SUMS file, signed with Sigstore by the repository's release workflow. The repository's README has the cosign command to check it.

Build the index

The gate judges actions against a map of your production systems. Build it once per repository, and again when your infrastructure changes:

vine index .
vine map

vine map prints what VineScale found and how it labelled each target. If a label is wrong, set it in .vinescale.yml; a label there always beats a guess.

What does the gate check?

Each action resolves to a target: a database host and name, a Terraform workspace, a kube context, a cloud profile, a git branch or a path. VineScale labels each one production, staging, dev or unknown, from its name and host. The default branch and protected branches count as production; your home folder and system folders do too.

• Databases: migrations in Prisma, Drizzle, Alembic, Django, Rails, Flyway, Laravel and Supabase; SQL run through psql, mysql, sqlite3 or a database MCP tool; scripts and test suites that drop or empty tables.
• Infrastructure: terraform and tofu apply, destroy and state changes; kubectl deletes, prunes, drains and scale-to-zero; helm uninstall; deletes in aws, gcloud and az.
• Files and git: recursive deletes, dd and mkfs; force pushes; git reset --hard, clean -f and other commands that throw away uncommitted work.
• APIs: curl, wget and gh api calls that delete.
• The gate itself: the agent editing .vinescale.yml or the hook entries, or running vine uninstall, always asks you first.

Read-only actions such as SELECT, terraform plan, kubectl get or a normal push go straight through. Chained commands are split, and the strictest part decides.

When does VineScale allow, ask or block?

It allows read-only and non-production actions, asks before risky changes to production or unknown targets, and blocks destructive changes to production.

• Allow: VineScale says nothing, and your agent's own permission rules apply as usual. VineScale only ever tightens a permission; it never grants one.
• Ask: a risky change to production or an unknown target. Your agent shows you the reason and waits for your answer.
• Block: a destructive change to production, such as dropping a column that other services read, or terraform apply -auto-approve in a production workspace. The agent is told to stop and hand the step to you.

The same action on localhost or a dev branch is allowed. A reason line looks like this:

VineScale blocked: drops column users.email on prod-db (production), read by 2 services. Ask the user to run it.

What happens when the gate itself fails?

If the gate crashes, gets input it doesn't understand, finds no index or a stale one, can't read its config, or hasn't decided within its time limit, it lets the action through and prints nothing, as if VineScale weren't installed. It never blocks your work because of its own fault. The next session's start note tells you if that happened.

Each decision is written to ~/.vinescale/gate.log on your machine, with passwords and tokens in commands redacted. The log never leaves your machine.

What are the known limits in the beta?

• The other agents are new. Codex, Cursor, Antigravity and Grok Build arrived in 0.2.0. Their hooks are tested against each agent's documented hook format, and we're still trying them inside each agent. In Antigravity, MCP tool calls aren't checked yet.
• It judges what it can see. When it can't tell which database a command points at, for example an address in a variable that isn't set where your agent runs, it lets the command through. Indexing the repository and setting labels in .vinescale.yml help.
• One level of scripts. It reads a script the agent runs, but not scripts that script runs in turn.
• Development databases are fair game. Wiping a local or dev database is allowed on purpose, so it doesn't get in the way of everyday work.
• Its own config, by shell. Edits to .vinescale.yml through the agent's edit tools ask first, but a shell command that writes to it isn't caught yet.
• One repository at a time. It can say how many services in a repository read a table, but it doesn't yet see other repositories that depend on yours.
• Newest on Linux. The macOS and Windows builds are in the release and checked against their checksums, and we're still confirming them on more machines. Please tell us if an install trips.

And because it fails open, a fault in the gate means no check at all for that action, never a stopped session.

How do I send feedback or report a bug?

Tell us what it blocked that it shouldn't have, what risky thing it let through, and anything that went wrong installing it.

Found a bug in vine? Report it here. Tell us what happened, what you expected, which coding agent and operating system you use, and the version from vine version. A command, log line or output helps if you have one; take out any passwords, tokens or connection strings first. Leaving your email is optional; add it if you would like a reply.

For anything else, open an issue on GitHub, or reply to the email that invited you. If you share a line from ~/.vinescale/gate.log, check it first: passwords and tokens in commands are redacted, but host and table names are not.

How do I remove VineScale?

If you installed the plugin, remove it with /plugin uninstall vinescale@vinescale. Otherwise run:

vine uninstall

That takes VineScale's hooks out of every agent's settings and leaves everything else as it was. vine uninstall --agent cursor takes them out of one. Then delete vine itself, or remove it with scoop uninstall vinescale if you installed it that way.

Frequently asked questions

Does VineScale need network access to decide?

No. The gate makes no network calls while it decides and never reads secret values. Each decision is logged to ~/.vinescale/gate.log on your machine, and the log never leaves it.

Does VineScale replace my agent's permission rules?

No. It runs alongside them and only ever tightens a permission; it never grants one. When VineScale allows an action, your agent's own permission rules still apply as usual.

Will VineScale stop the agent from wiping my dev database?

No, on purpose. Wiping a local or dev database is allowed so the gate doesn't get in the way of everyday work. The same action against a target labelled production is asked about or blocked.

Can the agent turn VineScale off?

Editing .vinescale.yml or the hook entries with the agent's edit tools, or running vine uninstall, always asks you first. In the beta, a shell command that writes to .vinescale.yml isn't caught yet.

Does VineScale see other repositories that depend on mine?

Not yet. It works one repository at a time: it can say how many services in a repository read a table, but it doesn't yet see other repositories that depend on yours. Cross-repo warnings are planned.