Clausona

What is Clausona about?

Clausona is a profile manager for Claude Code and OpenAI Codex command‑line interfaces. It creates separate config directories for each account, but symlinks shared resources (plugins, settings, skills, MCP servers) so the environment is consistent across profiles. It also displays plan‑quota usage and can auto‑select an account that still has headroom.

How to use Clausona?

1. Install (requires Node.js ≥ 20):
   • macOS/Linux: curl -fsSL https://github.com/larcane97/clausona/releases/latest/download/install.sh | bash
   • Windows PowerShell: irm https://github.com/larcane97/clausona/releases/latest/download/install.ps1 | iex
2. Initialize: clausona init discovers existing Claude Code and Codex sign‑ins and registers them as profiles.
3. Switch profiles: clausona use work or clausona use claude:work.
4. Run a tool with a specific profile: clausona run claude:personal -- <args>.
5. List profiles & quota: clausona list (optional --json).
6. Dashboard: simply run clausona (alias csn) to open the interactive TUI.
7. Optional actions: add API‑backed profiles, merge session histories, create routing rules, manage extensions, update with clausona update, uninstall with clausona uninstall.

Key Features

• One‑command profile switching (clausona use <name>).
• Shared plugins, skills, MCP servers, and settings.json across all profiles via symlinks.
• Optional shared conversation history (--merge-sessions).
• Live plan‑quota view for every Claude Code and Codex account.
• Automatic routing to the account with remaining quota (clausona run --route …).
• Ability to run two accounts simultaneously (clausona run claude:personal).
• API profiles for Anthropic, OpenRouter, or self‑hosted endpoints.
• Pure CLI passthrough – no daemon, no proxy; the original binaries are executed unchanged.
• Lightweight implementation: a shell hook and a few symlinks.
• Local usage tracking (cost & token counts) for Claude Code.
• Interactive TUI dashboard for profile, route, and extension management.

Use Cases

• Separating work and personal AI accounts on a single workstation without reinstalling plugins.
• Automated CI/CD scripts that pick the account with remaining quota for long‑running test suites.
• Multi‑agent fleets where each agent runs on a different profile (Superset, herdr, Orca).
• Developers using API‑backed endpoints (OpenRouter, custom Anthropic servers) alongside subscription accounts.
• Team environments where several engineers share the same skill set but need isolated sign‑ins.
• Windows users who need junction‑based linking for shared configuration.

FAQ

• How do I add a second Claude Code account? Sign in the first account, run clausona init, then clausona add claude:work to create a new profile and log in.

• Can I switch Codex CLI accounts without logging out? Yes. After adding a Codex profile (clausona add codex:work), use clausona use codex:work to change the active account.

• Do plugins and MCP servers carry over when I switch? Plugins, skills, and most settings are symlinked and shared. MCP servers stored in .claude.json are per‑profile; add them to each profile as needed.

• Is conversation history shared? By default it stays per account. Enable sharing with clausona config <profile> --merge-sessions (or the --merge-sessions flag on add).

• How does quota routing work? Define a route (clausona route add main). The tool picks the next account under 80 % usage, or the one with the most headroom, and can wait for a reset with --wait.

• Can I run two accounts at the same time? Yes. Use clausona use to set the global active profile, and clausona run claude:personal to launch a one‑off session on another profile.

• Do I need a daemon or background service? No. Clausona only adds a shell hook that sets environment variables for each launch.

• What about Windows link handling? Clausona uses junctions; enable Developer Mode to allow symbolic links, otherwise files are copied.

clausona

Switch between multiple Claude Code and OpenAI Codex CLI accounts on one machine. They sign in separately and share one setup. clausona can also pick the account with quota left for each run, and show the skills, MCP servers and hooks every account loads.

clausona is a profile manager for the Claude Code and OpenAI Codex CLIs. Every account gets a config directory for its sign-in. Skills, hooks, plugins and settings are shared across them, so csn use work is all it takes to move to another account.

Conversation history stays with the account unless you choose to share it. Once it's shared, a conversation started under one account can be resumed under another.

