Getting started

1. Install the server

uv tool install "refract @ git+https://github.com/sitien173/refract#subdirectory=server"

2. Configure targets and profiles

Create ~/.refract/config.toml. Start from server/config.v3.toml, which shows every supported key:

[daemon]
default_profile = "base"

[[targets]]
id = "codex-code"
backend = "codex"
reasoning = "high"

[[targets]]
id = "claude-review"
backend = "claude"
model = "sonnet"
args = ["--safe-mode", "--strict-mcp-config", "--tools", "Read,Grep,Glob"]

[profiles.base]
implement = "codex-code"
review = "claude-review"
consult = ["claude-review", "codex-code"]

In Claude Code, run /refract:setting-up-refract after installing the plugin. It scans your worker CLIs and writes this file with you.

3. Check and start the daemon

refract doctor
refract serve

refract doctor exits 0 when the state directory is writable and every target executable resolves. The daemon listens on http://127.0.0.1:8765/mcp.

4. Install the plugin

Run refract install with the host you use:

refract install -p claude
refract install -p claude,codex,pi
refract install -p all

-p takes claude, codex, agy, agy-ide, pi, or all. Pass a comma list or repeat the flag. all means every host CLI found on PATH, plus agy-ide when the Antigravity IDE is present. Add --dry-run to print the planned commands without running them. Use refract uninstall -p <host> to remove the plugin. See the Installing section of plugin/README.md for scopes and sources.

The standalone Antigravity IDE has no plugin CLI, so agy-ide works differently: Refract copies the plugin files itself, to ~/.gemini/config/plugins/refract/ for user scope or .agents/plugins/refract/ in the current directory for project scope. Without --source, Refract shallow-clones the GitHub repository into a temporary directory, which needs git. Pass a local clone with --source to skip the clone. Refract leaves a marker in what it copies and will not delete a directory it did not install.

To install by hand, use the host’s own commands.

Claude Code:

claude plugin marketplace add sitien173/refract
claude plugin install refract@refract

Codex:

codex plugin marketplace add sitien173/refract
codex plugin add refract@refract

Antigravity:

agy plugin install https://github.com/sitien173/refract

Pi:

pi install https://github.com/sitien173/refract

When the daemon is not running, the plugin’s SessionStart hook starts refract serve in the background.

5. Run the workflow

Command Purpose
/refract:brainstorm <idea> Clarify intent and trade-offs, then write a design.
/refract:write-plan <design> Turn a confirmed design into a phase plan.
/refract:execute-plan [target] Run one wave of phases through all three gates.
/refract:execute-plan-all [target] Run every wave through final audit without pausing.
/refract:debug <symptom> Diagnose a bug from runtime evidence before fixing it.

In Pi, drop the refract: prefix, for example /brainstorm.

Source: README.md