Getting started.

Got more than one Claude Code or Codex account? Handova lets you switch between them without logging out and back in, and hand a conversation and its memory to another account when one hits its usage limit. Every account keeps its own clean profile. Install it, let the guided setup add your accounts, and you're ready.

Install

Install it globally with your package manager:

npm install -g handova

Yarn 2 and later have no global installs, so use Yarn 1 or another manager. To try it once without installing, runnpx handova, pnpm dlx handova or bunx handova.

You'll need:

Guided setup

Once it's installed, run:

$ handova setup

Setup walks you through everything, one question at a time:

  1. Which agents. If both Claude Code and Codex are installed, it asks whether you want more than one account for Claude Code, Codex or both. Agents you haven't installed aren't offered. With only one installed, it skips the question.
  2. Your primary login. For each agent it asks what to call the login you already have, the one the agent uses on its own, and shows which email it belongs to. Setup suggests primary; call itpersonal, main or anything you like. If it isn't logged in yet, setup offers to log in.
  3. More accounts. It asks whether to add another account, suggests a name, creates it with your instructions and skills shared, and opens the agent's own login. It keeps asking until you say no.
  4. Summary. It lists your accounts and shows the commands to try next.

Run it again any time to add more accounts. It keeps everything you already have, and if you stop halfway, whatever was added stays.

Prefer commands?

Setup is optional. Everything it does is also a command: handova add, handova list and so on. See Commands.

How it works

Each coding agent keeps an account's login, settings and conversations in a config folder, and lets you point it at a different folder with an environment variable. Handova gives every account its own folder and sets that variable when it starts the agent.

AgentUsual folderExtra accountsSet with
Claude Code~/.claude~/.claude-<name>CLAUDE_CONFIG_DIR
Codex~/.codex~/.codex-<name>CODEX_HOME

Because every account has its own folder, the logins are separate. Logging in or out of one account never affects another, and you can run several at once in different terminals. Each account keeps its own clean profile: its own conversations, memory and settings, with no other organization's data mixed in.

The flip side is that one account can't see another's conversations. That's what handoff is for: it copies the conversation itself (and, for Claude Code, that folder's memory) to the other account, so the agent resumes it exactly where it stopped. That's different from /export, which saves a text transcript: pasted into another account it arrives as one long message, uses up a lot of that account's usage, and brings no memory.

Handova keeps its list of accounts in ~/.config/handova/accounts.json. Until something is saved there, it shows the primary login of each agent you have installed.

Accounts

An account is one of your logins for one agent. Each account remembers its agent, so after you add it you only use its name: handova backup starts Claude Code if backup is a Claude Code account, and Codex if it's a Codex account. The name is only a label.

Primary logins

Your primary login for an agent is the one it already uses on its own, in its usual folder. Setup asks what to call each one. Until you've run setup, Handova shows them as primary for Claude Code and codex for Codex. They're marked (primary) in handova list and run the agent exactly as it runs on its own. Rename them any time, or take one off the list if you don't use that agent.

Adding an account

$ handova add backup                       # asks which agent it's for$ handova add codex-backup --agent codex   # says so up front

If you have both Claude Code and Codex installed, handova add asks which agent the account is for. With only one installed, it uses that one without asking. In scripts, where there's no one to ask, pass--agent.

A new account gets its own folder and opens the agent's login. Your instructions follow it: these are linked from your primary login, so edits show up in every account, while settings are copied so each account can change its own.

AgentShared (linked)Copied
Claude CodeCLAUDE.md, skills, agents, commandssettings.json
CodexAGENTS.md, prompts, skillsconfig.toml

Use --dir to adopt a folder you already have; if it's logged in, the login step is skipped. Pointing it at an agent's usual folder registers your primary login, for example if you installed Codex after you started using Handova:

$ handova add codex --agent codex --dir ~/.codex

Names use lowercase letters, digits and dashes.

Renaming and removing

$ handova rename backup spare    # only the name changes$ handova remove spare           # forget it; folder and login stay$ handova remove spare --purge   # also log out and delete its folder

--purge asks first, and never deletes an agent's usual folder: removing a primary login only takes it off Handova's list.

Handoff

A handoff moves a conversation from one of your accounts to another, so you can keep going when one hits its usage limit. Both accounts must be the same agent.

FromToWorks?What moves
Claude CodeClaude CodeYesThe conversation, files saved with it (like subagent transcripts) and that folder's memory
CodexCodexYesThe conversation. Codex keeps memory per account, not per folder, so it stays
Claude CodeCodex, or backNot yetNothing. Handova stops before copying and explains why
$ handova handoff primary backup       # Claude Code to Claude Code$ handova handoff codex codex-backup   # Codex to Codex$ handova handoff backup primary       # and back again

What gets handed over

Claude Code to Claude Code copies:

