RefactorAI

Getting Started

Quickstart: your first commit-triggered review

Install the CLI, enable the Git hook, and keep RefactorAI watching commits from your terminal, editor, IDE, or Git GUI — before code ever becomes a PR.

10 minDevelopers and tech leads

RefactorAI runs a tight local loop: you commit however you already work — terminal, VS Code, Cursor, JetBrains, GitHub Desktop, or another Git client — and RefactorAI reacts to Git itself. It reviews the changed files plus the code they touch, raises Refactor Requests you resolve in a live terminal, and gates the push. Follow the five steps below to get there.

Everything runs on your machine

The commit loop is local-first. There is no network round-trip on the commit path, and your source never leaves your device.

  1. Step 1 — Install the CLI

    The public CLI is lightweight and contains no proprietary logic. We recommend pipx, which installs refactor as a global command in its own isolated environment — no dependency conflicts with your projects or system Python.

    Install Refactor CLI (recommended)
    # Recommended: global, isolated install via pipx
pipx install refactorai-cli
refactor --help

    Why pipx?

    pipx keeps the CLI on your PATH everywhere while isolating its dependencies. If you'd rather use pip, that works too — just note a project-venv install only exposes refactor inside that venv.
    Get pipx, or use pip instead
    # No pipx yet? Bootstrap it once:
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Windows PowerShell often uses the Python launcher:
py -m pip install --user pipx
py -m pipx ensurepath

# Or fall back to plain pip (installs into the active environment):
python3 -m pip install --upgrade refactorai-cli

  2. Step 2 — Authenticate

    Create an account at refactorai.codes, generate a developer key, and authenticate your CLI session. Bring your own provider key or run a local model — your choice.

    Authenticate with your developer key
    # Sign up and create a developer key at https://refactorai.codes
refactor login --key <your_developer_key>
refactor whoami

  3. Step 3 — Enable the Git hook

    Initialize RefactorAI in your repository and install the git hooks. The post-commit hook is non-blocking (<100ms) and only enqueues the commit — it never slows or fails your commit.

    Initialize and install hooks
    cd <your-repo>
refactor init
refactor hook install   # non-blocking post-commit + pre-push gate

    Commit from the tool you already use

    The hook runs when Git creates the commit, so it works whether you commit from the terminal, VS Code/Cursor Source Control, JetBrains, GitHub Desktop, or most Git GUIs. If a GUI client disables local hooks, commits will not appear in refactor watch until hooks are enabled.

    Your first commit builds a baseline

    The first commit in a repo is reviewed at full-project scope once. After that, every commit is scoped to just the changed and graph-associated files.

  4. Step 4 — Open the Refactor Terminal

    Open one always-on window beside your editor — the same way you keep a dev server running. In VS Code or Cursor, use the integrated terminal; in JetBrains, use the built-in terminal; in Git GUIs, keep any terminal open beside the app. Each commit appears as a node in a live graph, moving queued → reviewing → reviewed with a gate verdict and Refactor Request count.

    Start the Refactor Terminal
    refactor watch            # the always-on Refactor Terminal
# or, headless / for agents:
refactor watch --json

    It can open itself

    With auto-open enabled, the terminal pops up like a dev-server window after your first commit — nothing to remember to run.

  5. Step 5 — Resolve and push through the gate

    Resolve a commit's Refactor Requests in place, then push from the terminal, Source Control panel, or Git GUI. The pre-push gate runs in warn or strict mode; strict blocks the push until the gate passes.

    Resolve, then push
    # In the Refactor Terminal:
#   [r] resolve this commit's Refactor Requests (behavior-preserving)
#   [d] view the diff
#   [p] push through the pre-push gate

git push                  # strict gate blocks until the gate passes

# Escape hatch examples:
# macOS / Linux / Git Bash
REFACTOR_SKIP=1 git push

# Windows PowerShell
$env:REFACTOR_SKIP=1; git push

# Windows cmd.exe
set REFACTOR_SKIP=1 && git push

    Fail-open by design

    A slow or unavailable local run never wedges your push — the gate degrades to warn on timeout.

What's next

Continue with Install & Setup to standardize onboarding for every developer, or read the Developer Workflow guide to see the commit → watch → resolve → push loop in daily use.