Skip to content
Agent Switch Agent Switch

Working with agent-config

agent-config is a separate tool that gives coding agents rules, skills and a review council. When both are installed, they share two things:

  • Every account’s limits. agent-config reads them from Agent Switch, so it can tell you a limit is coming and keep its own council seats off accounts that are full.
  • One question near a limit. “Move this work to another account?” is asked in your session and in the Agent Switch app at the same time. Whichever you answer first counts for both. Agent Switch makes the move.

Nothing moves without your answer, in either tool.

How it connects

Section titled “How it connects”

agent-config starts agent-switch mcp serve, a local MCP server, as part of your agent session. It runs as you, talks over the session’s own input and output, and opens no port. There is nothing to sign in to.

Turn it off in the app (Settings › Protection › Let agent-config connect) or in a terminal:

Terminal window
agent-switch link off      # agent-config stops connecting; mcp serve offers no tools
agent-switch link on       # the default
agent-switch link status --json

What happens near a limit

Section titled “What happens near a limit”

  1. A question is opened. When a running session’s account reaches 90 % of a window (or its protection threshold, if that is lower), the background service opens a switch request. agent-config may open one earlier, when its own quota reading says the window is filling fast. Each request lists the accounts the work could move to: same tool first, the emptiest first, plus one account of the other tool as a handoff.

  2. You are asked, in both places. agent-config tells you in the session. The app opens its near-limit sheet and marks it “agent-config asked”.

  3. You answer once. Choose an account and how: after this turn, now, or as a handoff (a new session that starts from a written brief). Or keep going, or decline. The first answer is kept; an answer given later in the other tool is not applied, and it shows you the first one.

  4. Agent Switch moves the work. An answer given in agent-config is carried out by the background service. An answer given in the app is carried out by the app, as before. A move that needs a terminal (a Codex move, a handoff) leaves the command to continue with.

When accounts run at different paces

Section titled “When accounts run at different paces”

Waiting for 90 % can be too late to spread the work well: one account is spent by Tuesday while another resets on Friday with half its week unused. So the background service also asks earlier, when both are true:

  • This account runs too fast. At the rate its own usage rose over the last hours, it would reach its protection threshold before 80 % of the time to its reset has passed. Windows that reset within six hours are left to the limit question; the 5-hour window fills during any real session.
  • Another account would waste room. An account of the same tool with no session of its own would still be below 60 % when it resets.

The request is a pace request (kind: "pace") and carries how many hours are left (etaFull) and, per account offered, how much would expire unused (spareAtReset). You answer it like any other: in the session, in the app (it waits in the list and never opens a sheet by itself), or here. Putting it off (snooze or decline) keeps it closed until that window resets; the question near the limit still comes.

Terminal window
agent-switch pace status --json   # {"enabled":true}
agent-switch pace off             # only the question near the limit remains

In the app: Settings › Protection › Suggest a switch when accounts run at different paces.

In the chat

Section titled “In the chat”

With agent-config, its prompt-time hook reads switch_list for your session and shows the request’s summary — one plain sentence — then records your answer through switch_decide. This works for Claude Code and Codex.

Without agent-config, Claude Code can still hear about a request. The prompt hook is opt-in:

Terminal window
agent-switch hooks chat on        # every Claude account; or name one
agent-switch hooks chat status
agent-switch hooks chat off

When a request is open for the session, Claude gets one line of context with the summary and the agent-switch switch decide … commands, and asks you. It stays silent while agent-config is wired to this Agent Switch, so you never hear the same question twice, and it never holds up a prompt.

From the command line

Section titled “From the command line”
Terminal window
agent-switch limits --json                          # every account's limits, from cache
agent-switch switch list                            # open requests
agent-switch switch list --session claude/work/<id> --json   # with kind and summary
agent-switch switch request --session claude/work/<id>
agent-switch switch decide <id> approve --to claude/home --how after-turn
agent-switch switch decide <id> decline

The MCP server offers the same: limits_get (with burnPerHour and etaFull per window), session_whoami, switch_list (filter with session; each request has kind and summary), switch_status, switch_request, switch_decide and link_status (contract 1). switch_decide records your answer, so your agent asks you before calling it.