clausona also shows how much of your accounts' 5-hour and weekly plan limits is left, side by side.

Step-by-step guides, including how to do it by hand: multiple Claude Code accounts, multiple Codex CLI accounts, and the same in Korean.

Why

I've been using Claude Code with a personal and a work account, and I got tired of setting up plugins and permissions for both. So I made a simple tool for it.

If you have Claude Code or OpenAI Codex CLI accounts for personal use, work or different orgs, switching between them on one machine is tedious:

• Switching is manual. You log out and back in, or juggle CLAUDE_CONFIG_DIR (Claude) or CODEX_HOME (Codex) yourself.
• Settings don't carry over. A second account gets a separate config directory. Your plugins, permissions, settings and skills have to be set up from scratch, every time.

clausona fixes both. One command switches profiles, and your setup comes along.

csn use work             # switch to the work account
csn use codex:personal   # switch to your personal Codex account too

You don't sign in again, and you don't reinstall plugins.

csn is a shorthand alias for clausona, registered automatically on install.

Features

• One-command switching — clausona use <name> and you're on a different account
• Shared environment — plugins (and the MCP servers they bring), skills, and settings.json with its hooks and permissions (Claude), and config.toml (MCP servers included), skills, and hooks (Codex) are symlinked across profiles within each tool. Set up once, use everywhere. MCP servers added with claude mcp add stay per account — see the FAQ.
• Shared history, if you want — clausona config <profile> --merge-sessions shares conversation history with your primary directory, so claude --resume and claude --continue (and codex resume on macOS and Linux) find conversations from every account that shares it
• Plan quota at a glance — session and weekly limit usage for every account, read live from each tool's own usage endpoint (Claude and Codex)
• Routing — clausona run --route main starts on whichever account still has room, going by the same plan-quota readings. With a directory rule or a default route, a plain clausona run claude (or codex) picks the account on its own (docs)
• Extensions — the skills, MCP servers and hooks Claude Code and Codex load in a project, for every account, on the dashboard's Extensions screen or from clausona skills, clausona mcp and clausona hooks. Turn one off or delete it, behind a backup, and undo puts it back (docs)
• Two accounts at once — clausona run claude:personal starts one session under another profile without switching, so two terminals can run two accounts side by side
• Parallel agent fleets — plugins from this repo let one Claude Code or Codex session run parallel agents in Superset, herdr or Orca, each on its own account or API model, then check and clean up after them. Install only the one for the tool you use
• API profiles — a profile can point at an API endpoint instead of a subscription login: the Anthropic API, a gateway, or a model you serve yourself
• Pure CLI passthrough — no wrapping, no proxying, no background process. claude and codex run directly and unmodified. Compatible with oh-my-claudecode, Cline, codex plugins, and any other tool in your stack.
• Lightweight — a single shell hook and a few symlinks. No daemon, no server, and no startup overhead: claude and codex start from a small cached script, and clausona itself runs only when something changed — a profile switch, a plugin install — or for a profile it can't cache, such as an API profile (details).
• Usage tracking — per-profile cost and token usage, tracked locally (Claude Code only for now)
• Interactive dashboard — TUI for managing profiles and routes, viewing usage, and running health checks

Install

Requirements: Node.js >= 20, and at least one of:

• Claude Code CLI
• OpenAI Codex CLI

Platforms: macOS/Linux (zsh or bash) and Windows (PowerShell 5.1+)

macOS/Linux:

curl -fsSL https://github.com/larcane97/clausona/releases/latest/download/install.sh | bash

Piping to bash does not read your shell profile, so if Node comes from a version manager (nvm, fnm, asdf), activate it before running the command.

Windows PowerShell:

irm https://github.com/larcane97/clausona/releases/latest/download/install.ps1 | iex

Updating. When a newer release is out, the dashboard (csn) says so in its header and lists Update above Profiles; choose it and answer Y, and csn restarts on the new version. From a script or another shell, clausona update does the same (--yes skips the question). Either way the download is checked against the release's published SHA-256 before the installed copy is replaced. Only a copy the installer put in place updates itself; any other is pointed at the installer.

