Renitor — the guide.

From your first handoff to a multi-model chat that keeps going when a provider caps. Five minutes to your first handoff.

Install

VS Code: Extensions panel → search "Renitor" → Install. Or from a .vsix: Extensions → ··· → Install from VSIX…

Cursor / Windsurf / VSCodium: install from Open VSX (these editors don't use the Microsoft marketplace).

After a reload you'll see ⇄ Handoff in the status bar — the one-click path.

Your first handoff

Work normally in any agent (Claude Code, Codex, Aider…) inside VS Code's terminal.
When you hit a wall — or the limit toast appears — click ⇄ Handoff (or run Renitor: Generate Handoff).
Pick the target agent. Two things happen: .renitor/current-handoff.md is written (goal, diff, errors, decisions — secrets scrubbed), and a paste-ready prompt in that agent's dialect lands on your clipboard.
Paste into the next agent. It reads the handoff and continues.

Targeting a web chat LLM (ChatGPT free, Gemini, DeepSeek…)? Use Copy Chat Prompt — web chats can't read files, so the whole handoff is inlined into one bounded paste.

The rotation loop Claude ⇄ Codex

Detect — Claude Code prints "usage limit reached" → a toast offers the handoff. One click, and the Codex prompt is on your clipboard.
Detour — work in Codex until Claude's window resets.
Hand back Free — run Renitor: Hand Back to Previous Agent → choose Claude Code — native resume. A new session is injected into Claude's own history: your pre-detour context plus what Codex did (read from Codex's session log + git delta). The claude --resume <id> command is copied — run it, and Claude simply knows.

BYOK & API mode

BYOK mode is your hedge: if a vendor ever moves headless CLI usage out of subscriptions, the chat keeps working on your own API key — one setting flip.

Run Renitor: Set API Key (BYOK) → pick OpenRouter (recommended — one key reaches every model), a direct Anthropic / OpenAI key, or a free Google AI Studio (Gemini) key → paste it. Stored in your OS keychain via VS Code SecretStorage — never on disk, never in a handoff, redacted from all logs.
Set renitor.chat.mode to byok.
Chat as normal — turns now run against the provider API, metered on your key, with the live cost meter on. Remove keys anytime with Clear API Keys (BYOK).

BYOK supports OpenRouter (one key, all models), Anthropic (Claude), OpenAI (GPT) and Google AI Studio (Gemini, free tier). Other agents run in CLI mode. Tip: set a hard spend limit on your key's provider page and keep auto-recharge off — spend stays capped.

Multi-model chat

Renitor: Open Multi-Model Chat Free opens a chat panel inside VS Code where Claude, GPT, Gemini and 19 free models share one thread. Switch models from the dropdown mid-conversation — the history is provider-neutral, so it's instant.

