Billing per agent

Put each agent on its own Claude account, so personal and work usage never share a plan. Step by step, no coding needed.

Say you run two agents: Kevin for personal life and Scout for client work. Out of the box both use whichever Claude account you last logged in with, so their usage lands on one plan. With a few minutes of setup, each agent uses its own account instead:

Agent	Home folder	Bills to
Kevin	`~/Documents/Agents/Kevin`	Your personal Claude account
Scout	`~/Documents/Agents/Scout`	Your work Claude account

Don't have a second agent yet? Start with Adding another agent.

This page covers Claude Code 2.1.312 or later. Codex signs in its own way and is not covered here yet.

How it works

Claude Code can sign in two ways. Normally it uses the account you logged into with /login, and there is only one of those per computer: log in as your work account and every agent switches to it.

The second way is a token: a long password-like key tied to one account. You create one token per account and save each in its agent's folder. Then you start that agent with agent instead of claude. agent is a small command you add to your terminal once: in a folder that has a saved token, it starts Claude Code with that token, and anywhere else it behaves exactly like claude. Each agent uses only its own folder's token, so each one stays on its own account, even when both run at the same time.

Before you start

A paid plan on every account. Each account needs Pro, Max, Team, or Enterprise. Two accounts means two subscriptions.
Claude Code 2.1.314 or later. Run claude --version in a terminal, and claude update if it is older.
A plain-text editor, for one step. On a Mac, CotEditor is free and simple. On Windows, VS Code is free and works well. Avoid TextEdit and Notepad: they can swap straight quotes for curly ones.
About ten minutes, and the email and password for each account.

Already set this up before 0.9.0, with the token in settings.local.json? Run /agent-kevin:upgrade in that agent: it moves the token for you and offers to add the agent command, so you can skip to Check it worked.

Set it up

Close your agents

In every terminal where an agent is running, type /exit.

Open a terminal in your user folder

Open a new terminal window: Terminal on a Mac, PowerShell on Windows. Then run:

cd ~

Sign in to the first account in your browser

Go to claude.ai and check which account is signed in (your name is at the bottom left). If it is not the account for your first agent, sign out and sign in to the right one.

Create the token

In the terminal, run:

claude setup-token

Your browser opens and asks you to approve access. Approve it. Back in the terminal, a long line of text starting with sk-ant- appears. That is the token. Select all of it and copy it.

Claude Code does not save the token anywhere, so keep it on your clipboard until you finish the next step.

Save the token in the agent's folder

With the token still copied, run this one line. It writes the token from your clipboard into the agent's secrets folder without showing it on screen. Change Kevin to your agent's folder name:

cd ~/Documents/Agents/Kevin && mkdir -p .state/secrets && printf '{"env":{"CLAUDE_CODE_OAUTH_TOKEN":"%s","AGENT_SUBSCRIPTION":"1"}}\n' "$(pbpaste | tr -d '[:space:]')" > .state/secrets/.env.claude.json && chmod 600 .state/secrets/.env.claude.json && cd ~

The file it writes looks like this, with your token in place of the placeholder:

{"env":{"CLAUDE_CODE_OAUTH_TOKEN":"sk-ant-oat01-…","AGENT_SUBSCRIPTION":"1"}}

AGENT_SUBSCRIPTION lets the agent tell, at the start of each session, whether it was started with this file. Never paste the token into a chat with your agent.

Add the agent command (once per computer)

Open your terminal's startup file in your editor and paste the block at the very end:

In CotEditor, choose File → Open and go to your user folder (the one with your name). The file is hidden at first: press Shift + Cmd + . (the period key) to show hidden files.
Open .zshrc. If there is none, choose File → New instead, and save it in your user folder as .zshrc at the end.
Paste this at the end and save:

# Claude with subscription segmentation
agent() {
  local s=$PWD/.state/secrets/.env.claude.json
  [[ -f $s ]] && set -- --settings "$s" "$@"
  claude "$@"
}

