# VineScale docs · Install the free beta for your coding agent

> How to install VineScale's free safety gate for Claude Code, Codex, Cursor, Antigravity or Grok Build, what it checks, its known limits and how to remove it.

Web page: https://vinescale.com/docs/

[Home](https://vinescale.com/)

Free beta · version 0.2.0

## 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](https://vinescale.com/beta/) and [how to send feedback](https://vinescale.com/docs/#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](https://github.com/vinescale/plugin), 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](https://github.com/vinescale/plugin#checking-a-release) 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](https://tally.so/r/8NqKp5). 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](https://github.com/vinescale/plugin/issues), 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.