v3.1.0-rc.1
Juggling multiple AI accounts, solved
Orrery pools your Claude Code, Codex, and Gemini CLI accounts and switches between them with one command — no logging out, no re-auth, and your conversation picks up right where you left off.
Orrery pools your Claude Code, Codex, and Gemini CLI accounts and switches between them with one command — no logging out, no re-auth, and your conversation picks up right where you left off.
If you installed Orrery via APT (apt install orrery), running orrery update may show already the newest version (2.3.x). The APT repo is no longer maintained, and the old update path didn't run apt update first. Run the native installer once to transition:
This removes the APT-managed binary, installs the new orrery-bin, and switches future orrery update calls to the native install flow. Optionally clean up the stale APT source:
All your logins in one place. Add a Claude, Codex, or Gemini account once — Orrery keeps the credential in a shared pool, ready to switch to any time.
orrery use --claude work swaps the active account for a tool. No logout, no password, no browser auth flow — just an instant switch.
Switch accounts mid-task and claude --resume still works. Conversation history is shared across switches by default.
Launch via orrery run claude and use /orrery:phantom inside Claude to swap account or sandbox without losing the conversation.
Need a fully separate config per client or project? An optional sandbox isolates memory, sessions, and env vars on top of accounts.
Switching only affects the current shell. Other terminal windows stay on their own account, unaffected — and there's no background process.
Built in Swift — native binary, instant startup. Shell integration is a tiny eval'd function. Supports bash and zsh.
Add each AI tool account once. Orrery keeps the credentials in a shared pool — switching is instant, with no logout and no re-auth.
Start with accounts — that's all most people need. Reach for a sandbox only when a context needs fully isolated config.
Your identity for a tool — the credential Orrery logs in with. Accounts live in a shared pool: add once, switch any time with orrery use. This is the layer you'll touch every day.
An optional isolation layer: separate memory, sessions, and env vars. Most users never need one — reach for a sandbox when a client or project needs its own config space. Enter with orrery enter, leave with orrery exit.
Represents continuity: conversation history and project context. Shared across account switches by default — claude --resume just works.
Traditional tooling isolates dependencies (virtualenv) or runtime versions (nvm).
Orrery extends that idea to AI accounts — and, when you need it, full config isolation.
Run orrery setup once. It generates ~/.orrery/activate.sh and adds it to your rc file. Then source ~/.orrery/activate.sh to activate in the current shell.
activate.sh also checks for new Orrery releases in the background (once per day) and shows a notice at your next shell open.
Run orrery add --claude (or --codex / --gemini) and log in once. The account joins a shared pool — repeat for every account you use.
orrery use --claude personal makes that account active for Claude. No logout, no re-auth — and your conversation history stays intact across switches.
After switching accounts, claude --resume picks up your last session. Identity changes, continuity doesn't — the best of both worlds.
When a client or project needs fully isolated config, run orrery sandbox create client-a, then orrery enter client-a / orrery exit to move in and out. Skip this entirely if you only switch accounts.
Launch Claude with orrery run claude and a supervisor stays alongside it.
From inside that Claude, the /orrery:phantom slash command swaps the active
account or sandbox without restarting the conversation —
Claude exits, the supervisor relaunches it with the new context and --resume,
and you continue where you left off.
Phantom mode is the default for orrery run claude.
To opt out (single-shot, no supervisor): orrery run --non-phantom claude.
The slash command is installed automatically by orrery mcp setup.
origin baseline
origin is your normal setup: the accounts and per-tool config you'd use
without Orrery at all. On first orrery setup, your existing tool configs
(~/.claude/, ~/.codex/, ~/.gemini/) are moved into
~/.orrery/origin/ and the original paths become symlinks — your data is
untouched, it just lives where Orrery can manage and sync it. Switching accounts with
orrery use works right here at origin; you only need a sandbox when a
context calls for fully isolated config.
orrery exit returns to origin from any sandbox. Orrery-specific variables
like CLAUDE_CONFIG_DIR get unset, so each tool falls back to its native
path — which now resolves to the managed config via the symlink. The experience feels
like "exit Orrery", but you're still on Orrery-managed storage. orrery enter
origin is rejected and points you at exit: origin is the absence
of a sandbox, not a sandbox you enter.
Unlike regular sandboxes, origin cannot be deleted or renamed and
uses the system's native config paths. It does support memory and session settings —
use orrery sandbox memory isolate / share / storage to
control where its project memory lives, and choose per-tool session sharing during
orrery setup. Run orrery sandbox info origin to see full state.
Reverting the takeover. To take a tool fully out of Orrery (back to its pre-setup state), uninstall — it restores tools to their original locations and removes the shell integration:
Your company uses a Claude Team plan, and you have a personal Pro subscription. Add both to the pool, then flip between them with one command — no logout.
Mid-conversation with Claude on your work account? Switch to personal, do something, then switch back — your session is still there.
Freelancers and consultants juggling different clients — each needs its own credentials, settings, and memory. Give each client a sandbox for full isolation.
Orrery integrates with Claude Code, Codex CLI, and Gemini CLI via MCP. Delegate tasks across accounts, share memory between tools, and manage sessions — all from one place.
Run this in your project directory. Orrery registers itself as an MCP server and installs slash commands.
After setup, use these directly in Claude Code:
/orrery:delegate
Delegate a task to another account
/orrery:sessions
List sessions and resume by index
/orrery:phantom
Switch env mid-conversation — Claude relaunches with --resume
Claude understands your environments through MCP tools. You can say things like: