---
title: "How Rig Works"
description: "Rig tailors rules for your project to better check code changes during each coding turn."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.rig.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Rig Works

## Setup: prepare checks for your project {#what-setup-learns-about-your-project}

**Prepare once. Check changes in seconds.**

A default security rule pack provides a starting point, but can miss patterns specific to your project. 

Rig spends time during setup tailoring security checks to your project. During everyday coding, it reuses those saved rules to check changes, give your agent actionable feedback, and verify repairs.

Setup is run once for a project. Your agent uses Rig’s setup skill and Rig tools to prepare the scanner for your codebase.

> **What is a security check?**
>
> Rig Scan uses **SAST—static application security testing**. It reads source code without running your application and applies rules that describe potentially unsafe code patterns.
>
> A check connects a pattern to an explanation: **what to look for, why it matters, and where it appears in your code.**

The setup skill runs the agent through a simple flow:

### 1. Understanding the Project

The agent gathers project-specific details such as languages, frameworks, database types, and packages for database access and authentication.

| What setup learns | Why it matters for a rule |
| --- | --- |
| The language and framework | Which syntax and APIs to recognize. |
| How requests reach the database | Where input could become part of a query. |
| Custom helpers and wrappers | Which project-specific calls the general rules may miss. |

### 2. Assess Coverage

Rig starts with a default rule pack designed to cover most security types for most projects. But default rules can miss vulnerabilities in your specific stack.

Rig includes a coverage tool that your agent will use to assess how well the default rule pack covers your app. 

For example, your application might wrap database access in its own helper. Tailoring gives checks a way to recognize that project-specific pattern.

Coverage considers two things: **files covered** and **vulnerability types tested for**. This helps direct the setup work toward areas that need more attention.

### 3. Close the Gaps

Rig guides the agent through a loop designed to close the gaps identified in step 2. 

Rig includes a skill and specialized instructions on how to create rules that capture vulnerability types.

The agent continues this loop until the coverage goal of **>80%** is reached. This is Rig’s setup coverage measure across files and vulnerability types—not a claim that it detects 80% of all possible vulnerabilities.

#### Example Rule

A rule can look for values inserted directly into the query text, like in this example with a database helper called `database.raw`.

### Unsafe · should flag

```js title="Input becomes part of the query"
database.raw(`SELECT * FROM users WHERE name = '${name}'`);
```

**Expected result:** flag this call. The inserted value can change the database instruction.

### Safe form · should pass

```js title="Input passed separately"
database.raw('SELECT * FROM users WHERE name = $1', [name]);
```

**Expected result:** this rule should not flag the call, assuming the helper supports PostgreSQL-style parameter binding.

### The rule

```yaml title="Illustrative rule for this direct call"
rules:
  - id: interpolated-raw-query
    languages: [javascript, typescript]
    severity: ERROR
    message: Pass input as a separate query parameter.
    pattern: database.raw(`...${$VALUE}...`)
```

-- 


### Output: saved project rules

The resulting rules are the connection between setup and everyday scanning: the scanner reuses them instead of asking the agent to rediscover the project on every check.

**Setup loop → saved project rules → fast scan loop**

| Part | Responsibility |
| --- | --- |
| Your coding agent | Follows the setup skill, prepares rules, interprets feedback, and edits code. |
| Rig Setup | Connects the workflow to checks, tracks changes, and keeps scan evidence and finding status. |
| Rig Scan | Reads source code and applies the configured rules locally. |


## Scans: check changes as your agent codes {#when-checks-run}

Once setup is complete, work with your agent as usual. Rig connects to the coding workflow through **MCP tools**—tools the agent calls to talk to Rig—and **hooks**, which run at events such as code changes and the end of a turn.

> **Rig runs Locally**
>
> Rig Scan runs locally. No rules, findings, or telemetry are shared with Rig. Your agent handles its own model calls and data settings.

### How checking the diff works

Rig retains the task’s starting code and compares it with the current changes. Checks cover the accumulated changes in the task, including later edits made to repair a finding.

The scanner reads the **changed files with their surrounding code**, not just isolated added lines. Rig uses a baseline comparison to identify findings associated with the changes, while retaining the current-file results to verify whether a reported issue is actually gone.

This keeps feedback focused on the work in progress. A whole-project scan is a separate operation.

### How findings become fixes

Rig gives the agent structured findings with a file location, rule, severity, and explanation. The agent uses that information to edit the code, then calls Rig to check again using the configured rules.

```
Location: `src/users.ts`, line 18  
Rule: `interpolated-raw-query`  
Problem: a value is inserted into a raw database query.  
Repair guidance: pass input as a separate query parameter.
```
The agent has the choice to handle each finding:

| Agent response | What happens next | What Rig reports |
| --- | --- | --- |
| **Code Repaired** | Rig Scan reruns the saved checks against the updated changes. | Issue marked fixed only when the recheck establishes resolution. |
| **Skip with a reason** | Rig records the explanation against the current finding. | Skipped, with the reason visible. |
| **Leave it unaddressed** | The end-of-turn process can request further agent work. | User is alerted the agent left issue unresolved. |

The agent does not simply declare an issue fixed. Rig derives that status from the scan evidence, including whether the recheck covered the affected file and still matches the current code.

> **Agents Can Skip an Issues**
>
> The agent records a reason against the finding. Rig keeps it visible as **skipped**, alongside that explanation. It remains unresolved; a skip does not disable the rule or grant a permanent exception.
>
> If the relevant code changes, the earlier skip reason does not automatically carry forward to the changed evidence.
>
> **Example skip reason:**
>
> > “This file is an intentionally unsafe training fixture. Keeping the example for the exercise.”


### What if the agent forgets to call Rig?

Rig falls back to using turn hooks. The end-of-turn hook checks for missing or outdated scan evidence. For configured scans, it runs the needed check before deciding whether more agent work is required.

If findings are still unaddressed, Rig can ask the agent to repair them or record reasons. This automatic loop is bounded to **three repair rounds**, and stops earlier on no progress, cancellation, or a scanner failure. Hook behavior depends on the host integration being enabled and trusted.

### What you see at the end

Rig supplies a summary for the agent’s turn response, with the findings and verification state kept together.

```
---
Rig Findings
1 fixed · 1 skipped · 0 unaddressed

- Fixed: query input is now passed separately; recheck confirms resolution.
- 👀 Skipped: the training fixture remains intentionally unsafe; the reason is recorded.

The skipped issue remains unresolved even though no findings are left without a response.
---
```

| Outcome | What it tells you |
| --- | --- |
| Fixed | A comparable recheck establishes that the finding was resolved. |
| Skipped | The finding remains, with the agent’s recorded reason. |
| Unaddressed | The finding still needs a fix or an explanation. |
| Verification incomplete | A missing, outdated, or failed check prevents a verified result. |


### The MCP Interface

| Tool | What the agent uses it for |
| --- | --- |
| `rig_context` | Retrieve applicable guidance and the task’s verification needs. |
| `rig_check` | Run checks against the task’s accumulated changes and recheck repairs. |
| `rig_respond` | Record a reason for skipping a current finding. |
| `rig_finish` | Read the current completion report; this tool does not run a scan. |

A task identifier connects these calls to the same starting code, changes, findings, and evidence. Rig retains the scan results so the summary is based on recorded checks.

Source: https://docs.rig.ai/how-rig-works/index.mdx