open source · MIT · node ≥ 20

A local-first agent
you assemble yourself.

One agent, tailored to the job: it writes code and checks its own work, reviews like a senior, runs your day — and becomes whatever agent you describe in a markdown file. On a model on your own machine, or a cloud one.

$ curl -fsSL https://raw.githubusercontent.com/lucasaguilar/rei/main/install.sh | bash
$ cd ~/my-project && rei

$ git clone https://github.com/lucasaguilar/rei && cd rei
$ npm install && npm run build
$ ./install-rei-cli-local.sh

setup wizard on first run no account no telemetry by default

✓ tsc --noEmit · 0 errors

a session

It doesn't take the model's word for it.

REI runs your project's real compiler before the turn ends, hands the model its own errors to fix, and reports what it actually found.

!Your shell, zero inference. !npm test runs locally; the model never sees it.
⇪You decide what it sees. /attach hands over the one output that matters, as verified evidence.
✓Verified, not claimed. The edit is checked with tsc, cargo check, go build… before it says "done".

~/my-project — rei

one agent, tailored to the job

Local for free, cloud when it counts. No lock-in.

Drop a markdown file in .rei/ and it is there next session — no build, no plugin API, no fork.

🧠

Codes

And runs your project's own compiler or tests before it says "done". Failures go back to the model with the compiler's own message.

ask · planning · agent

🔍

Audits

A reviewer role in your session, or an isolated sub-agent on a different model — because the same weights tend to agree with themselves.

/auditor audit @plan.md

☀️

Runs your day

News, weather, your morning briefing; email and music through the MCP servers you connect. Never touches your repo.

/persona daily

🧩

Yours

Personas, roles and skills are files you write — and the limits they declare are enforced in code, not suggested in a prompt.