After upgrading, open a new shell — or re-run the hook in each shell that is already open: eval "$(clausona shell-init)" on zsh/bash, Invoke-Expression (& clausona shell-init | Out-String) on PowerShell. A shell keeps the hook it loaded when it started, and an older hook can apply less than the version you just installed: one from before API profiles sets only the config directory, with no endpoint and no key.

Quick Start

clausona init             # discover existing Claude Code and Codex accounts
clausona use work         # switch to a profile (bare name if unique)
clausona use claude:work  # switch claude account (use prefix when both tools have "work")
clausona add codex:work   # add a codex profile
clausona use codex:personal  # switch codex account
clausona list             # see all profiles with plan quota and weekly usage
clausona                  # open the interactive dashboard

clausona add claude:gw --api --base-url https://openrouter.ai/api   # a profile backed by an API endpoint

clausona starts from an account that is already signed in, Claude Code or Codex: clausona init registers the accounts it finds and refuses when there are none, and until it has run the other commands say "clausona is not initialized". On a machine where neither has been signed in, run claude login or codex login once first. API profiles are added next to a Claude Code account, so they need claude login once even if you will use only API profiles.

Plan quota

clausona list and the dashboard show how much of each account's plan limits are already spent, so you can pick a profile that still has headroom.

PROFILE             ACCOUNT                      5H         7D
claude:work         you@example.com              6% 23m     46% 13h
claude:personal     you@personal.com             0%         100% 4d
codex:work          you@example.com              —          12% 5d

5H is the rolling session window, 7D the weekly one, each followed by how long until it resets. The dashboard shows the same reading with a gauge and the precise reset time, plus the most-consumed per-model limit.

Readings come from each tool's own usage endpoint, authenticated with the credential that tool already stored for that profile. For subscription profiles clausona holds no token of its own. Results are cached for 5 minutes; --refresh forces a re-read and --no-quota skips the network entirely.

How lapsed tokens are renewed, and what a dash in the table means: docs/plan-quota.md.

Routing

You can let clausona choose the account. A route is a named group of accounts and a rule for picking one of them by plan quota:

clausona route add main                          # every Claude Code account, taking turns
clausona route explain main                      # who would be picked now, and why
clausona run --route main -- -p "run the tests"

The run says on stderr which account it got:

  ▸ claude:work  route main, next in turn, 34% of 7D used

By default an account at 80% or more of its 5-hour or weekly limit is used only when no other account in the route is under 80%. Then the one with the most left is picked, even at 99%. Only when every account is at 100%, or skipped because it is signed out or its quota could not be read, does clausona say when each one resets or why it was skipped, and exit with code 75 instead of starting a session. With --wait it waits for the soonest reset instead, up to 5 hours or the cap you give, and then runs. That suits scripts and cron:

clausona run --route main --wait=2h -- -p "run the nightly review"

When the tool's arguments name a model, as in -- --model opus, an account's limit on that model counts too, so an account whose Opus limit is used up is not picked for an Opus run.

A route is for Claude Code unless you say otherwise. --tool codex makes a Codex route, and --tool all makes one that takes the accounts of both tools. clausona route on its own opens the Routes screen, where you can look through your routes and create or edit one in a form. It is also on the dashboard, under Profiles.

You can also skip --route and let the directory decide:

clausona route dir ~/work work                   # in ~/work and below, clausona run claude takes route work
clausona route default main                      # everywhere else, it takes route main
clausona route explain                           # what a run here would take, and why

With neither, clausona run claude runs the active profile, as it always has.

An API profile can join a route too, once it has a spend limit. It is billed per use, so a route takes it only by its exact name, never through *. Its usage is its spend against the limit, read from the provider (OpenRouter, or a LiteLLM proxy):

clausona route budget claude:gw --usd 20 --per month   # or use the limit set on the key itself
clausona route set main --add claude:gw

A budget stops new routed sessions, not one already running; the limit on the provider key is what blocks requests.

Patterns like *@example.com, fallbacks, the strategies, waiting in scripts, budgets, and the JSON that scripts and agents read: docs/routing.md.

API profiles

