Operate the Claude router

The Claude router is a local proxy that routes Claude Code conversations across several Claude subscription accounts. A user with one account does not need it.

Find the command

An agent's shell may not have claude-router on PATH. This prints its absolute path:

echo "${XDG_DATA_HOME:-$HOME/.local/share}/astack/claude-router/bin/claude-router"

Below, claude-router stands for that path. Write the absolute path in every command you run or give. If the file is missing, the router is not installed, and Set up from nothing applies.

Run the read-only commands yourself

Run status, check, and cache yourself. When status does not explain a failure, also run the state and log commands in Find the service. None of these commands stops, restarts, or reconfigures the router. check sends one short test message on one account's plan. Show their lines as printed. The router's tests check that its status, events, and service logs hold no token.

To answer "is the router working", run check and report its lines, with the step from Read check lines for each fail line.

Give the user every other command

Give every other command to the user in a code block, to run in their own terminal, and say which reason applies:

• A command that stops or restarts the router cuts off every routed session in the middle of a turn, possibly this one.
• A sign-in waits on a browser window that only the user can use.
• start turns the router on at every login.

NAME is the user's label for an account, such as work. With -no-browser, setup, account add, and login print the sign-in URL. account remove refuses for the last account, and for an account with conversations from the last 5 hours. With -force, those conversations move to another account on their next request.

CHECKOUT is the absolute path of the user's astack checkout. Ask the user for it.

Read check lines

check prints one line per check, then check passed or check failed, then a next line after a failure. Each line starts with ok, fail, or skip. A skip line follows a failure or a stopped router and needs no step.

For the settings line:

• setup with no -account reuses the accounts in config.json. If it refuses with config.json lists no accounts, give claude-router setup -account NAME ....
• If setup refuses with Claude Code already routes through the router, the settings changed after activation. Give claude-router direct, then the same setup. If direct refuses, give its next line.
• A settings file whose env sets ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN also fails this line. setup refuses until the user removes the key.

If check stops before the first check line, it prints a line that starts with claude-router: or astack:. Report that line, and give the next line if one follows.

Know what the router costs and refuses

A conversation stays on its account until that account's included allowance runs out. Then the router moves the conversation to another account, and the next request writes the conversation's prompt cache again there. cache reports these moves and their cache writes. status prints a cache line when moves caused more than 10% of the last 24 hours' cache writes.

A Claude model newer than the router's model list gets a 503 that says the SDK refused the pinned account without an upstream attempt. The router reads the published model catalog at each start, so give the user claude-router stop and claude-router start.

Paid overflow is the claude.ai setting that bills usage past the plan's included allowance, shown there as extra usage or usage credits. The router sends requests only to accounts whose latest reading shows paid overflow off. If the user turns paid overflow on after the last reading, while the account's included allowance is used up, one paid response can happen before the router sees it.

Set up from nothing

Give the user these steps. Put the checkout's absolute path in place of CHECKOUT, and the user's account labels in place of work and alumni.

1. Install Go 1.26 or newer from https://go.dev/dl/, Python 3.10 or newer, and Claude Code. python3 --version, go version, and claude --version must work in the shell.
2. If the user has no astack checkout, give git clone https://github.com/syanga/astack.git. CHECKOUT is then the absolute path of the new astack directory.

3. Download the pinned modules once, with network access:

   (cd CHECKOUT/components/claude-router && go mod download)

4. Build and install the router. The install changes no Claude Code settings:

   cd CHECKOUT && ./install.sh --component claude-router

5. When the install asks Add claude-router to PATH in FILE? [Y/n], press Enter. When it prints SKIP PATH instead, add the line it prints to the shell's startup file. Then open a new shell.

6. On Linux only, let the router run without a login session:

   sudo loginctl enable-linger "$USER"

7. Sign in each account, start the router, and activate it:

   claude-router setup -account work -account alumni

   It ends with activated Claude Code routes through the router. On Linux, the code matches line ends with (darwin/arm64), and a note line says not yet tested on real Linux. Both name the accepted record's platform, and neither is a failure.

If setup refuses because an account has paid overflow on, ask the user to turn it off on claude.ai, then give claude-router stop and claude-router setup. Without the stop, the running router keeps its old reading for up to 10 minutes and setup can refuse again.

After setup and after direct, tell the user to start a new Claude Code session, because a session reads its settings when it starts. After the user reports that setup finished, run check.

Roll back

Give the user claude-router direct, and tell them to start a new Claude Code session. If direct prints after claude needs its own /login, tell the user to run /login in that session. claude-router setup activates the router again. cd CHECKOUT && ./uninstall.sh --component claude-router removes it. direct and uninstall keep logins and assignments.

Find the service

When status does not explain a failure, run the state and log commands for this system and report what they show.