clausona 0.0.0-stage → 0.14.0-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 larcane97
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,542 @@
-# Temporary Holding Version
+# clausona
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Switch between Claude Code and OpenAI Codex CLI accounts without logging out while keeping the same conversation. Each account stays signed in separately and shares a single setup. Dynamic routing optimizes usage across your accounts by starting each run on one with room, and clausona shows which skills, MCP servers and hooks each account loads. Under the hood, it's just a shell hook and symlinks, with no daemon or proxy.**
+
+<p align="center">
+  <a href="https://github.com/hesreallyhim/awesome-claude-code"><img src="https://img.shields.io/badge/Mentioned%20in-Awesome%20Claude%20Code-fc60a8?style=for-the-badge&logo=awesomelists&logoColor=white" alt="Mentioned in Awesome Claude Code" /></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/larcane97/clausona/releases/latest"><img src="https://img.shields.io/github/v/release/larcane97/clausona?include_prereleases&label=release" alt="Latest release" /></a>
+  <a href="https://github.com/larcane97/clausona/actions/workflows/ci.yml"><img src="https://github.com/larcane97/clausona/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue" alt="Platforms: macOS, Linux, Windows" />
+  <a href="https://github.com/larcane97/clausona/blob/v0.14.0-beta/LICENSE"><img src="https://img.shields.io/github/license/larcane97/clausona" alt="MIT license" /></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/larcane97/clausona/v0.14.0-beta/assets/demo.gif" alt="clausona listing Claude Code and Codex accounts with their plan quota, switching to the work account so that plain claude starts signed in as it, switching back, and opening the dashboard" width="800" />
+</p>
+
+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 each account's weekly plan limit remains side by side, along with the remaining 5-hour limit on plans that have one.
+
+Step-by-step guides, including how to do it by hand:
+[multiple Claude Code accounts](https://larcane97.github.io/clausona/guides/multiple-claude-code-accounts/),
+[multiple Codex CLI accounts](https://larcane97.github.io/clausona/guides/multiple-codex-cli-accounts/),
+and [the same in Korean](https://larcane97.github.io/clausona/ko/). Another guide covers
+[the skills, MCP servers and hooks each account loads](https://larcane97.github.io/clausona/guides/claude-code-skills-mcp-hooks/).
+
+## 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.
+
+```bash
+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](#do-my-mcp-servers-plugins-and-settings-carry-over-when-i-switch).
+- **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** — weekly limit usage for every account, and the 5-hour session limit on plans that have one, 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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/routing.md))
+- **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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/extensions.md))
+- **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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/usecases/superset-fleet.md), [herdr](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/usecases/herdr-fleet.md), [Orca](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/usecases/orca-fleet.md) or plain [tmux](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/usecases/tmux-fleet.md), 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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/how-it-works.md#the-launch-cache)).
+- **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](https://docs.anthropic.com/en/docs/claude-code)
+- [OpenAI Codex CLI](https://github.com/openai/codex)
+
+**Platforms:** macOS/Linux (zsh or bash) and Windows (PowerShell 5.1+)
+
+macOS/Linux:
+
+```bash
+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:
+
+```powershell
+irm https://github.com/larcane97/clausona/releases/latest/download/install.ps1 | iex
+```
+
+With npm, on any of these platforms:
+
+```bash
+npm install -g clausona
+```
+
+npm does not touch your shell profile, so add the shell hook yourself, then open a new shell. The
+hook is what makes a plain `claude` or `codex` start on the profile you switched to, and it defines
+`csn`. On zsh or bash, add this line to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+eval "$(clausona shell-init)"
+```
+
+On PowerShell, add this line to the profile file that `$PROFILE.CurrentUserAllHosts` names:
+
+```powershell
+Invoke-Expression (& clausona shell-init | Out-String)
+```
+
+To remove a copy installed with npm, run `clausona uninstall` first, then `npm uninstall -g clausona`.
+
+**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). Other
+commands you run in a terminal, such as `clausona list`, ask after their output:
+`Update now? (Y/n)`. Any key but `y` or Enter, or no answer within ten seconds, and they leave it
+for a week, as they do after a no on the dashboard or to `clausona update`. They learn about a
+release from a check that runs in the background at most once a day, so no command waits for
+GitHub; a yes asks GitHub again first, so it installs the latest release. However you update,
+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. For a copy installed with npm,
+`clausona update`, the dashboard and the question after commands say to run
+`npm install -g clausona@latest` instead. Any other copy 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
+
+```bash
+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](#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              none       12% 5d
+```
+
+`5H` is the rolling session window, `7D` the weekly one, each followed by how long
+until it resets. A plan without a 5-hour limit, such as a verified Claude Ultra plan or some
+Codex plans, shows `none` under `5H`, and when no account has a 5-hour limit the column is left
+out. 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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/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:
+
+```bash
+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
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/larcane97/clausona/v0.14.0-beta/assets/routing.gif" alt="clausona route explain main listing three Claude Code accounts with their 5-hour and weekly usage, personal over 80% and work picked next; clausona run --route main saying it took claude:work and opening Claude Code, whose /status shows the work account; the same command again taking claude:team, the next in turn" width="800" />
+</p>
+
+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:
+
+```bash
+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:
+
+```bash
+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):
+
+```bash
+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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/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.
+
+```bash
+# 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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/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.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/larcane97/clausona/v0.14.0-beta/assets/extensions.gif" alt="The dashboard's Extensions screen listing the skills Claude Code loads in ~/app, grouped by project, Global, Cloud and plugins; sentry-cli, unused for four months, turned off in this project after a dialog that asks first, then put back with u; then the MCP servers and which account starts each one" width="800" />
+</p>
+
+```bash
+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:
+
+```bash
+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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/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](#api-profiles)                  |
+| `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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/routing.md) picks |
+| `clausona route add\|set\|rename\|remove\|edit\|list\|explain\|pick …` | Manage [routes](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/routing.md) |
+| `clausona route dir\|default …`                                     | Pick a route by directory, or by default, for a plain `clausona run claude` ([dir rules](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/routing.md#dir-rules-and-defaults)) |
+| `clausona route budget [<profile>] …`                               | List or set API profiles' spend limits, so they can join routes ([budgets](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/routing.md#api-profiles-in-routes)) |
+| `clausona route`                                                    | Open the [Routes screen](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/routing.md#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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/api-profiles.md#the-model) |
+| `clausona config <profile> --set KEY=VALUE \| --unset KEY \| --edit` | Set [advanced settings](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/api-profiles.md#advanced-settings) per profile |
+| `clausona config <profile> --base-url <url> \| --auth <scheme> \| --label <name>` | [Change an API profile's endpoint](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/api-profiles.md#changing-the-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 star`                                                     | Star clausona on GitHub (through `gh`, or in your browser) |
+| `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
+│                            that a plugin install in any profile reaches
+├── 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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/how-it-works.md#what-a-claude-profile-shares)). 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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/how-it-works.md#what-a-codex-profile-shares)).
+
+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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/how-it-works.md)**.
+
+## How clausona compares
+
+|  | clausona | [claude-swap](https://github.com/realiti4/claude-swap) | [codex-auth](https://github.com/Loongphy/codex-auth) | [aisw](https://github.com/burakdede/aisw) | [claude-code-profiles](https://github.com/quinnjr/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.
+
+See the [guides site](https://larcane97.github.io/clausona/guides/claude-code-account-switchers/) for a fuller comparison covering ccam, ClaudeCodeMultiAccounts, ccswitch and Orca.
+
+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 own `.claude.json`, which
+clausona does not share. 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 7-day usage, and its 5-hour usage on
+plans that have one, with 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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/routing.md).
+
+### 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, Orca or tmux 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, Orca terminal or tmux window. To have one
+session split a job across several such agents, watch them and clean up after them, install the
+plugin for your tool:
+
+```bash
+claude plugin marketplace add larcane97/clausona
+claude plugin install superset-fleet@clausona   # or herdr-fleet, orca-fleet, tmux-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](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/usecases/superset-fleet.md), [herdr](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/usecases/herdr-fleet.md),
+[Orca](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/usecases/orca-fleet.md) and [tmux](https://github.com/larcane97/clausona/blob/v0.14.0-beta/docs/usecases/tmux-fleet.md) 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](#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.
+
+## Listed in
+
+[Awesome Claude Code](https://github.com/hesreallyhim/awesome-claude-code), [Awesome AI Plugins](https://github.com/hashgraph-online/awesome-ai-plugins), [Awesome CLI Coding Agents](https://github.com/bradAGI/awesome-cli-coding-agents)
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/larcane97/clausona](https://github.com/larcane97/clausona).
+
+If clausona saves you a few logins a day, a ⭐ on the repo helps other people find it.
+
+## License
+
+MIT