(04)
Documentation
Every command, config key and concept — versioned with the CLI and answered by the agent itself.
v2.4.1
Updated weekly
14 articles
Search docs…
GETTING STARTED / 01
Installation
Rafan ships as a single binary for macOS, Linux and Windows, and as an npm package for CI environments. The binary auto-updates; npm installs pin the version you choose.
You need Git 2.30 or newer. Node 20+ is only required for the npm distribution.
$ npm install -g rafan
$ rafan --version
rafan/2.4.1 · agent core 7
GETTING STARTED / 02
Quickstart
Point Rafan at a repository, describe the change you want and review the plan it drafts. Nothing is written until you approve the diff.
Sessions start from the context graph, so the agent already knows your folders, scripts and open tasks — no onboarding prompt required.
$ rafan
> add an audit log to the billing service
plan ready · 4 files · 2 commands
GETTING STARTED / 03
Authentication
Rafan authenticates with short-lived device tokens. Run rafan auth login once and the CLI stores a scoped credential in your OS keychain.
Team workspaces can enforce SSO. Tokens inherit the scopes of the member who created the session and expire after twelve hours.
$ rafan auth login
> opening browser · device code 8F2K-1QX
signed in · workspace rafan-labs
CORE CONCEPTS / 01
The context graph
The context graph indexes every file, symbol and script in your repository, then links them to the tasks and plans you have run before.
It lives in .rafan/graph and updates incrementally, so a fresh session understands the project before the first prompt is sent.
$ rafan graph status
nodes 12,480 · edges 38,204
last sync 4s ago · 96% fresh
CORE CONCEPTS / 02
Project memory
Memory files store the decisions your team makes: conventions, ownership and the reasons behind past changes.
Rafan reads memory before planning and writes back a short note after each approved diff, so knowledge accumulates instead of resetting.
$ rafan memory add billing
> service owns invoice + refund flows
saved to .rafan/memory/billing.md
CORE CONCEPTS / 03
Plans & diffs
Every change starts as a plan: files to touch, commands to run and risks to check. Approve it once and the diff is applied to a branch.
Plans are plain text, so they can be reviewed in a pull request before a single line is executed.
$ rafan plan “add retries to webhooks”
3 files · 1 migration · 0 commands
apply? › branch feature/webhook-retries
CORE CONCEPTS / 04
Sandboxing
Commands run in a disposable sandbox with no network unless the plan requests it. The repository is mounted read-only until you approve writes.
Limits are configurable per workspace; anything that escapes the sandbox shows up in the run log as a blocked action.
$ rafan run --sandbox strict
network off · fs read-only · 2 cpu
exit 0 · 41s · nothing blocked
GUIDES / 01
Monorepos
Point Rafan at a workspace root and it maps each package, its scripts and the dependencies between them.
Plans stay scoped to the packages they touch, so a change to the billing service never rewrites the design system.
$ rafan init --workspace
packages 14 · apps 3 · shared 2
graph saved · boundaries respected
GUIDES / 02
Custom commands
Commands are small, reviewable scripts stored next to your code. Run them by name in the CLI or from the command palette.
Each command declares the files it may read and the shell it may use, which keeps automation predictable for the whole team.
$ rafan cmd list
audit-log · seed-db · release-notes
$ rafan cmd audit-log --since 7d
GUIDES / 03
MCP connectors
Connect external tools through the Model Context Protocol. Rafan discovers the tools a server exposes and offers them to the agent.
Connectors are declared in rafan.config.json and can be limited to read-only calls while you are still evaluating one.
$ rafan mcp add linear
connected · 12 tools · read-only
tools cached for this workspace
GUIDES / 04
CI mode
In CI, Rafan runs headless: it drafts a plan, prints the diff and exits with a status code your pipeline can gate on.
No prompts, no interactive approvals. Anything that needs a human is reported as a pending action.
$ rafan ci --plan-only
plan · 2 files · 1 command
exit 0 · awaiting review in PR
REFERENCE / 01
Configuration
One file configures the workspace: models, sandbox limits, connectors and the commands available to the agent.
Values can be overridden per directory, which makes it safe to tighten rules inside sensitive packages.
$ rafan config show
model rafan-4 · sandbox strict
telemetry off · memory on
REFERENCE / 02
CLI reference
All commands share a small set of flags: --json for machine output, --dry-run to preview and --workspace to target a package.
Run rafan help with a command name for the full list of options, or read the generated manual in .rafan/manual.
$ rafan help apply
usage · rafan apply <plan> [--dry-run]
flags · --json --workspace --yes
REFERENCE / 03
Permissions
Permissions decide what the agent may do without asking: read files, write files, run commands, reach the network.
Grant the smallest scope that works. Every elevation is logged and can be revoked from the workspace settings.
$ rafan perms
read · write(plan) · exec(sandbox)
network · denied · 0 overrides
Prefer email?