remora

Run Claude Code with a cost-aware GPT-5.6 agent fleet for one session.

remora launches Claude Code with session-scoped OpenAI model routing, role agents, and orchestration. Sol handles planning and critical review, Luna handles lower-cost exploration and implementation, and Terra is the balanced interactive option. Exiting the child session removes every override.

繁體中文

Contents

• What remora changes
• Architecture and model map
• Requirements
• Install
• Configure
• Use
• Isolation and security
• Troubleshooting
• Uninstall
• Further reading

What remora changes

Core guarantee: plain claude keeps its original credentials, settings, agents, and model routing. remora changes only the child process it launches.

Large Plans use a reviewed program envelope followed by independently approvable execution slices. Two automatic REVISE verdicts pause only the affected readiness unit; unrelated READY slices may proceed after explicit approval. By default, the next executable slice is reviewed and presented for approval before downstream slices. Security-sensitive units require read-only security evidence before the first Plan review for that unit. The complete contract belongs in the architecture document.

Architecture and model map

flowchart LR
    USER["Developer"] -->|claude| NATIVE["Native Claude Code"]
    USER -->|remora| LAUNCHER["remora launcher"]
    LAUNCHER -->|child-only environment| GATEWAY["Anthropic-compatible gateway"]
    LAUNCHER -->|session agents and policy| RUNTIME["Claude Code runtime"]
    RUNTIME --> SOL["OpenAI Sol
planning and verification"]
    RUNTIME --> LUNA["OpenAI Luna
recon and implementation"]
    RUNTIME --> TERRA["OpenAI Terra
balanced interactive use"]

remora is a launcher, not a proxy. Bring an Anthropic Messages-compatible gateway such as CLIProxyAPI; the gateway owns protocol translation, OAuth, retries, cooldown, and billing.

Runtime behavior and reference documents:

Requirements

Install

Approval-gated install

Give Claude Code this immutable-tag runbook:

Read and follow this installation runbook:
https://raw.githubusercontent.com/Nanako0129/remora-cc/v0.1.15/install/AGENT-INSTALL.md

Perform only the read-only preflight first. Show every proposed filesystem
change, trust boundary, download source, and verification step. Do not write
anything until I explicitly approve.

The runbook stops for approval, verifies SHA-256 and GitHub artifact attestation, installs atomically, and confirms that ~/.claude did not change. It never asks for a bearer token or OAuth file.

Manual source install

git clone --branch v0.1.15 --depth 1 https://github.com/Nanako0129/remora-cc.git
cd remora-cc
./install.sh

The installer does not edit PATH. Add it yourself when needed:

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

Configure

Deploy the gateway first with the CLIProxyAPI quick start, then edit the generated file:

${EDITOR:-vi} ~/.config/remora-cc/config.toml

Use an environment variable for a quick smoke test:

export REMORA_AUTH_TOKEN='replace-me'
remora doctor --online

For daily macOS use, prefer Keychain:

[proxy]
base_url = "http://127.0.0.1:8317"
auth_token_env = "REMORA_AUTH_TOKEN"
auth_token_command = [
  "security",
  "find-generic-password",
  "-a", "YOUR_MACOS_USER",
  "-s", "cliproxyapi",
  "-w",
]

The environment variable wins when present. Otherwise remora executes the credential command directly without a shell. Existing pre-eight-role configs remain compatible; use config.example.toml to add independent Plan and security reviewer routing.

Use

cd ~/src/my-project
remora
remora --continue
remora -p 'summarize this repository'

Unknown arguments pass through to Claude Code. Explicit --model or --agents values replace only that remora default. --fallback-model is rejected to keep automatic fallback disabled; content after -- remains untouched.

Fast mode is opt-in and session-only:

remora --fast --continue
remora dry-run --fast --continue

Note: Fast requests service_tier=priority from the gateway. It may cost more and does not bypass provider quota.

Isolation and security

remora agents
claude --version

The first command should show the OpenAI role map; the second remains native Claude Code. For file-level evidence, compare a SHA-256 manifest of ~/.claude before and after installation.

⚠️ Security boundary: the gateway and upstream model still receive every prompt and source file Claude Code sends. Read SECURITY.md before using a remote gateway on sensitive repositories. Managed organization policy has higher precedence than remora and can change fallback or role behavior.

Troubleshooting

⚠️ Do not disable gateway cooldown globally as the first fix. A real upstream rate limit can become a retry storm. See the gateway runbook for diagnosis and the narrow active-turn exception.

Uninstall

"${XDG_DATA_HOME:-$HOME/.local/share}/remora-cc/uninstall.sh"
"${XDG_DATA_HOME:-$HOME/.local/share}/remora-cc/uninstall.sh" --purge

The default keeps config.toml; --purge removes it. Neither command touches ~/.claude.

Further reading

remora packages the role-based orchestration pattern established by pilotfish and composes with optional delegation planning such as Baton. It does not claim to invent multi-agent routing.

License

MIT