A profile can be backed by an API endpoint instead of a subscription login — the Anthropic API, a gateway such as OpenRouter, or a model you serve yourself. It sits beside your subscription profiles in clausona list, switches the same way, and shares the same plugins and settings. In this version API profiles are for Claude Code only.

# a hosted gateway
clausona add claude:gw --api \
  --base-url https://openrouter.ai/api \
  --model z-ai/glm-5.3

# a model you serve yourself
clausona add claude:local --api \
  --base-url http://localhost:8000 \
  --model glm-5.3 \
  --set CLAUDE_CODE_MAX_CONTEXT_TOKENS=262144 \
  --set API_TIMEOUT_MS=600000

clausona use claude:gw

The key is never passed as an argument. By default it is read from a prompt that does not echo it, or from stdin, and stored in the macOS Keychain or ~/.clausona/secrets.json; with --key-from env:NAME or --key-from command:"op read …" clausona records only where to find it and reads it at each launch.

An api-key profile's first claude session asks about the key — answer Yes. Claude Code shows "Detected a custom API key in your environment" with the cursor on "No (recommended)", so pressing Enter answers No, and that profile then ignores its key. /config → "Use custom API key" changes the answer later. A bearer profile is not asked.

The model, where the key lives, per-profile settings, changing the endpoint, and what clausona hides or clears from the environment: docs/api-profiles.md.

Extensions

csn skills, csn mcp and csn hooks list the skills, MCP servers and hooks that Claude Code and Codex load, for every account, seen from one project. The dashboard's Extensions screen shows the same. Secret values are never shown.

csn skills ls --scope project                 # the skills this project defines
csn skills ls --scope unused --tool claude    # Claude skills not used in 90 days

ls lists one scope, by default what loads in this project; show <name> tells everything about one item, such as which accounts have an MCP server and whether it is on here. Both only read files.

off, on, rm and undo change things, each after a confirm step and behind a backup:

csn skills rm old-one --dry-run               # what deleting it would change
csn mcp off github --account work             # off in this project, for one account
csn skills undo                               # put back the last skills change

The screen does the same with keys. Add --json for scripts and coding agents.

Scopes, tags, every option, what each change writes, the JSON fields and recipes for agents: docs/extensions.md.

Commands

<profile> accepts either a bare name (e.g. work) when it is unique across all tools, or a tool:name prefix (e.g. claude:work, codex:work) when disambiguation is needed.

Command	Description
clausona	Interactive TUI dashboard
clausona init	Discover and register Claude Code and Codex accounts
clausona add <profile> [--from <path>] [--merge-sessions]	Add a profile manually
clausona add <profile> --api --base-url <url> [...]	Add an API profile
clausona remove <profile>	Remove a profile. Its config directory and history stay, so delete that directory before adding the name again
clausona use [profile]	Switch active profile
clausona run <profile> [-- args...]	Run the tool's CLI with a specific profile (a leading -- is dropped)
clausona run --route <name> [-- args...]	Run on the account a route picks
clausona route add|set|rename|remove|edit|list|explain|pick …	Manage routes
clausona route dir|default …	Pick a route by directory, or by default, for a plain clausona run claude (dir rules)
clausona route budget [<profile>] …	List or set API profiles' spend limits, so they can join routes (budgets)
clausona route	Open the Routes screen (in a terminal)
clausona list [--json] [--refresh] [--no-quota] [--no-renew]	List all profiles with plan quota and usage
clausona usage [profile] [--period=today|week|month|all]	View cost and token usage
clausona current [--json]	Show active profile
clausona config <profile> --merge-sessions | --separate-sessions	Configure session mode
clausona config <profile> --model <id>	Change a profile's model
clausona config <profile> --set KEY=VALUE | --unset KEY | --edit	Set advanced settings per profile
clausona config <profile> --base-url <url> | --auth <scheme> | --label <name>	Change an API profile's endpoint
clausona config <profile> --key | --key-from <source>	Change an API profile's key, or where it is read from
clausona config <profile> --show [--json]	Print a profile's settings (--json adds the catalog)
clausona doctor [--json]	Check profile health
clausona skills ls|show|off|on|rm	Skills each project loads; turn them off or delete them
clausona mcp ls|show|off|on|rm	MCP servers each project loads; turn them off or delete them
clausona hooks ls|show|off|on|rm	Hooks each project runs; turn them off or delete them
clausona repair <profile>	Fix broken shared links
clausona login <profile>	Re-authenticate a profile
clausona update [--yes]	Update to the latest release (asks first; --yes skips)
clausona uninstall	Uninstall clausona completely