Codex to Codex copies:

Already shared, so nothing to copy. When you add an account, these are linked to your primary login, so the other account has them before any handoff and every account stays in sync:

Accounts added with --no-share, or folders adopted with --dir that already had their own, keep their own instructions and skills instead.

Never copied:

What happens

  1. Run it where you were working. Conversations are kept per folder, so run it in the folder you used the agent in.
  2. It finds the conversation: your latest one in that folder, or the one you pick with --pick or --session <id>.
  3. It asks first. It names the account and organization the conversation is going to, and waits for a yes. Skip the question with --yes.
  4. It copies, never overwriting. Anything already on the other account is kept.
  5. It opens it there. The agent starts on the other account with the conversation loaded. Use --no-resume to copy only.

The fine print

Organizations

Handing a conversation to another account means it's processed under that account's organization. Handova names it and asks before copying. If your workplace doesn't allow moving work between accounts, don't.

Agents

Claude Code

Codex

Adding more agents

Everything specific to an agent lives in one file in src/harness/. Before an agent is added, its login and conversation storage are checked against a real install. The checklist is in theproject's CLAUDE.md.

Commands

Every command, part by part.

Guided setup

handovasetup↑ action

Asks whether you want more than one account for Claude Code, Codex or both (only installed agents are offered), asks what to call your primary login for each, then adds the accounts you name and logs you in to each. Run it again any time to add more.

Run your coding agent as an account

handovabackup↑ account--continue↑ passed to the tool

Opens the account's coding agent, Claude Code or Codex, logged in as backup. Anything after the account name is passed to it, so it works the same as running the agent yourself.

handova backupstarts a new conversation
handova backup --continuereopens the last conversation in this folder
handova backup --resumelists past conversations to pick from

Hand a conversation to another account

handovahandoff↑ actionprimary↑ frombackup↑ to

Both accounts must be the same agent: Claude Code to Claude Code, or Codex to Codex. Run it in the folder you were working in. It finds your latest conversation there on primary, asks before sending it to backup, copies it (plus that folder's memory, for Claude Code) and opens it there. Hand it back with handova handoff backup primary.

--pickchoose the conversation from a list
--session <id>hand over one specific conversation
--no-memorycopy only the conversation
--no-resumecopy without opening the agent
--yesskip the confirmation

Add an account

handovaadd↑ actionbackup↑ name you choose

Asks which agent the account is for (unless you have only one installed), creates a folder for it, shares your instructions and skills, copies your settings, then opens the login.

--agent claude|codexsay which agent, so it doesn't ask
--dir <folder>use a folder you already have
--no-sharestart without your shared files
--no-loginskip the login step

List accounts

handovalist↑ action

Shows every account in a table: its agent, who it's signed in as, the organization and its folder.

Remove an account

handovaremove↑ actionbackup↑ account--purge↑ optional

Forgets the account and keeps its folder and login. With --purge, it also logs the account out and deletes its folder, after asking. It never deletes an agent's usual folder.

Rename an account

handovarename↑ actionbackup↑ current namespare↑ new name

Changes only the name; the folder and login stay the same. Works for your primary logins too, so primary can become main, personal or anything you like.

Check everything

handovadoctor↑ action

Checks that each account's coding agent is installed, every account is logged in, and the shared links still work. For anything wrong, it says how to fix it.

Print shortcuts

handovashell-init↑ action

Prints a claude-<account> shortcut for each account. Add eval "$(handova shell-init)" to your shell profile to use them.

handova help lists every command and handova --version prints the installed version.

Troubleshooting

Start with:

$ handova doctor

Checks each agent is installed, every account is logged in and the shared links still work, and says how to fix anything that isn't.

You seeWhat to do
can't run "codex" in the listThat agent isn't installed or isn't on your PATH. Install it, or take the account off the list.
not logged inLog in with handova <account> auth login for Claude Code, or handova <account> login for Codex.
No sessions for this folderRun the handoff from the folder you started the agent in.
Already further along on the other accountThat account has the newer copy. Resume it there with the command Handova prints.
The two copies have divergedBoth were continued. Handova won't merge them; resume on the account you want to keep.
A Claude Code account and a Codex accountHandoffs only work between accounts of the same agent.
This needs a confirmationYou're not in an interactive terminal. Run it again with --yes.
No accounts yetInstall Claude Code or Codex, then run handova setup.
CLAUDE_CONFIG_DIR or CODEX_HOME is set in your shellRemove it from your shell profile. Handova sets it per account.

Privacy and safety

Uninstall

$ handova remove backup --purge   # optional: delete extra accounts first$ npm uninstall -g handova      # or: pnpm remove -g, yarn global remove, bun remove -g

Your primary Claude Code and Codex logins aren't touched. To forget Handova's account list too, delete~/.config/handova.