.rei/roles/*.md

why it verifies

A model's claim is worth nothing on its own.

REI detects what the project is and runs that project's own verify command against the edits. Two attempts to reach green — and if it can't, the turn ends on a warning, not on a report that implies it passed.

The check never lies about its own strength. An unrecognised project gets no verify command rather than a fake pass.

Your own oracle? Point REI_SANDBOX_VERIFY_COMMAND at a linter, a test suite or a Makefile target.

Project	Verify command	Proves
TypeScript	`npx tsc --noEmit`	types
Angular	`npx ngc --noEmit`	types + templates
Rust	`cargo check`	compiles
Go	`go build ./...`	compiles
C#	`dotnet build`	compiles
Java · Kotlin	`mvn compile` · `gradle`	compiles
Swift	`swift build`	compiles
Dart · Flutter	`dart analyze`	types
Python + mypy/pyright	`python3 -m mypy .`	types
Python	`python3 -m py_compile`	syntax only
PHP	`php -l`	syntax only
Luau	`luau-analyze` · `selene`	analysis
anything else	—	nothing, on purpose

cloud or local, same tool

Built for the model on your machine. Not a fallback.

Per-mode models, per-model tuning and on-demand context exist because a 30B on your laptop is not a frontier model behind an API. KV-cache-friendly prompts, files read once, large tool output spilled to disk.

Local free · private · offline

LM Studioprimary oMLXApple Silicon Ollama MTPLX

Cloud your API key

OpenRouter Google Gemini Groq Hugging Face

Anything OpenAI `/v1` openai-compat

vLLM llama.cpp SGLang LiteLLM LocalAI your gateway

mix them, and pay for less

Exploring is the expensive half.

Run ask and planning locally — the many, chatty turns — and put only the agent turns you want to get right on a frontier model. The housekeeping models (compaction, vision) stay on the local side by design.

tool calls in one ask turn

28.5k

input tokens — billed locally: $0

# .rei/.env
MODEL_PROVIDER=lmstudio        # ask + planning — free
LMSTUDIO_MODEL_ASK=ornith-1.5-35b-a3b
LMSTUDIO_MODEL_PLANNING=qwen3.8-27b

AGENT_MODEL_PROVIDER=openrouter  # the edits worth paying for
OPENROUTER_MODEL_AGENT=<a frontier model>

three modes

Ask, plan, then act.

Each mode can run its own model: a small fast one to ask, the strongest reasoner to plan, the most reliable tool-caller to execute.

askread-only

Answers questions about the repository.

planningread-only

Produces a structured, stage-by-stage plan.

agentedits files

Executes: reads, edits, runs commands, verifies.

extend it

Everything that shapes REI is a markdown file.

No build, no plugin API, no fork. And what a file declares is enforced — it can only ever narrow what's allowed.

A whole posture: which mode it starts in, what it may write, which model it prefers.

.rei/roles/auditor.md

---
name: auditor
description: Adversarial review of a plan BEFORE implementation
baseMode: planning
writeGlob: "*.review.md"
preferredModel: gemma-4-26b-a4b
---
You are an extremely critical Lead Architect. Your ONLY job is to find what is
wrong, missing or risky. You are NOT here to implement or encourage.

writeGlob is a write scope — the auditor can persist plan.review.md and nothing else.
preferredModel actually runs. Give the reviewer different weights.

One definition, two ways to run it. They differ on one thing: whose context it runs in.

/role auditor             # wear it HERE — your history, your session
audit @plan.md

/auditor audit @plan.md   # run it ISOLATED — fresh session, returns a report

The worker starts with a small, clean window; your context grows by its report only.
/runplan gives each plan stage its own worker; in agent mode the model has a delegate tool.

A persona replaces the coding agent: its own identity, knowledge and permissions. A tutor, a help desk, a sales assistant on WhatsApp, a concierge for your mornings.

.rei/personas/daily.md

---
name: daily
description: Daily concierge + the AI morning briefing
tools: [web_search, weather, read_files, edit_file, "mcp:*"]
skills: [daily-ai-briefing]
knowledgeDir: news
writeGlob: "news/*.html"
---
You are a daily concierge: weather, headlines, music, quick lookups.
You are NOT a coding assistant.

Gets the tools it lists and no others; reads only knowledgeDir; writes only writeGlob.
A channel caps it further — over WhatsApp, read-only.

A markdown recipe the model loads when the task calls for it — per project or for every project.

# per project
.rei/skills/<name>.md
.rei/skills/<name>/SKILL.md     # Claude Code layout loads unchanged

# everywhere
~/.config/rei/skills/

Ships with spec writing, task decomposition, test writing and spec verification.

Project rules — .rei/rules.md is prepended to every coding turn. REI ships no rules about your stack: they belong to the repo. /rules shows what the file costs you per turn.

MCP servers — declared in rei.config.json; their tools join the session. Past 25 tools they go behind a search tool, so a large server does not eat the window.

/rules install <stack>    # a starting ruleset to edit
/roles new <name>         # scaffold a role
/persona daily            # switch agent · /persona off

spec-driven development

Keep the work tied to what you actually asked for.

One bounded task with a criterion attached beats a fourteen-stage plan held in a context window. Every stage ends with its own Verify: command.

/spec

Writes .rei/specs/<name>.md with numbered acceptance criteria.

/decompose

A plan whose every stage cites a criterion: Satisfies: AC-2.

/trace

Crosses spec and plan both ways — finds stale criteria deterministically.

/runplan

One stage at a time, or every stage on its own isolated sub-agent.

METNOT METUNVERIFIED — three verdicts, with evidence. "I could not check this" is a real answer.

privacy, logs and traceability

With a local backend, nothing leaves the machine.

No account, no telemetry endpoint, no code uploaded for indexing. Telemetry is opt-in twice over: without a key the SDK is not even loaded.

✓Writes cannot leave the workspace, in any mode.

✓Credential files are not served to the model; secrets are masked in command output.

✓Destructive commands need your confirmation — and refuse when there's no one to ask.

!Said plainly: the command allow-list is not a sandbox, and opening an unfamiliar repo is running its AGENTS.md.

.rei/
├── logs/agent-flow.jsonl   # one JSON line per event
├── sessions/              # resumable: /session load
├── specs/ plans/ reviews/  # the SDD artifacts
├── tool-output/           # large results, spilled
├── roles/ personas/ skills/
├── rules.md
└── .env                   # .gitignore'd for you

Every turn is a correlated chain — USER_PROMPT → CONTEXT_SEARCH → COMMAND_EXECUTED → PATCH_OUTCOME. "What did it do, and why did that edit land?" is answerable afterwards, from disk, with grep.

use it from anywhere

Terminal, pipeline, or server.

Interactive

The full session: modes, roles, !shell, /attach, documents and images.

$ rei

One-shot

For scripts and pipelines. stdout carries the answer and nothing else.

$ rei ask "how is auth wired?"
$ rei agent "fix the failing test"

Server

An OpenAI-compatible API — point Continue.dev at it. Binds 127.0.0.1; a token is required to go public.

$ rei-server
/chat/completions · /models

who it's for

If one of these is you, REI was built for you.

💻 You run a model on your own machine

LM Studio, oMLX, Ollama, MTPLX — and you want an agent built for that.

🔒 Your code cannot leave the building

Regulated work, an NDA, a client who says no. Local-first is the requirement.

🧪 An agent said it changed something. It hadn't.

Or it had, and nothing compiled. REI reports what it actually found.

💸 You're paying per token

For work a machine you already own can do. Split it instead of choosing.

⌨️ You'd rather type `git status`

Than wait for a model to. !cmd runs with no inference.

🎓 You want an agent for one job

A tutor, an advisor, a help desk, a concierge — one markdown file, its limits enforced.

Start in under a minute.

The first run has no configuration, so REI starts the setup wizard by itself — and lists the models your local server already has.

$ curl -fsSL https://raw.githubusercontent.com/lucasaguilar/rei/main/install.sh | bash

★ Star on GitHub Developer guide →

A local-first agentyou assemble yourself.