Agent Accounts

Coding agents keep their sign-in on disk, in a folder under your home directory: ~/.claude, ~/.codex, ~/.kimi-code. If you have more than one login for an agent — a personal plan and a work plan, or two Claude accounts to spread the load — each one lives in its own folder. vord finds those folders, shows you what’s there, and points every session at the right one. Muse is the exception: vord currently tracks exactly one Muse account.

That’s the whole mechanism. vord never stores or forwards a token, never routes inference through one, and does not sign you in to a provider. It sets one environment variable per session — CLAUDE_CONFIG_DIR, CODEX_HOME or KIMI_CODE_HOME — and the agent does the rest exactly as it would in a plain terminal. For locally reported usage and quota readings, see Usage & quota.

Where accounts live

Each agent has a default folder and any number of named folders next to it:

Agent	Default folder	Named account `work`
Claude	`~/.claude`	`~/.claude-work`
Codex	`~/.codex`	`~/.codex-work`
Kimi	`~/.kimi-code`	`~/.kimi-code-work`
Muse	`~/.config/muse`	— (exactly one account)

The suffix after the dash is the account’s slot — its stable name in vord. Folders whose name after the prefix contains a dot or other disallowed characters (for example ~/.claude-work.lock) are not treated as accounts. The email is only for display: it’s read out of what the agent itself stored (Claude and Codex record one; kimi doesn’t store an email locally, so it shows as Kimi (default) and similar). Because a re-login can change the email but never the folder, vord keys everything off the slot.

The default folder is a slot too, named default. For it vord sets no environment variable at all — the agent finds its state under $HOME the way it always has. If the app itself was launched with CLAUDE_CONFIG_DIR set, the default account still uses the standard profile (vord removes the inherited variable for its own spawns); to run a specific profile, connect it as its own account.

Codex transcript tracking uses the account that the running session actually started with, including its subagent rollouts. Looking up a missing rollout runs in the background and retries are throttled. Pinning another account for the next restart does not move the running session’s transcript watcher.

Managing them

Settings → Agents → Accounts lists everything vord discovered, grouped into Claude-, Codex-, Kimi-, Grok-, OpenCode- and Muse-colored cards. Each row separates the display name, slot, real folder path and session count instead of joining them into one description. A status dot carries the state (hover it for the text; the account tooltip appears after a short 220 ms pause):

connected — signed in and ready to run sessions.
signed in — kimi’s version of the same thing (no email to show).
sign-in pending — the folder exists but the login isn’t finished, or a running Codex session reported that its sign-in can no longer be refreshed. vord won’t start new sessions on it until the sign-in changes.
signing in… — a sign-in tile for this slot is open right now.

An account that can’t run sessions yet also says so next to its name. A Sign-in pending badge comes with a Sign in button beside the row’s menu: click it to reopen that account’s sign-in tile and finish the login there. The badge disappears once the row is connected. While the tile is open, the badge reads Signing in….

Hovering the account badge on a session tile shows the account identity and, when the provider reports one, the plan name plus each quota window. See Usage & quota.

Within a usage window the percentage only goes up; values reported later by idle sessions never lower it. It drops only after the window resets.

A Default pill marks the row that new sessions currently use. The fixed-width ⋯ menu holds row actions, so long emails or translated action names cannot squeeze away the slot or Usage display. A row also tells you how many sessions use this account, and warns you when two folders of the same agent hold the same login — that’s allowed, but both then share one quota, so sparing one doesn’t spare the other. For Codex the shared limit follows the occupied workspace from the official sign-in, so a personal plan and a business plan on the same email keep separate limits. See Usage limits per window.

If a card has no discovered account, it shows a dedicated empty state with Connect account…. The Muse card is the exception: Muse has exactly one account, in ~/.config/muse, so its empty state offers Sign in to Muse… instead (see below). The public account cards and dashboard can show locally reported quota readings; see Usage & quota for the sources and limits.

Usage: tokens and cost per project

