Keeping an idle session warm

Keeping an idle Claude Code session's cache warm

Describes robot-council/cli v0.4.28.

An idle session's prompt cache expires, and the first turn after that pays to write the whole conversation again. For a fleet session idle between tasks, that cost lands on the first turn of the next task. --keep-warm=<minutes> has the bridge wake its own session once it has been idle that long, with a channel notice saying there is nothing to do, so the woken turn is short and hits the cache (#279). Off by default.

claude mcp add -s user robot-council \
  -e ROBOT_COUNCIL_SERVICE=https://your-fleet.example.com \
  -e ROBOT_COUNCIL_HARNESS=claude \
  -- robot-council mcp --keep-warm=55 --keep-warm-for=480

Set the interval from your cache's TTL; the bridge does not detect it. Claude Code's prompt caching documentation gives the main conversation a one-hour TTL on a Claude subscription within its included usage, and five minutes on an API key, a cloud provider, or a subscription drawing on usage credits; CLAUDE_CODE_PROMPT_CACHE_TTL sets it to 5m or 1h. For one hour, 55 minutes leaves room for a slow turn. On a five-minute TTL the option buys nothing at any practical interval. It would take a woken turn every four minutes for as long as the session sits idle, and by the pricing each reads the whole cache at a tenth of the input price, so an idle hour of them costs about what the one rewrite they prevent does, before counting what each woken turn writes.

--keep-warm-for=<minutes> is the ceiling. Once the session has been idle that long, keep-alives stop, so a seat abandoned overnight is not woken every hour until morning. Without it they go on for as long as the bridge runs. It has to be longer than the interval, or no keep-alive could ever be sent. A value that is not a whole number of minutes, a ceiling no longer than the interval, or --keep-warm given to any harness but Claude Code is reported on stderr, and the bridge runs without keep-alives.

What counts as activity, and what the bridge cannot see. The bridge sees no turns (#211 records why), so it reads three things that stand in for them: a tool call arriving, a notice it sent about fleet events, and a turn end the stop hook recorded. Under Claude Code, robot-council pending records the time it drains the sink, in a file beside the sink; --peek does not, and neither does any other harness's hook. So:

• It needs the stop hook, and Claude Code started with channels, as waking a seat describes. Without channels, the notice is dropped and nothing is kept warm.
• A long turn that calls no fleet tool looks idle until it ends, hook or no hook: running Bash and editing files moves nothing the bridge reads. So a turn longer than the interval can receive a keep-alive while it runs. The server instructions tell the agent to ignore one that arrives mid-task and carry on, and the turn folds it in. Without the hook, every turn is like this.
• A keep-alive's own turn end is not activity, or the ceiling could never arrive: the first turn end within two minutes of a keep-alive is taken as that keep-alive's. A tool call in between means the agent did something, and the turn end after it counts. The cost is the case above: a real turn that folded a keep-alive in, and ended within two minutes of it without calling a fleet tool, is taken for the keep-alive's, and the ceiling arrives that much early.
• A continued turn's end is not recorded. The script's loop guard exits before pending runs when Claude Code has already continued the turn, so the clock runs from the first end, and a long continuation can be followed by a keep-alive sooner than the interval.
• The record has the sink's identity: the service, the harness, and the project or the checkout. Two Claude Code sessions in one checkout share one record, as they share one sink.

What the woken turn does has not been measured yet. The server instructions tell the agent that a notice carrying keep_warm has nothing behind it, and to end the turn without tool calls unless it is in the middle of a task; whether a live session does, and that the cache stays warm, are open on #279.