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
• Operational notes
• Operational security
• Uninstall
• Prior art

What it changes

Remora launches a child claude process with a session-only --agents JSON document 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.

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| 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.

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.

At launch, Remora reads the gateway's Codex-compatible model catalog and takes the smallest window among every configured main and agent model. It then mirrors Codex CLI's policy: 95% is effective context and automatic compaction starts at 90% of the raw provider window. With the current 372K catalog this means 353.4K effective context and a 334.8K compact trigger. Remora passes the raw window and compact percentage to its Claude Code child; a failed or incomplete lookup falls back conservatively and never changes CLIProxyAPI or native Claude.

[context]
discovery = true
fallback_window = 372000
effective_window_percent = 95
auto_compact_percent = 90

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.2/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.2 --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.

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.

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