Installation

This page will inshallah take you from a fresh checkout to a working refac and a list of the language tools you still need.

Install from a releaseCopy Anchor Link

No Rust is needed. Each release on GitHub has an archive for Linux x86_64 and a SHA256SUMS file. Download both into one folder and replace 0.1.4 with the version you downloaded:

sha256sum -c SHA256SUMS
mkdir -p ~/.local/share/refac ~/.local/bin
tar -xzf refac-0.1.4-linux-x86_64.tar.gz -C ~/.local/share/refac
ln -sfn ~/.local/share/refac/refac-0.1.4-linux-x86_64/refac ~/.local/bin/refac
refac --version

refac --version should inshallah print the version you downloaded, with the commit it was built from. The archive holds the binary, the TypeScript and Python helper scripts it starts (scripts/), a pyrefly.toml and the license, so keep the folder together. To upgrade, run the same commands with the new version and delete the old folder. If ~/.local/bin is not on your PATH, add this to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Prerequisites for building from sourceCopy Anchor Link

Rust 1.99 or newer (edition 2024) builds refac. You only need it to build from source. The repository pins Rust 1.99.0 together with rustfmt and rust-analyzer in rust-toolchain.toml, so rustup picks the right toolchain by itself.

Platform: Linux. macOS and Windows are not targets, so nothing is tested or promised for them.

InstallCopy Anchor Link

git clone https://github.com/jav-ed/ai_refac.git
cd ai_refac
scripts/install.sh

scripts/install.sh builds the release binary, links it as ~/.local/bin/refac, and checks that the refac on your PATH is that build and was built from the commit you checked out. It ends with a line like this, or stops with the reason:

installed and current: refac 0.1.4 (55b157a, built 2026-10-09 20:09 UTC)

Run it again after every pull. It takes seconds when nothing changed. refac --version shows the same stamp at any time, and it should inshallah name the commit you checked out.

Keep the checkout where you built it. The TypeScript and Python helper scripts in scripts/ are read from the checkout at run time, and when one cannot be found the error lists every place that was looked at.

If ~/.local/bin is not on your PATH, the script says so and stops. Add this to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

By handCopy Anchor Link

cargo build --release

# A link follows every rebuild
ln -sf "$(pwd)/target/release/refac" ~/.local/bin/refac

# A fixed snapshot instead
cp target/release/refac ~/.local/bin/refac

cargo install --path . also gives a fixed snapshot.

Language toolsCopy Anchor Link

refac does not bundle language servers. The one exception is the TypeScript engine, which it installs on first use. A server is started for one command and stopped when the command ends, and you only need the tools for the languages you use.

No minimum version is enforced for external tools, but use recent releases.

Check what is readyCopy Anchor Link

refac doctor

One line per language: ready, MISSING, or broken, with the version and the place where the server was found. No server is started, so it returns at once. Run it before your first move and you will inshallah know what is missing before a command has to tell you. The output looks like this:

  go          MISSING  gopls: not usable
  rust        ready    rust-analyzer 1.99.0 (b940084 2026-09-28) (~/.cargo/bin/rust-analyzer)
  python      MISSING  basedpyright: not usable
  dart        MISSING  the Dart analysis server (dart language-server): not usable
  kotlin      MISSING  the JetBrains Kotlin language server: not usable
  typescript  ready    installed (scripts/node_modules/typescript-native)

For one language, name it:

refac doctor go

refac looks for the server exactly as a command would, starts it, waits for the handshake, and stops it again. It prints the version, the path, and, when something is wrong, the numbered steps that fix it. The exit code is 0 when the server is ready and 1 when it is missing or broken, so a script can branch on it.

When a move or rename needs a server that is not there, the command fails before any file is touched. The error lists every place that was looked at and points at refac doctor <language>. After you install the tool, run the original command again and it should inshallah go through.

Shell completions and manual pageCopy Anchor Link

refac completions bash > ~/.local/share/bash-completion/completions/refac
refac man | man -l -

completions supports bash, zsh, fish, elvish, and powershell.

NextCopy Anchor Link

With the tools in place we can inshallah move on to Usage, the commands you will use every day.