The dashboard’s Consumption tab summarizes verified local tokens and API list prices for 7, 30, or 90 days, by provider, account, project, and session. See Usage & quota for the cockpit, data sources, cost labels, and indexing limits.

You can also get there from a session: click the account control in the tile header and choose Manage accounts…. The vord menu has Manage accounts… as well, and it’s in the command palette. The tile context menu remains available, but it isn’t required for the normal flow.

New sessions start on

Every agent card carries one line that answers the only question that really matters: which account does a new session use? The visible pill picker chooses the account fresh sessions of that agent start on, or leaves it on Automatic (default folder). It’s computed with exactly the same rule the spawn path uses, so what it says is what will happen:

A pin on the tile always wins (see below) — but that’s per tile, so it isn’t part of this line.
Otherwise your choice in this picker, if that folder is still signed in.
Otherwise the default folder wins, if it’s signed in.
Otherwise the first named folder that’s signed in.

Folders with a pending sign-in never get new sessions. If your picked folder disappears, the selection silently falls back to the default — the line always shows the actual outcome.

Managed child starts and weekly limits

When spawn_agent chooses a model or account automatically, vord skips an account whose personal weekly limit has been reached. If another account for the same provider has a fresh usage reading below its own limit, vord starts the new child there. A personal limit on one account does not mean the provider is exhausted. An account whose provider reports no plan quota (such as a free tier) comes after accounts with a quota. If an account has a limit but its usage can’t be measured, vord holds the start and tells the parent which action the user needs (measure again, suspend or remove the limit); a recent weekly measurement with enough headroom still counts for 60 minutes. If no other account has measured headroom, the parent model gets the account name, limit, and reset information.

If a managed child has reached its personal weekly limit, vord holds a follow-up prompt and tells the parent immediately. The notice names the child’s account and says whether a new child can start on another measured account. The held prompt stays queued until usage permits another request. A completed child’s report still goes to its parent even when the child’s account has reached its limit.

A running session stays on the account it started with and may finish its current turn after the weekly limit is reached. vord does not move that session to another account.

Choosing before you start

A plain local shell has a visible Start agent control in its header. Open it and you get one flat, direct list for all three providers:

Claude · Automatic, Codex · Automatic, or Kimi · Automatic starts that provider with its normal account rule.
Provider · account name selects that exact account and starts the provider immediately in the same tile.
Connect account… and Manage accounts… are available in the same menu.

There is no right-click detour and no provider submenu. In a roomy header the control shows its label; in a narrow tile it becomes a compact icon so the project title and session status keep their space.

Every discovered model starts enabled. Under Settings → Agents → Models, turn off models you never want to select accidentally; newly discovered models still appear automatically. At least one model per assistant must stay enabled. Once you disable any model, Automatic is unavailable for that assistant — otherwise the provider could move its own default to a model you explicitly turned off. Running conversations keep the model they started with; the filter applies to new chats on the Mac and iPhone.

Pinning one account to an existing tile

Right-click a session (or click its account pill) and pick an account from the submenu. Automatic puts it back on the rule above. The pin is per tile, it survives restarts, and it decides both which folder the session starts on and which one it resumes into.

The pin also governs what a typed claude in that tile’s shell uses: when you launch claude yourself, vord resolves the tile’s current account choice at that very moment — pinning first and typing claude afterwards lands on the pinned account, reliably. (Only an explicit export CLAUDE_CONFIG_DIR=… you set by hand in the shell outranks it.)

In a shell tile where no agent is running yet, use Start agent to choose both provider and account. Picking an explicit row launches it immediately; you don’t have to make a choice and then type a second command.

One exception is a project lead: Change project lead… moves its session to the new account and continues the same conversation when the two accounts share their history.

Background restarts and hub catch-up, and sessions that close elsewhere, never change your selection or jump to another project.

The pill and the usage card follow the account a session really runs on. A running Claude reports the account folder it was started with, and vord corrects the tile within about half a minute if its record says otherwise. Agents that a running agent starts on its own, such as Claude calling codex or opencode from its shell, never change the tile’s account. They get their own account choice and leave the tile alone.