Streams live: replies appear token-by-token as the model generates them, not as a wall after a pause — Stop ends a long one and keeps what streamed. Sessions persist per-workspace across restarts (Clear wipes the current session's messages and cost; other saved sessions are untouched).
Session history: ＋ starts a fresh named session and 🕐 lists every saved conversation in the workspace — switch back, rename inline, or delete. Titles auto-derive from your first message (until you rename by clicking the title). Seven themes — Studio, plus Claude, ChatGPT and Gemini in light and dark — switch live from the / menu → Appearance.
Claude-Code-style composer: a context ring shows how full the model's window is and auto-compacts past 80% (oldest messages fold into a summary, recent turns stay full); a mode pill switches the permission level (Plan / Manual / Auto-edit / Auto — Tab cycles); a mic button records your voice and transcribes it into the box (Whisper, via your OpenAI key).
Approvals in the thread — even on the subscription CLI: an Allow/Skip card appears inside the conversation (and mirrored above the composer with ⌘⏎ Allow / ⌘⌫ Skip). Scopes range from once, to this chat, to persistent rules like npm or npm run *. Skip never kills the turn — the model is told to proceed without the tool.
Watch the agent work: every tool call is a live card — spinner while it runs, ✓/✗ when it finishes, click to expand the output (edits show a real +/− diff). After a turn that changed files: a Files changed (N) bar with one-click Revert this turn.
Type while it streams: your next message queues and sends the moment the reply finishes.
Attach anything: the + opens a picker — active file or selection, any open tab, or files from disk. Text embeds (bounded, secret-redacted); images attach as real vision input on Claude/GPT keys (and the claude CLI reads them from disk). You can also just paste a screenshot into the box.
Per-model memory access: the shared project memory reaches every model by default; / → Memory access per model… excludes any model per workspace — it then gets none of the brief in its prompt.
Your agents & skills, cross-model: the same .claude/agents/*.md and .claude/skills/ files Claude Code uses (or tool-neutral .renitor/ equivalents) work in the chat — @reviewer applies the persona, /deploy-check staging runs the skill, on whatever model has the turn. Listed in the / menu.
Clarifying-question cards: an ambiguous task gets up to 3 short multiple-choice questions as clickable cards (plus an "Other" box); your answers flow back into the same turn. Available to every BYOK/free model via the ask_user tool; Team chat's boss interview asks with the same cards (typed answers remain the fallback).
The providers hub: / → Model providers… shows every provider with an honest status — sign in with the subscription you already pay for (Claude, ChatGPT/Codex; Gemini & Cursor CLIs as handoff targets) or add an API key (one free OpenRouter key unlocks the free models).
Always-visible working indicator: a status line above the composer for the whole turn — thinking → running → reading output → writing — with elapsed time and Stop (Esc).
Smart handback: after a limit-driven switch, Renitor tracks when that provider's window should reset and offers, in-thread, to hand the session back.
In-thread tools: reviews (pick reviewer + scope on cards, report lands in the conversation), handoff and handback all run inside the chat — no OS pickers or popups.
Multi-model moves: Team chat (the boss & worker duo: the boss interviews you, writes a living work order, the next model in your chain builds it with real tools, and the boss reviews the actual changed files — sending revisions back until it approves; pin the pair with renitor.route.boss/renitor.route.worker), Debate (two models argue until one concedes), /consensus (3 models answer, one merged synthesis with disagreements called out), Improve (another model critiques, yours rewrites), and @sonnet/@gpt/@qwen mentions to route any message.
See it work, live: command output streams into the tool card while it runs; Compare shows a turn's changes as a native multi-file diff next to Revert.
Operating modes — Economy / Balanced / Best: one row in the / menu sets how hard the session protects your wallet. Economy runs everything routine on free models and pays only for genuinely complex work, Balanced mixes cheap models for routine messages with strong ones for hard tasks, Best puts the strongest model on every turn. Hand-editing the model chain or the Smart toggle drops back to Manual.
Smart routing: turn on Smart routing from the / menu and every message goes to the cheapest model that can handle it — quick questions hit free models, complex tasks get a strong one. Stretches your subscription before limits ever hit; the thread says which model answered and why.
The savings ledger — your receipt: Renitor counts, locally, every provider limit it survived and every token it ran on free models, priced at what a paid model would have charged. Click Saved so far in the / menu for a shareable receipt card — copy the text or save it as an image. Counted on your machine, never phoned home; dollar figures are labeled estimates.
Guardian model (Auto mode): a cheap second model reviews every shell command before Auto runs it — anything risky pauses for your approval. On by default (renitor.chat.guardian).
Per-message actions: hover any reply for Copy, Regenerate (a failed retry restores the previous answer), and Second opinion — a different model critiques or validates that specific reply.
Approve once, remembered: when an agent asks to run a shell command, "Always allow" adds that binary to a persistent allowlist — it never asks for that one again (compound commands are never auto-allowed).
Falls back automatically: when a model hits a rate limit or runs out of credits, the thread auto-switches to another model in place and keeps going — no copy-paste, and you can see what carried over.
One key, every model: with an OpenRouter key, Claude + GPT + fallback all run on a single prepaid balance. Direct Anthropic/OpenAI keys work too.
Reads like a doc: full markdown — headings, lists, bold, inline code, links, and code blocks with a one-click Copy button.
Cost in view: a live strip shows tokens used and this session's spend. It opens on a cheap model by default.
It sees your code: ＋ Add file / selection attaches the active editor's file (or your selection) to your next message — bounded and secret-redacted. Or right-click a selection → Ask Renitor about this. The in-editor edge a browser chat can't match.

Two ways to run it (renitor.chat.mode): subscription (default) drives the claude/codex CLI you're already logged into — your existing plan, no API key. It never touches auth tokens; it just invokes the official CLI, so it stays ToS-conscious. Tools live inside the chat too: a toolbar and slash commands (/review, /adversarial, /handoff, /handback, /attach, /mode, /chain, /history, /new, /export, /clear) — review reports render in the thread and findings land in the Problems panel. byok uses your own metered API key (one OpenRouter key reaches every model), stored in the OS keychain. Subscription mode is best-effort — if a provider restricts headless subscription use, BYOK is the always-available fallback.

All commands

Command	What it does
Generate Handoff	The main one — handoff file + clipboard prompt. Also on the status bar.
Copy Claude / Codex / Generic / Chat Prompt	Refreshes the handoff if stale, copies that dialect. Chat inlines the whole brief.
Open Multi-Model Chat Free	One thread, many models (Claude, GPT, Gemini + 19 free), switch in place, auto-failover on limit/credit. BYOK.
Hand Back to Previous Agent Free	The return leg — handback.md for any agent, native session injection for Claude Code.
Generate PR / Branch Handoff Free	Briefs on a whole branch: diff vs merge-base + commit list. Pure git.
Generate Handoff for Selected Files Free	Right-click files in the Explorer → focused handoff embedding their contents.
Run Tests & Capture Output	Runs an inferred (or custom) command; failing output lands in the next handoff.
Capture Terminal/Error Notes	Editor selection → terminal selection → quick paste → opens the notes file.
Set / Clear API Key (BYOK)	Store provider API keys in the OS keychain for the chat's BYOK mode.
Edit Project Memory / Open Handoff / Reset	Durable facts file · open current handoff · clean slate (memory kept unless double-confirmed).
Enter License Key / License Status	License activation (offline) — not needed during the free open launch.

Settings that matter

Setting	Default	Notes
defaultTargetAgent	claude	Or `ask` for a picker. 12 options.
detectLimitHits	on	The limit toast.
includeAgentSessionTrace	on	Auto-goal from local session logs (Pro at generation time).
permissionMode	autoEdit	plan / manual / autoEdit / auto — how much the model may do in your workspace without asking. Switch live from the chat's mode pill (Tab cycles).
chat.mode	subscription	`subscription` (your logged-in CLI) or `byok` (your API key).

Pro & licensing

Everything — the multi-model chat (subscription + BYOK), the round-trip handback, session-trace goal inference, PR/focused handoffs — is free during the open launch. No signup, no key, no trial clock. If a paid tier returns after the launch period, the build you installed keeps working.

Privacy & honest limitations

Local-first, documented network behaviour: no backend, no telemetry, no calls home to Renitor — the local features (handoff) make no network calls at all; the chat reaches only the provider you choose (your subscription CLI or your own key).
Keys & tokens: BYOK keys live in the OS keychain, redacted from every log. CLI mode launches official CLIs under your own logins — auth tokens are never touched or wrapped.
It does not bypass rate limits — it makes them painless (CLI rotation) or irrelevant (BYOK).
Secret redaction (patterns + your .env values) is defense-in-depth, not a guarantee — the handoff shows a redaction count and says so.
Session formats are undocumented and can change; handback injection is strictly additive (writes a new file, never edits yours), so it degrades to a markdown brief rather than touching your data.