How it works

clausona use only records which profile is active. The shell hook the installer adds wraps claude and codex: on each launch it points the tool at the active profile's config directory (CLAUDE_CONFIG_DIR or CODEX_HOME) for that one run, then runs the real, unmodified binary. Your interactive shell is left as it was.

clausona use work
↓
claude             ← wrapper applies the work profile's env, then runs claude
↓
_track-usage       ← on exit, records any new cost/token usage

clausona use codex:personal
↓
codex              ← wrapper applies the personal profile's env, then runs codex

Each profile is its own config directory. Its sign-in and session history stay in it; the rest links back to your primary directory, so what you set up once is there for every account:

~/.claude-work/            (new claude profile)
├── .claude.json           ← own account metadata and `claude mcp add` servers (NOT shared)
├── .credentials.json      ← own OAuth tokens outside macOS, and on macOS when the
│                            Keychain refuses them (NOT shared)
├── projects/              ← own session history (NOT shared by default)
├── plugins/               ← own directory: each entry links to ~/.claude/plugins/, except
│                            the two JSON files that hold paths, kept as per-profile copies
├── settings.json →  ~/.claude/settings.json  (symlink to primary)
└── ...

What Claude Code keeps for one account or org, such as its policy limits, remote managed settings, MCP sign-in cache and background daemon, stays with each profile too (the full list). So do the daemon's scheduled tasks and Remote Control folders: those set up on the primary stay with the primary, and a profile sets its own.

Codex profiles share only their configuration: config.toml, hooks.json, AGENTS.md, rules/, skills/, plugins/, prompts/ and a few more. Everything else Codex keeps in its home, such as its app-server daemon and its memories, stays with each account (the full list).

clausona has no telemetry and no server of its own. Its network calls are each profile's plan-quota lookup — and a lapsed token's renewal — against that profile's own provider, which clausona list --no-quota skips, and the dashboard's check of GitHub for a newer clausona release.

Session separation, Windows links, how credentials are kept apart, what doctor and repair look at, and where clausona stores its data: docs/how-it-works.md.

How clausona compares

	clausona	claude-swap	codex-auth	aisw	claude-code-profiles
Claude Code	✓	✓	—	✓	✓
Codex CLI	✓	—	✓	✓	—
How it switches	a config directory per account	swaps the login inside one ~/.claude	copies auth.json into ~/.codex	writes each tool's own credential store, plus a config-dir shell hook	a config directory per profile, through a claude() wrapper
History kept per account, plugins and settings shared	✓	partly: cswap run sessions share settings and skills, not plugins	— (one ~/.codex for all accounts)	—	skills only
Plan quota for every account	✓	✓	✓	—	—

Compared from each project's README and docs in September 2026; — means we found no mention of it. Corrections are welcome.

clausona is built around one idea: keep accounts apart where they have to be — sign-in and history — and shared everywhere else, for Claude Code and Codex alike.

FAQ

How do I use two Claude Code accounts on one machine?

Sign in to the first account as usual (claude login) and run clausona init to register it. Then clausona add claude:work creates a second profile and opens Claude Code's own sign-in for it. From then on, csn use work and csn use personal choose which account claude starts with. Each account keeps its own sign-in and history; plugins and settings are shared.

How do I switch Codex CLI accounts without logging out?

clausona add codex:work creates a second Codex home (~/.codex-work) with its own auth.json, signed in through Codex's own login. csn use codex:work makes codex start with that account, and csn use codex:personal switches back. config.toml, skills and plugins stay shared with your main ~/.codex, and codex resume shows only the active account's sessions.

Do my MCP servers, plugins and settings carry over when I switch?

