AgentLayer▸docs
Run it

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.

In short

This page puts each agent on its own Claude account, so personal and work usage land on separate plans. Check Before you start first: every account needs a paid plan, and the setup takes about ten minutes.

Say you run two agents: Oppi 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:

AgentHome folderBills to
Oppi~/Documents/Agents/OppiYour personal Claude account
Scout~/Documents/Agents/ScoutYour work Claude account

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

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

How it works

Each agent gets a token from its own account, and a small agent command starts Claude Code with that token. Open this for why that keeps the accounts apart.

Before you start

  • A paid plan on every account. Each account needs Pro, Max, Team, or Enterprise. Two accounts means two subscriptions.
  • An up-to-date Claude Code. Run claude update in a terminal. The version the plugin needs is on the Claude Code page.
  • 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.

Set this up before, with the token in settings.local.json? The upgrade skill moves the token for you and offers to add the agent command (Upgrades). Then 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 Oppi to your agent's folder name:

cd ~/Documents/Agents/Oppi && 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:

  1. 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.
  2. Open .zshrc. If there is none, choose File → New instead, and save it in your user folder as .zshrc at the end.
  3. 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 "$@"
}
  1. 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

  1. On claude.ai, sign out, then sign in to the other account.
  2. In the terminal, run claude setup-token again, approve, and copy the new token.
  3. 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/Oppi && agent

Check it worked

Inside each agent:

  1. The banner at the top names your plan (for example Claude Max), not "API Usage Billing".
  2. /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.
  3. /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 your agent'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. cmux's Claude Code button is the exception: it runs claude until you change its command to agent, as in Toolbar buttons.
  • 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 stopped reading the token from an agent's own settings files, so it lives in its own file now.

If something's off

Most problems are the new command not loaded yet, an agent started with claude, or both tokens made on one account; find the symptom below, or check for an API key overriding the token.

Other ways to split billing

You wantUse
Each agent on its own subscription, automatically, by folderThe token and agent, as above
Several Claude accounts for all of Claude Code, not tied to an agentA separate config folder per account. See Anthropic's multiple accounts guide
An itemised bill per client that you can invoice or expenseAn 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.

On this page