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 handovaYarn 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:
- Claude Code, Codex or both, installed and working on their own first.
- Node.js 20 or newer, or Bun.
- macOS. Linux should work; Windows isn't supported yet.
Guided setup
Once it's installed, run:
$ handova setupSetup walks you through everything, one question at a time:
- 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.
- 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,mainor anything you like. If it isn't logged in yet, setup offers to log in. - 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.
- 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.
| Agent | Usual folder | Extra accounts | Set 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 frontIf 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.
| Agent | Shared (linked) | Copied |
|---|---|---|
| Claude Code | CLAUDE.md, skills, agents, commands | settings.json |
| Codex | AGENTS.md, prompts, skills | config.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 ~/.codexNames 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.
| From | To | Works? | What moves |
|---|---|---|---|
| Claude Code | Claude Code | Yes | The conversation, files saved with it (like subagent transcripts) and that folder's memory |
| Codex | Codex | Yes | The conversation. Codex keeps memory per account, not per folder, so it stays |
| Claude Code | Codex, or back | Not yet | Nothing. 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 againWhat gets handed over
Claude Code to Claude Code copies:
- The whole conversation: your messages, Claude's replies, and every tool call (file reads, edits, commands it ran) with its result. That's what lets the other account carry on exactly where you stopped.
- Files saved alongside it, like subagent transcripts and long tool output.
- Claude Code's memory for that folder:
MEMORY.mdand its memory files, merged without overwriting what the other account already has.
Codex to Codex copies:
- The whole conversation: your messages, Codex's replies, and every tool call with its result. Codex rebuilds its own index from it when you resume.
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:
- Your instructions:
CLAUDE.mdfor Claude Code,AGENTS.mdfor Codex. - Your skills, plus
agentsandcommandsfor Claude Code, andpromptsfor Codex. A skill you add from any account shows up in all of them. - Your code: every account works in the same folder on the same computer. Skills kept in the project (like
.claude/skills) come with it.
Accounts added with --no-share, or folders adopted with --dir that already had their own, keep their own instructions and skills instead.
Never copied:
- The undo history for file edits, so rewind on the new account can't reach before the handoff.
- Your other conversations, unless you hand them over too.
- Logins and settings: each account keeps its own.
- Claude Code's saved plan files. The conversation where a plan was made does move.
- Codex's memory, which belongs to the whole account rather than a folder.
What happens
- Run it where you were working. Conversations are kept per folder, so run it in the folder you used the agent in.
- It finds the conversation: your latest one in that folder, or the one you pick with
--pickor--session <id>. - It asks first. It names the account and organization the conversation is going to, and waits for a yes. Skip the question with
--yes. - It copies, never overwriting. Anything already on the other account is kept.
- It opens it there. The agent starts on the other account with the conversation loaded. Use
--no-resumeto copy only.
The fine print
- The copy is a fork. What you do on the new account doesn't flow back to the old one.
- Handing over again brings an older copy up to date, if you only carried on with the original.
- If both copies were continued, they've diverged. Handova won't merge them and tells you to resume on the other account instead.
- Claude Code memory merges file by file: files the other account already has are kept and listed, and missing lines are added to
MEMORY.md. Leave memory behind with--no-memory.
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
- Logins are checked with
claude auth statusand opened withclaude auth login.handova listshows the email and organization. - Conversations live in
projects/inside the account's folder, grouped by the folder you started Claude Code in. - Memory is per folder, so a handoff can bring it along.
- Your primary login runs with
CLAUDE_CONFIG_DIRunset, exactly like plainclaude.
Codex
- Logins are checked with
codex login statusand opened withcodex login. For a ChatGPT login,handova listshows the email and plan (for example "ChatGPT plus") in the organization column; for an API key, "API key". - Conversations live in
sessions/inside the account's folder, filed by date. A handoff copies the conversation to the same place in the other account, andcodex resumepicks it up with its full history. - Memory is per account, so it isn't moved.
- Your primary login runs with
CODEX_HOMEunset, exactly like plaincodex.
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
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
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 backup | starts a new conversation |
handova backup --continue | reopens the last conversation in this folder |
handova backup --resume | lists past conversations to pick from |
Hand a conversation to another account
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.
--pick | choose the conversation from a list |
--session <id> | hand over one specific conversation |
--no-memory | copy only the conversation |
--no-resume | copy without opening the agent |
--yes | skip the confirmation |
Add an account
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|codex | say which agent, so it doesn't ask |
--dir <folder> | use a folder you already have |
--no-share | start without your shared files |
--no-login | skip the login step |
List accounts
Shows every account in a table: its agent, who it's signed in as, the organization and its folder.
Remove an account
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
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
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
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 doctorChecks 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 see | What to do |
|---|---|
can't run "codex" in the list | That agent isn't installed or isn't on your PATH. Install it, or take the account off the list. |
not logged in | Log in with handova <account> auth login for Claude Code, or handova <account> login for Codex. |
| No sessions for this folder | Run the handoff from the folder you started the agent in. |
| Already further along on the other account | That account has the newer copy. Resume it there with the command Handova prints. |
| The two copies have diverged | Both were continued. Handova won't merge them; resume on the account you want to keep. |
| A Claude Code account and a Codex account | Handoffs only work between accounts of the same agent. |
| This needs a confirmation | You're not in an interactive terminal. Run it again with --yes. |
| No accounts yet | Install Claude Code or Codex, then run handova setup. |
CLAUDE_CONFIG_DIR or CODEX_HOME is set in your shell | Remove it from your shell profile. Handova sets it per account. |
Privacy and safety
- No network requests. Handova copies files on your computer and starts your agent, which talks to its provider as it always does.
- Logins stay with the agents. Handova never stores logins. It asks each agent whether it's logged in, and for Codex reads the email and plan from Codex's own login file to show in the list.
- It confirms before it sends or deletes. Handoffs and
--purgeboth ask first. - It never deletes your agents' usual folders (
~/.claude,~/.codex), and never edits your shell profile.
Uninstall
$ handova remove backup --purge # optional: delete extra accounts first$ npm uninstall -g handova # or: pnpm remove -g, yarn global remove, bun remove -gYour primary Claude Code and Codex logins aren't touched. To forget Handova's account list too, delete~/.config/handova.