remora

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

remora attaches OpenAI GPT-5.6 models to Claude Code for one session. Sol plans, orchestrates, and verifies critical work; Luna handles exploration and implementation at lower cost; Terra provides a balanced everyday switch. Claude Code remains the interface, tool runtime, and agent orchestrator. Like the fish it is named after, remora leaves its host unchanged when the session ends.

繁體中文

Contents

• What it changes
• Architecture
• Model map
• Who it is for
• Trust and security
• Requirements
• Install
• Configure
• Use
• Verify isolation
• Questions and answers
• Operational notes
• Operational security
• Uninstall
• Prior art

What it changes

remora launches a child claude process with a session-only --agents JSON document, a session-only orchestration addendum, and a child-only gateway environment. Claude Code officially documents --agents as a current-session source that outranks project and user agent files without persisting them. The addendum schedules independent work in the background and reserves foreground agents for immediate blocking dependencies.

Core guarantee: quitting remora ends every override. Running claude afterward uses the same command, credentials, settings, and agents it used before installation.

Architecture

flowchart LR
    U[Developer] -->|claude| N[Native Claude Code]
    U -->|remora| R[remora launcher]
    R -->|child-only env| G[Anthropic-compatible gateway]
    R -->|session-only agents + orchestration| C[Claude Code runtime]
    C -->|orchestration and judgment| SOL[OpenAI Sol]
    C -->|recon and implementation| LUNA[OpenAI Luna]
    C -->|default Sonnet alias| TERRA[OpenAI Terra]
    C -->|fresh-context verification| VERIFY[OpenAI Sol verifier]
    G --> OAI[OpenAI / Codex OAuth]

The launcher is intentionally not a proxy and stores no OAuth credentials. Bring an Anthropic-compatible gateway such as CLIProxyAPI, then point remora at it. See the architecture rationale and gateway runbook.

Model map

The defaults mirror the working GPT-5.6 split that motivated this repository. Every name is configurable because gateways expose different model catalogs.

Claude Code's built-in aliases remain useful escape hatches: Opus defaults to Sol, Sonnet to Terra, and Haiku to Luna.

Claude Code validates subagent models against availableModels. If a user's normal settings list only Claude aliases, a raw gateway id such as gpt-5.6-luna is otherwise rejected and silently inherits the Sol main model. remora prevents that fallback by passing a child-only additional settings document that allowlists every configured gateway model. It does not write or replace the user's settings file, and managed organization policy still retains its normal higher precedence.

Context safety

OpenAI's public GPT-5.6 API advertises a 1.05M context window, but CLIProxyAPI's Codex OAuth catalog currently reports 372K for Sol, Terra, and Luna. remora treats the gateway catalog as the operational limit instead of assuming that the public API limit applies to a subscription/OAuth route.

Claude Code assigns unknown custom model ids a 200K context window. remora therefore defaults to stock mode: a truthful 200K client window with Claude's native compact pipeline left untouched. Native Claude may compact before the displayed limit because it separately reserves output tokens and precomputes summaries; remora does not report a made-up exact trigger for this mode.

Users who explicitly install Calico Claude can select calico mode. remora then reads the gateway catalog, supplies an exact model/window map to Calico's validated context adapter, displays 95% as usable context, and compacts at 90% of the raw window. A 372K provider window therefore appears as 353.4K usable context and compacts near 334.8K. Malformed maps, unknown ids, and missing Calico patches fail closed.

[context]
mode = "stock"
stock_window = 200000
discovery = true
fallback_window = 372000
effective_window_percent = 95
auto_compact_percent = 90

To opt in after installing a Calico release that contains custom-context-window, change only mode = "calico" and run remora doctor --online before starting work.

Who it is for

remora is for developers who prefer Claude Code's interaction model but want their coding work executed by a tiered GPT-5.6 fleet. It is especially useful when a single frontier model for every subtask is unnecessarily expensive.

remora is not a hosted gateway, an OAuth account manager, an official OpenAI or Anthropic integration, or a zero-trust sandbox. It is a poor fit where organizational policy prohibits model gateways or where only vendor-supported routing is acceptable.

Trust and security

Installation is approval-gated, release artifacts are verifiable, and runtime overrides are confined to the remora child process.

The gateway and upstream model still receive prompts and any source Claude Code sends them. Review the full security policy and gateway trust boundary before using remora on sensitive repositories.

Requirements

Install

Approval-gated one-prompt install

Give Claude Code this prompt. The immutable tag is intentional:

Read and follow this installation runbook:
https://raw.githubusercontent.com/Nanako0129/remora-cc/v0.1.5/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 will not ask for a bearer token or OAuth file. It stops at an approval gate, downloads the matching release, verifies its SHA-256 and GitHub attestation, installs atomically, and checks that ~/.claude did not change.

Manual source install

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

The installer copies remora under the XDG data directory, creates a configuration only when none exists, and links one new executable:

~/.local/bin/remora
~/.local/share/remora-cc/
~/.config/remora-cc/config.toml

It does not add the bin directory to PATH. If needed, add this to your shell profile yourself:

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

Configure

Need a gateway first? Follow the minimal CLIProxyAPI Docker Compose deployment, complete Codex OAuth in its GUI, then return here with the proxy API key.

Edit the generated configuration:

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

For a quick local test, export the gateway token in the current terminal:

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

For daily macOS use, retrieve the token from Keychain instead of storing it in TOML:

[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 array directly without a shell and reads the token from stdout.

Use

Run remora anywhere you would run Claude Code:

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

All unrecognized arguments pass through to claude. Explicit Claude flags win: supplying your own --model or --agents prevents remora from injecting that specific default.

Useful diagnostics:

Verify isolation

Before and after installation, these checks should produce identical hashes because remora never writes them:

find ~/.claude -type f -maxdepth 3 -print0 \
  | sort -z \
  | xargs -0 shasum -a 256 > /tmp/claude-files.sha256

remora dry-run
claude --version

The strongest behavioral check is simply to run both commands. remora agents should show the OpenAI map; plain claude should retain its original model and authentication.

Questions and answers

Operational notes

⚠️ Do not disable gateway cooldown globally as the first fix. A real upstream rate limit can become a retry storm. The safer order is lower concurrency, bounded retry, multiple credentials, and correct classification of transient versus quota 429 responses.

The experimental active-turn bridge is the narrow exception: v1 deliberately requires one credential with cooling disabled and refuses to advertise support for multi-account or Home routing. See the gateway runbook.

Operational security

remora never prints the gateway token, includes no telemetry, and invokes credential-store commands as an argument array without shell expansion. The proxy still receives source code and prompts, and the selected OpenAI account still processes them. Read SECURITY.md before using a remote gateway.

Uninstall

./uninstall.sh

The default keeps the configuration for reinstalling. Remove it too with:

./uninstall.sh --purge

Neither path touches ~/.claude.

Prior art

remora packages a narrow technique rather than inventing multi-agent routing. pilotfish established the role-based orchestration pattern; use it when you want to study or customize the global-policy version of this design. Anthropic documents dynamic session agents and custom LLM gateways; CLIProxyAPI supplies the protocol bridge. remora's contribution is one auditable, installable launcher for an existing gateway, with no mutation of native Claude state.

License

MIT