ccauto

Continuity and account automation for Claude Code sessions running in VS Code terminals. macOS only.

Two independent managers, both off until you turn them on:

• Context Manager keeps a long session going unattended. When a terminal session passes a context mark, ccauto asks it to write a handoff brief, then types /clear, restores the tab's colour and resumes from the brief, all in the same tab.
• Usage Manager keeps work flowing across several Claude accounts. It polls every saved account's five-hour and weekly usage with reset times, shows them in the status bar, and when the active account nears its limit it switches the machine's active Claude Code login in place, so every running session follows within about 30 seconds.

Requirements

• macOS. ccauto stores credentials in the login Keychain through the system security tool.
• Claude Code >=2.1.270 <2.2.0 installed and signed in. ccauto refuses to run outside that range until its assumptions have been re-verified, and says so in the status bar.
• Claude Code running as the CLI inside VS Code's integrated terminal. The Claude Code side panel and Terminal.app sessions are not driven by the Context Manager; the Usage Manager's account switch still applies to them, because it is machine-wide.
• A Claude subscription per account (usage figures come from the account's OAuth login).
• A local VS Code window. In a Remote-SSH, WSL or Codespaces window ccauto runs on your Mac (it needs the Keychain) while the terminals are remote, so it shows sessions but cannot drive them.

For your team: setup in five minutes

1. Install ccauto from the Extensions view (or code --install-extension ccauto-0.3.1.vsix from a release file). No reload needed on a fresh install.
2. Look at the bottom-right status bar: ctx off and usage off · <you>. Your current Claude Code login is imported as the first account automatically.
3. Click either item for the ccauto menu → Add Account. A terminal opens and runs the Claude sign-in; complete it in the browser as the extra account, then give the account a short name when asked. Repeat per extra account.
4. From the same menu, Refresh Usage, then hover the status bar item to see every account's numbers.
5. Turn on what you want from the menu: Turn Usage Manager on and/or Turn Context Manager on. Defaults: switch away at 90 % five-hour usage; context mark at 80 %.

Things to know before enabling:

• The account switch is machine-wide: every Claude Code process on the Mac follows it. Do not share a machine's login with someone else's sessions.
• The Context Manager types into your terminals. It only ever types into a session that is idle at its prompt, only in the VS Code window that holds the leader lock, and only three lines: the handoff request, /clear (plus /color), and the resume request. ccauto: Show Log records every keystroke it sends.
• If VS Code shows ctx n/a, the self-check failed; the menu's Show Log says why.

The status bar

The usage item is rendered from usage.statusFormat in the config. Default:

$(robot) {account} $(ccauto-five) {fiveHour}% | {fiveHourReset}  $(ccauto-week) {weekly}% | {weeklyReset}

Placeholders: {account} (the account's name), {email}, {fiveHour}, {weekly} (percent), {fiveHourReset}, {weeklyReset} (countdowns), {fiveHourResetAt}, {weeklyResetAt} (local clock time), and one pair per model-scoped limit your plan reports, such as {fable} and {fableReset}. Icons are $(name) codicons from https://microsoft.github.io/vscode-codicons/dist/codicon.html plus ccauto's own $(ccauto-five) and $(ccauto-week). The non-breaking space before $(ccauto-week) keeps the two windows apart; VS Code collapses ordinary runs of spaces.

Countdowns show one unit (3d, 5h, 23m); with "preciseResetTimers": true they show two (3d 4h, 4h 23m), never seconds. A leading $(circle-slash) means the manager is off but still polling; $(debug-pause) means every account is over its limit. Hover for a table of all accounts.

Config (~/.ccauto/config.json)

Written with defaults on first run and reloaded live when saved. Open it from the menu.

Switch rule: leave the active account at the five-hour or weekly threshold, or when a model-scoped limit (for example the weekly Fable cap) is at the weekly threshold for a model one of your sessions is running; go to the account with the soonest weekly reset among those under the prefer threshold; else the lowest five-hour usage under the away threshold; else pause until a reset and say so in the status bar. An account with no room on a model a session is using, or over the weekly cap, is never chosen.

Where things live

• ~/.ccauto/ — config, state, log, handoff briefs, accounts.json (emails and names, no secrets).
• Login Keychain — one ccauto:<email> item per saved account, plus Claude Code's own Claude Code-credentials item, which ccauto rewrites on a switch and never refreshes itself.
• ~/.claude/sessions/ and the session transcripts — read only, to know which sessions exist and how full they are.

Nothing leaves the machine except the calls Claude Code itself makes: usage is read from Anthropic's OAuth usage endpoint with each account's own token.

Troubleshooting

• claude CLI not found on PATH on a VS Code started from the Dock: fixed in 0.1.1; update.
• Nothing is typed although a session is over the mark: the log shows not typing … skipped:<reason>. no-terminal means the session is in another VS Code window; only the leader window types, and only into its own terminals. busy means the session was mid-turn; it is retried when idle.
• another window is the leader: run switches from the window whose log says became leader, or close the other window.
• A session is flagged ($(alert) on the context item) after repeated failed handoffs: fix the session by hand, then Clear Session Flag from the menu.

Development

npm install, then npm run typecheck && npm test (unit), npm run test:vscode (extension host), npm run package (vsix), npm run icons (rebuilds the glyph font from scripts/make-icons.mjs). Design notes are under docs/superpowers/; publishing steps in docs/publishing.md.

Logs

ccauto: Show Log or ~/.ccauto/ccauto.log.