Plugins — and the MCP servers they bring — settings.json, skills, commands and agents do: they are linked to your primary config directory, so what you install under one account is there under every account of that tool. MCP servers added with claude mcp add are the exception: Claude Code keeps those in each config directory's .claude.json, next to that account's sign-in, and clausona does not share that file. Add them to each profile, or put them in a project's .mcp.json. Sign-ins are never shared, and session history stays with each account unless you merge sessions (below).

Can I continue a conversation under another account?

Yes, once the accounts share history: clausona config claude:work --merge-sessions (or --merge-sessions on clausona add and clausona init). For Claude Code that copies the account's existing conversations into the primary's history first, so none are lost. Then claude --resume lists conversations from every account that shares history, and claude --continue picks up the latest one in the current folder, whichever account started it. For Codex on macOS and Linux, codex resume and codex resume --last find threads from every such account, goals included; the account's earlier Codex conversations are set aside in a backup rather than copied, and come back with --separate-sessions. On Windows Codex's thread store stays with each account, so a thread from another account is resumed by its id. --separate-sessions turns sharing off.

Can I see Claude and Codex plan limits for all my accounts at once?

Yes. clausona list and the dashboard show every account's 5-hour and 7-day usage and the time until each resets, read from each tool's own usage endpoint with the credential that tool already stored. Accounts you have not used today still report, because clausona renews a lapsed access token when it needs to.

Can clausona pick the account with quota left?

Yes. clausona route add main makes a route of every Claude Code account (--tool codex for Codex, --tool all for both), and clausona run --route main starts on the next one in turn that is under 80% of its limits. With --strategy headroom it takes the account with the most room instead. After clausona route default main, a plain clausona run claude does the same. See Routing.

Can I run two accounts at the same time?

Yes. csn use sets the account new claude and codex launches start with, and clausona run claude:personal starts one session under another profile without changing that. So one terminal can run your work account while another runs clausona run claude:personal.

Can each Superset, herdr or Orca agent run on a different account?

Yes. Start each one with clausona run <profile> -- <args>: as a custom agent's command in Superset → Settings → Agents, or in any herdr pane or Orca terminal. To have one session split a job across several such agents, watch them and clean up after them, install the plugin for your tool:

claude plugin marketplace add larcane97/clausona
claude plugin install superset-fleet@clausona   # or herdr-fleet, orca-fleet

In Codex, add the shared rules too: codex plugin marketplace add larcane97/clausona, then codex plugin add fleet-core@clausona and the runner's plugin. See the Superset, herdr and Orca pages. If you installed clausona@clausona before, run claude plugin install superset-fleet@clausona once after updating it.

How is this different from setting CLAUDE_CONFIG_DIR myself?

A shell alias per account gives you separate sign-ins, but each directory starts empty: plugins, settings and skills have to be installed again in every one, and they drift apart afterwards. clausona links them to one primary directory, shows every account's plan quota in one place, and clausona doctor and repair spot and link the directories a newer Claude Code version adds.

Does clausona wrap or proxy claude and codex?

No. The shell hook sets the profile's environment for one run and executes the real claude or codex binary, unmodified. There is no daemon and no proxy. If you export CLAUDE_CONFIG_DIR or CODEX_HOME yourself, clausona steps aside for that shell.

Can I use an API key, OpenRouter, or a self-hosted model as a profile?

Yes, for Claude Code: clausona add claude:gw --api --base-url <url> creates a profile backed by any endpoint that speaks the Anthropic Messages format. It switches like any other profile. See API profiles. Codex API profiles are not supported yet.

Does it work on Windows?

Yes, with PowerShell 5.1 or later. Shared directories use junctions. Turn on Developer Mode so shared files can be symbolic links: without it, files the tools save whole (settings.json, CLAUDE.md, keybindings.json, and Codex's config.toml and hooks.json) stay a copy per account, and clausona doctor says so. Other files fall back to hard links.

Contributing

Issues and pull requests are welcome at github.com/larcane97/clausona.

If clausona saves you a few logins a day, a ⭐ on the repo helps other people find it.

License

MIT