The submenu only offers accounts of the same agent as the tile: a codex tile is never offered your Claude logins. The slot name work can exist under every agent at once without them getting confused for each other.

The account control is available before launch in every plain local shell. Once an authenticated Claude, Codex, or Kimi process is running, the header shows the account carried by that session. Remote/SSH shells don’t get the local quick-launch control because their account folders live on a different machine.

The header shows the account’s name, which is its slot: mandr for ~/.claude-mandr, even if its address is moin@… like another account’s. The default account has no slot name of its own, so it keeps the part of its address before the @ (for example rico); if a named account of the same agent already uses that name, the default one reads rico (default). The same name appears on the usage card, in the account menus, in the settings rows (with the address below it), and on the iPhone. Very long names are shortened with a …, and the control has a hard width limit it cannot exceed, in any tile size and with any account name: the session title and the status never lose room to it. Hover it, or open its menu, for the name together with the full address.

Connecting another account

Connect account… — in the Accounts pane, in the tile’s account submenu, or from the pill — asks for the agent and a short name, shows you the exact folder it will create, then:

Creates the folder (~/.claude-<name> and so on).
Opens a sign-in tile in the cockpit and types the agent’s login command into it (claude, codex login, kimi). For OpenCode, vord probes the installed version and runs opencode console login on v1 or opencode auth login opencode on v2; XDG_DATA_HOME keeps the login in that slot.
You finish the login in that tile — it’s a normal terminal, the agent’s own browser flow runs as usual.

For OpenCode, the sheet names the login command for the installed version before you start. If that version is one vord doesn’t support (3 and later), the sheet shows a message instead of a command, and nothing is created.

The Accounts pane picks up the finished login by itself; the slot flips from “sign-in pending” to connected. The sign-in tile is a normal tile: nothing kills it, you close it when you’re done.

If a running Codex child loses its sign-in, its tile changes to Codex sign-in needed, vord marks that account sign-in pending, pauses the child, and tells you to sign in again or restart the task on another account. Its parent is told that the child cannot continue.

Names are limited to letters, digits, - and _, can’t start with -/_, and can’t be default — the name becomes a real folder name, so it has to survive being a path.

The sign-in tile has no account stamp of its own; it runs with the target account’s config folder, including the new folder, and never uses another account. A row with the Sign-in pending badge has Sign in beside its menu and in the menu to reopen that account’s tile, plus Remove. Adding the same name again offers Continue sign-in.

New Claude accounts share these entries from ~/.claude by symlink: settings.json, CLAUDE.md, hooks/, skills/, agents/, commands/, knowledge/, history.jsonl, sessions/, session-env/, file-history/, paste-cache/, plans/, shell-snapshots/, debug/, and tasks/; projects/ follows the shared history. The login itself (.claude.json) stays with each account, as do plugins/, cache/, backups/, and security/. If a new account already has its own file with one of the shared names, vord keeps it and Settings shows a warning. Existing accounts are not changed.

Muse has exactly one account. Muse reads its sign-in only from ~/.config/muse (or $XDG_CONFIG_HOME/muse), so vord does not create named Muse folders: the connect sheet doesn’t list Muse, and the Muse card has no Connect another account… button. When no Muse account is found, Sign in to Muse… opens a sign-in tile that runs muse login against that default folder. Alternatively set META_API_KEY. Folders named ~/.muse-<name> from earlier versions are left untouched; vord ignores them.

Shared Codex settings

Codex accounts use the same CLI settings from ~/.codex/config.toml. These include the model, thinking depth, permission mode, and MCP configuration. A new account also gets your chosen YOLO mode if it is set in the shared configuration.

vord prepares the shared configuration before sign-in, start, or resume. Existing account-specific configurations are first backed up as config.toml.vord-backup-* in the relevant account folder. If the default file is missing while the slot already has a configuration, vord stops and leaves both files unchanged; an empty default file is created only for a truly fresh installation. Sign-ins and auth.json remain separate. Changes to the shared configuration apply to all connected accounts the next time they start.