Back in the terminal, run source ~/.zshrc (or open a new terminal window).

You only do this once, however many agents you have.

Repeat for the next agent

On claude.ai, sign out, then sign in to the other account.
In the terminal, run claude setup-token again, approve, and copy the new token.
Run the save command from step 5 again, with the second agent's folder name.

Do this for every agent that should have its own account. Give your main agent a token too: then logging into a different account later never moves it.

Start each agent with agent

From now on, start each agent from its own home folder with agent instead of claude:

cd ~/Documents/Agents/Kevin && agent

Check it worked

Inside each agent:

The banner at the top names your plan (for example Claude Max), not "API Usage Billing".
/status shows how the agent signed in. It should name the token (CLAUDE_CODE_OAUTH_TOKEN), not your regular login. This proves the token is in use, but not which account it belongs to.
/usage shows the plan usage of the account that agent is on. Run it in both agents. Different numbers mean different accounts.

If both show the same numbers, give one agent a short task and run /usage in both again. Only that agent's number should move. If both move, they share one account: redo the token for one of them, making sure the browser is signed in to the other account first.

Once a year

Each token lasts one year. Put a reminder in your calendar for the day you made it. When a token runs out, the agent stops being able to sign in: create a new one and save it with the same command (steps 2 to 5 above, which replace the old token), then restart that agent with agent.

Good to know

Typing claude instead of agent uses your regular login. The agent notices: its first message warns that this session started without its own subscription. Type /exit and start it again with agent.
The token only chats with Claude. It cannot start Remote Control sessions or use connectors you set up on claude.ai. Tools and MCP servers set up on your computer, including all of Kevin's, still work. For commands that need your full login, such as claude remote-control, use claude, not agent.
It works the same in cmux and in any other terminal, since agent is a command of its own.
Your regular login still matters elsewhere. Claude Code sessions started with claude, or outside an agent's folder, keep using the account from /login.
Treat the token like a password. The secrets folder is excluded from git and never leaves your computer. Don't copy the token into documents, chats, or screenshots.
Why not settings.local.json any more? Claude Code 2.1.312 stopped reading the token from an agent's own settings files, so it lives in its own file now.

If something's off

What you see	What to do
`agent: command not found`	Your terminal hasn't loaded the new command yet. Open a new terminal window, or run `source ~/.zshrc` (Windows: `. $PROFILE.CurrentUserAllHosts`)
The agent warns this session started without its own subscription	You started it with `claude`, or from an app that doesn't use your terminal. Type `/exit`, then start it with `agent` from its home folder
Both agents use the same account	Both tokens were made while the browser was on one account. On claude.ai, switch to the other account, create a new token, and save it in one agent's folder again
The banner says "API Usage Billing"	Something other than the token is signing in, such as an API key (below) or an `apiKeyHelper` setting. Remove it and start the agent with `agent`
`agent remote-control` or another command fails with "OAuth refresh token is no longer valid" or "Could not resolve authentication method"	The token only chats; that command needs your full login. Run it with `claude` instead
Sign-in errors about a year after setup	The token ran out. See Once a year

Something stronger overriding the token. An API key saved in your terminal's settings outranks the token, and the agent then bills that key instead. To check, run this in a normal terminal:

env | grep ANTHROPIC

If it prints ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN, that variable is winning. Remove it from your shell profile (~/.zshrc on a Mac) and open a new terminal.

Other ways to split billing

You want	Use
Each agent on its own subscription, automatically, by folder	The token and `agent`, as above
Several Claude accounts for all of Claude Code, not tied to an agent	A separate config folder per account. See Anthropic's multiple accounts guide
An itemised bill per client that you can invoice or expense	An API key from a separate Anthropic Console organization per client, saved as `ANTHROPIC_API_KEY` in place of the token. This bills per use rather than a flat monthly fee

Anthropic describes setup-token as meant for scripts and servers where a browser login isn't available. If billing matters contractually, for example for a client, check your plan's terms or use the API key route.