Agent fallbacks

A bot runs on one agent, such as Claude Code. When that agent can't answer, because its usage ran out, it's rate limited or overloaded, it's signed out, or it won't start, the bot can carry on with the next agent in its list. The new agent continues the same turn in the same chat, with the bot's memory, workspace and tools. The bot goes back to its own agent once that one recovers.

Each fallback is another agent (for example Claude Code, then Codex, then Gemini CLI). To fall back between one agent's own models, set that in the agent itself (for example Claude Code's fallbackModel).

A bot has no fallbacks until you add them.

Set up fallbacks

Fallbacks live in the bot's Agent card, below its expandable settings:

  • Desktop app: click the bot's name at the top of the chat. The Settings tab shows the Agent card.
  • iPhone: tap the bot's name at the top of the chat. The Settings tab shows the Agent card.
  • Terminal UI: press e on the bot and go to the Fallbacks field.

In the desktop, iPhone and Android apps:

  1. Next to Fallbacks, press +. A new row appears under the list, already open on its pickers.
  2. Pick the agent and its model right there, the same way as the bot's own agent. Tap a row's summary any time to change its agent, model or login profile; it keeps its place.
  3. Add up to three. Use each row's ⋯ menu to Move up, Move down or Remove.

Each agent can appear once on each of its login profiles: an agent with more than one login profile can be a fallback again on another of them, the bot's own agent included, and its row then asks which login profile. An agent with one login appears once, and the bot's own isn't offered. The info button next to Fallbacks explains the feature.

In the terminal UI, ←/→ picks a fallback, space adds the next free agent or changes a fallback's model, a changes its agent, c changes its login profile, [ and ] move it, and x removes it.

Everything else stays the bot's own whichever agent is answering: its folder, approvals, connectors, skills, computer use and memory, and Fast mode where the fallback's agent has it. With Auto under Permissions, each agent works in its own Auto mode. A fallback without the bot's mode (Claude Code's Plan, say) works in its own closest mode that is no less careful, such as Codex's Read-only, and the chat says which. A fallback with no mode that careful, or one that won't switch to it, doesn't take the turn: the next one does.

Note: A fallback that runs on an API key instead of a subscription costs money with that provider.

When a bot moves on

Codync moves on only when the agent returns an error that says it can't answer. The agents retry on their own first, so Codync doesn't ask the same agent again. Each agent is tried at most once per turn.

The agent it leaves then rests: every bot on the computer skips it for a while, so one bot finding Claude Code out of usage spares the others from trying. A bot on another login profile rests only that login profile: bots on the default one carry on, and the other way round.

The chat says the agent…Bots skip it until
reached its usage limitthe reset time the agent reported (an hour if it gave none)
is out of credits6 hours have passed
is rate limited, or is overloaded1, 5, 25, then 60 minutes, growing with failures in a row
is signed outit's signed in again (Codync also looks again after an hour, or after 10 minutes for an agent it doesn't know by name)
couldn't start5 minutes have passed
doesn't have this bot's modelyou change the bot's settings (this one is about the bot's setup, so only this bot skips that step)
doesn't have this bot's modeyou change the bot's settings (likewise only this bot)

A rest also ends early when any turn on that agent finishes normally. Switch back ends the rest of the bot's own agent.

These don't move a bot on: you stopping it, the agent refusing, output or step limits, a routine's time limit, or the agent compacting a full context.

Codex currently reports its rate limits and overloads as ordinary reply text, so for Codex only a usage limit moves the bot on. For Pi, a model request its provider turned down as busy (HTTP 5xx) or rate limited (HTTP 429) moves the bot on; any other error Pi ends a turn in shows as a notice in the chat.

What the next agent knows

When a fallback takes a turn over, it hears what it needs before the turn's messages:

  • If it hasn't worked in this chat before: a recap of the conversation (the latest summary, the most recent messages and any open plan; once that agent has worked in this bot, also what you said before them), with a list of the files the agents before it changed, the commands they ran and the dev servers still running.
  • If it has: a catch-up of what was said since it last answered, with the same list for what the other agents did meanwhile. Each agent keeps its own session, so coming back resumes it.
  • If agents already failed during this turn: which one stopped and why, what each of them did (tool calls, messages, last note), and a reminder to check what's done before redoing any step.

Once Codync knows the agent's context window, the recap takes at most a tenth of it (about 20,000 tokens at most). It lists file paths and command lines, not their contents, so the agent reads a file again before changing it. Rules you want every agent to follow belong in the bot's memory, which each agent gets in full.

New session (in the bot's menu) clears every agent's session, and none of them is told what was said before.

What the chat shows

  • A switch: one line where another agent took over, such as "Claude Code reached its usage limit (resets in 2 h). Codex carried on." Click or tap it to see what the new agent was told. In the terminal UI it's a ↪ line; press o to unfold it.
  • The way back: "Back on Claude Code."
  • A signed-out agent: moving past one also posts that agent's sign-in card. Its Sign in button opens the agent's sign-in sheet; once you're signed in, the bot goes back to that agent on its next message.
  • Every agent failed: a failure notice says how each one is, for example "No agent in this bot's list could answer: Claude Code reached its usage limit (resets in 2 h); Codex …". If one of them was signed out, the turn's messages wait on its sign-in card and go out again once you sign in (messages older than 24 hours aren't resent).
  • No fallbacks yet: when a bot without fallbacks stops because its agent ran out of usage, was rate limited or was overloaded, the notice offers Add a fallback, which opens the Agent card in the bot's Settings. In the terminal UI, pick the notice and press A.
  • Background work: a thread falls back the same way. Its sign-in card and its Add a fallback notice appear in the bot's chat, with the line In the background · and the thread's title; its own steps just say it asked there. A thread that can't go on until you sign in waits for you instead of failing, and carries on once you have.

The Agent card shows the state too. While the bot is on a fallback, its first row reads, for example, "Using Codex until Claude Code resets at 3:00 PM" when Claude Code reached its usage limit, or "Using Codex while Claude Code is signed out" for another reason, with Switch back. The fallback in use is marked In use, and a resting agent shows "Usage resets 3:00 PM" or "Resting until 3:00 PM". These lines follow the app's language. In the terminal UI, the bot's settings (e) show the agent in use while it is on a fallback, and the chain in the Fallbacks field.

Going back

Each turn starts on the first agent in the bot's list that isn't resting. So the bot returns to its own agent on its first turn after the reset, never in the middle of a turn. After you sign in to a signed-out agent, it returns on its next message.

To go back right away, press Switch back in the Agent card (b on the Agent field of the bot's settings in the terminal UI). It ends the rest of the bot's own agent and, if the bot is idle, moves it back now.

Let the bot set its own fallbacks

You can ask a bot to set up its own chain, for example "if you run out of usage, carry on with Codex". It can see which agents are on the computer, whether each is signed in or resting, and their models, and it replaces its list with the one you asked for. A notice in its chat records each change, such as "Fallbacks set: Codex · gpt-5.5, Gemini CLI" or "Fallbacks removed".

The switch Let the bot change its fallbacks, under the list, controls this. It's on by default. In the terminal UI it's the Bot edits field.

A bot that manages the team can change any bot's fallbacks, and its own only while this switch is on. Either way, bots set agents and models only.