forced_chatgpt_workspace_id must not be shared: it binds Codex to a workspace and visibly blocks sign-in, start, or resume. forced_login_method, by contrast, is intentionally shareable because it only specifies the CLI sign-in method and does not select a workspace.

Additional Codex accounts also get the Codex app’s bundled plugins (for example Computer Use, MCP server cua_repl) from ~/.codex: vord links .tmp/bundled-marketplaces/openai-bundled and plugins/cache/openai-bundled into the account folder and points the openai-bundled marketplace there at launch. Existing folders in the account stay untouched.

Profiles such as $CODEX_HOME/<name>.config.toml are outside this contract; vord does not start Codex with --profile. Relative values for model_instructions_file, sqlite_home, log_dir, and history are also not shared: Codex resolves them per process against its working directory or CODEX_HOME. To intentionally share this data, use absolute paths and accept a shared history or database.

If vord cannot safely prepare the shared configuration, the app shows an error and does not start the session with different settings.

Removing an account

Open a row’s ⋯ menu and choose Remove… to move its folder to the Trash — never a hard delete, because that folder holds the agent’s entire local history for this account: conversations, settings, project state. You can pull it back out of the Trash until you empty it.

Two guards:

The default folder is never removed. It’s the agent’s own baseline, and vord didn’t create it. Sign out inside the agent instead.
An account with running or starting sessions is locked. The row counts those sessions; saved or ended sessions do not prevent removal. End running sessions first. Pinning a different account takes effect only after restart and does not free the account currently in use.

The confirmation notes that local history will be moved to the Trash. Saved conversations alone do not prevent removal, but their account-specific files are moved too. Shared, linked history remains in the shared folder.

By default each account keeps its own conversation history: a session started on work is only listed when you resume on work. With Share session history in the Accounts pane (Settings → Agents → Accounts) vord merges the histories of all accounts of one provider into the default account’s folder and links every other account folder to it with a symlink. From then on every session of that provider shows up on every account — because the agents themselves don’t lock a saved session to the account that wrote it.

What happens when you turn it on:

Files from each linked folder are merged into the default folder. Nothing is deleted — each original folder is renamed to <folder>.pre-link-<timestamp> as a backup, and files that already existed in both places keep the default folder’s version (the other one stays in the backup). Note: the backup lives inside the account’s own folder, so removing that account later moves the backup to the Trash together with everything else.
Sessions that are running right now are skipped and migrated automatically as soon as they’re quiet — the app keeps the list and finishes the job in the background. Merging under a live session would split its history. (This watch covers vord’s own tiles; finish a session running in an external terminal on that account before enabling the switch.)
A per-account result appears under the switch: what was merged, any conflicts, and where the backup is. If anything couldn’t be linked (for example a folder that’s already a link to somewhere else), the switch tells you instead of pretending.

Some sessions have no account on record, typically older ones. With shared history on, resuming such a session uses the same choice as a fresh start (see New sessions start on), so the automatic choice applies as well. The chosen account is stored with the session from then on. If the automatic choice finds no usable account, vord doesn’t resume the session and tells you why. Pin an account to the tile and resume again. Without shared history, such a session still resumes on the default account.

Turning the switch off stops the linking, the background upkeep, and the catch-up of skipped sessions, but it does not unlink or undo anything — the shared folder stays shared. Removing a linked account moves its whole folder (symlink and backups included) to the Trash; the shared history itself and other accounts’ folders are untouched. Currently available for Claude and Codex; more providers follow once their resume behavior under a shared folder is verified.

Limits

Personal usage limits are per window. On the Usage limits tab each account is a card. Limits sets a mark from 5 to 95 % on any reported window, in steps of 5, and Pause account stops the account outright. A limit on a model window blocks the whole account. See Usage limits per window.
Discovery is a snapshot. It runs at launch, after a sign-in, and when you hit Refresh. Folders you create by hand outside vord show up after a refresh.
No account UI on the iPhone. The companion shows which Claude account a session runs on (see Controlling Sessions from the iPhone), but connecting, pinning and removing happen on the Mac.