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

# Quickstart

> Build Refactron from source and verify your first diff end to end, then give the same gate to your AI agent over MCP.

In the next ten minutes you'll build Refactron, verify a real change against a real test suite, and read your first `SAFE` / `UNSAFE` / `UNPROVEN` verdict.

<Note>
  `verify-diff`, the MCP server, and `preflight` are unreleased; they are **not** in
  `refactron@0.2.4` on npm yet. Build from source until the next release, which ships the
  `refactron` and `refactron-mcp` bins. The published npm package is the [migration-mode transform
  CLI](#migration-mode) covered at the end. If `refactron verify-diff` reports an unknown command,
  you're on the npm package (migration mode, `0.2.4`); `verify-diff` is from-source only until then.
</Note>

## Build from source

Requires Node.js ≥ 18. To earn a `SAFE` verdict end to end you also need a Python project with a passing `pytest` suite, plus `coverage.py` for the coverage measurement:

```bash theme={null}
pip install pytest coverage
```

```bash theme={null}
git clone https://github.com/Refactron-ai/Refactron_Lib_TS
cd Refactron_Lib_TS
npm install
npm run build
```

## Authenticate

`verify-diff` is auth-gated. Log in once on this machine (this runs a device-code flow and opens your browser to approve a code):

```bash theme={null}
node dist/cli/index.js login
```

For CI or a headless box, export a token instead of the browser flow:

```bash theme={null}
export REFACTRON_TOKEN=refactron_live_...
```

An unauthenticated run exits `7`.

## Verify a diff

Point Refactron at a repo and a unified diff. The diff can come from anywhere: an agent, a codemod, or your own `git diff`.

<Steps>
  <Step title="Capture a change as a diff">
    From a Python project with a test suite:

    ```bash theme={null}
    cd /path/to/your/project
    git diff > change.diff          # or: your agent wrote change.diff
    # already staged or committed? use `git diff --staged` or `git diff main...HEAD`
    ```
  </Step>

  <Step title="Verify it">
    You `cd`'d into your own project above, so call Refactron by the absolute path to its build (you're no longer inside the Refactron checkout):

    ```bash theme={null}
    node /path/to/Refactron_Lib_TS/dist/cli/index.js \
      verify-diff . --diff change.diff --test-cmd "python3 -m pytest -q"
    ```

    Refactron copies your project into an isolated shadow tree, applies the diff there,
    runs the gates, and measures whether your tests exercise the changed lines. Your
    real working tree is never modified.

    <Note>
      Coverage is **Python-only**, so only an all-Python diff can return `SAFE`; a TypeScript or
      mixed diff passes the gates and returns `UNPROVEN`. Form that expectation before the verdict
      prints below.
    </Note>
  </Step>

  <Step title="Read the verdict">
    One of three outcomes prints:

    ```text theme={null}
    [SAFE] Tests pass and the changed code is covered.
    ```

    ```text theme={null}
    [UNPROVEN] Tests pass, but the changed code is not exercised by any test.
      uncovered: calc.py:14
    ```

    ```text theme={null}
    [UNSAFE] <the failing test output>
    ```

    `SAFE` and `UNPROVEN` exit `0`; `UNSAFE` exits `1`, so it fails a CI job on its own.
  </Step>
</Steps>

What just happened:

* **`SAFE`**: the gates passed *and* your tests run the changed code (at least one changed line per file). Proven.
* **`UNPROVEN`**: the gates passed, but the change isn't proven. Two causes, two responses:
  * A line is named in the output (`uncovered: calc.py:14`): add a test that exercises it, then re-run to earn `SAFE`.
  * The reason is "coverage of the changed code could not be determined": that's the [Python-only limit](/verification/verdicts#the-python-only-limitation) (a non-Python or mixed diff, or no `coverage.py`). The gates still passed, but no added test changes the verdict today.
* **`UNSAFE`**: a gate rejected the change. A tests-gate failure prints the failing-test tail; a syntax or imports failure prints that gate's reason.

Add `--json` for the full reproducible report. See [Verdicts](/verification/verdicts) for the complete model.

<Warning>
  Coverage is **Python-only** (via `coverage.py`). A TypeScript or mixed-language diff can never
  reach `SAFE` today; it returns `UNPROVEN` ("coverage of the changed code could not be
  determined"). The gates still run; only the coverage half is Python-only.
</Warning>

## Give the gate to your agent (MCP)

The same engine is available as an [MCP](https://modelcontextprotocol.io) tool, `verify_change`, so an AI agent can verify a change before it lands it. Register the stdio server with your client. For Claude Code:

```bash theme={null}
claude mcp add refactron -- node /absolute/path/to/Refactron_Lib_TS/dist/mcp/server.js
```

The agent proposes an edit (as full-file contents or a unified diff), calls `verify_change`, and gets back the same `SAFE` / `UNSAFE` / `UNPROVEN` report, then decides whether to land it. Full setup in [MCP server](/verification/mcp-server).

## Migration mode

Refactron also ships 20 deterministic AST transforms that both *author* a change and *verify* it through the same gates before an atomic write. This is the published npm CLI; install it directly:

```bash theme={null}
npm install -g refactron@0.2.4
cd your-project && refactron login
refactron analyze .              # findings + blast radius + tier
refactron run --dry-run          # preview the diff (no writes)
refactron run --apply            # gates, then atomic write
```

<Note>
  `refactron@0.2.4` on npm is the transform CLI only. It does **not** include `verify-diff`, the MCP
  server, or `preflight`; those are the from-source build above until the next release.
</Note>

See [Migration mode](/transforms/index) for the transform catalog and the [CLI reference](/cli/reference) for every command and flag.

## Next steps

<CardGroup cols={2}>
  <Card title="Verify a diff" icon="shield-check" href="/verification/verify-diff">
    Every `verify-diff` flag, exit code, and the JSON report shape.
  </Card>

  <Card title="Safety model" icon="shield-check" href="/concepts/safety-model">
    The shadow tree, the three gates, and the atomic-write contract.
  </Card>
</CardGroup>