Claude Timeout Resume ☕

Claude needs a nap. You shouldn't have to babysit the clock.

You're deep in the flow, and then:

You've hit your session limit · resets 1:40am

Cool. Cool cool cool. So now you either sit there refreshing, or you wander off and forget all about it until tomorrow afternoon.

This little extension just... handles it. It notices the limit, quietly counts down, and a little after the clock runs out it wakes your session back up and carries on. Go make tea. Go outside. Sleep. It'll be waiting for you, already working.

How it feels

1. Claude taps out.
2. Your status bar picks up the vibe: 🕐 Claude resumes in 4h 32m
3. You go live your life.
4. A while after the limit lifts, your session picks up right where you left off — in the same terminal you were already sitting in.

That's the whole thing. No setup, no config, no ceremony.

Why "a while after"?

Because everyone's cooldown ends on the same round minute, and coming back at exactly 1:40:00am alongside everyone else is a bit conspicuous. So it waits a random 5-30 minutes past the reset before waking anything up. You'll see it in the countdown. Don't like it? claudeTimeout.randomDelayMaxMinutes: 0 and it resumes the second the clock runs out.

The chime

The other half of not babysitting: knowing when Claude wants you.

You wander off while it works, and it hits a permission prompt — Do you want to proceed? — and then just sits there. Politely. For twenty minutes. Or it finishes the whole job and waits at the input box while you're in another window.

Now it makes a noise. That's it. A small sound the moment Claude stops working and starts waiting, whether it's a permission prompt or a finished turn.

If that turns out to be more annoying than useful — and it might! — it's one command away from silence: Mute the "Claude needs you" Sound, or the same entry in the status menu, or the Mute Sound button on the notification. You can also keep just the permission prompts and drop the turn-end ones (claudeTimeout.soundOnTurnEnd: false), or swap the sound for your own file (claudeTimeout.soundFile).

The other kind of stuck

Sometimes Claude isn't out of quota — it's just busy:

API Error: 529 Overloaded. This is a server-side issue, usually temporary.

You hit enter again. Four minutes of spinner. Same error. Retype the whole prompt. Same error. Eventually you open a new terminal, run claude there, and it goes through first time — which is a slightly absurd thing to have to discover on your own.

So now it does that for you:

1. Waits about a minute and re-sends the prompt the error swallowed — pulled back out of Claude Code's own session file, so you never retype it.
2. Still failing? It stops flogging that session and starts a fresh one with claude --continue, in the same folder, carrying the conversation and your prompt with it. This is the bit that actually works.
3. Still failing after that? It stops and tells you, rather than hammering a server that's clearly having a rough day.

Sitting there looking busy with no error at all? Ctrl+Shift+P → Start New Claude Session. Same trick, on demand.

Getting it

Install, reload the window, and forget it exists. It stays completely invisible until there's actually something to tell you.

The five buttons you might ever want

Hit Ctrl+Shift+P and type "Claude Timeout":

• Show Status — how long's left, and a big friendly Resume Now if you're impatient. (Or just click the countdown in the status bar.)
• Start New Claude Session — for when it's wedged. New terminal, fresh session, your last prompt already in it.
• Set Resume Timer — do it by hand. Understands 5h, 90m, at 15:30, whatever. Set by hand means exactly on time, no random delay.
• Cancel Pending Resume — changed your mind. No hard feelings.
• Mute/Unmute the "Claude needs you" Sound — self-explanatory. There's also Play the Alert Sound if you want to hear it first.

Good to know

• 🌙 Close your laptop. Sleep, hibernate, restart VS Code — the countdown keeps its own time and survives all of it. If the limit lifted while you were away, it just picks up when you come back.
• 👀 It watches quietly. It reads Claude Code's own session files, so it works even when you run Claude in a terminal outside VS Code.
• 🤝 It won't nag. One notification when the limit hits, one when you're back.
• ✋ You're always in charge. Turn off auto-resume and it'll just tap you on the shoulder instead: claudeTimeout.autoResume.

Want to tinker?

There are knobs — which command to run, what prompt to send, how long to wait after the reset, which folder to resume in. All under claudeTimeout.* in settings.

Full details live in DOCS.md next to the extension, if you're into that. Most people never need to open it.

What's new in 0.3.0

It doesn't come back at the same second as everybody else, it makes a noise when Claude needs you, and there's a Sponsor button on the extension page if any of this has saved you an afternoon. ☕

The random 5-30 minute delay applies to detected cooldowns only, the sound is one click from muted, and the sponsoring is — obviously — entirely optional.

What's new in 0.2.0

It handles "Overloaded", not just "out of quota".

A 529 isn't a cooldown — waiting five hours for it is wrong, and so is retrying the same session forever. It now retries on a short backoff, escalates to a brand-new session when that session is clearly cursed, and re-sends the prompt the error ate instead of a generic "continue". Turn the whole thing off with claudeTimeout.retryOnOverload if you'd rather drive.

What was fixed in 0.1.1

It now wakes up the terminal you were actually working in.

Before, when the clock ran out you'd get a brand-new terminal off to the side while your real session sat exactly where you left it — still waiting on you to press Enter. Which rather defeats the point of the whole extension.

Three things changed:

• Resuming happens in the terminal that hit the limit, not a fresh one. That's the new default (claudeTimeout.resumeTarget). Set it back to newTerminal if you liked the old way.
• The terminal no longer gets forgotten. A limit gets spotted twice — once in your terminal, once in Claude's own session files — and only the first knows which terminal it happened in. Whichever showed up second was being thrown away, so half the time that detail vanished and you'd get a new terminal anyway. Now the second sighting fills in what the first was missing.
• When it genuinely can't tell, it types into your active terminal instead of giving up and opening a new one.

If the old terminal is really gone — you closed it, the process died — it still falls back to opening a fresh one. Nothing to configure either way.

Like it?

There's a Sponsor button next to my name up on the extension page, or Ctrl+Shift+P → Claude Timeout: Sponsor This Extension. Entirely optional, genuinely appreciated. Bug reports and "it didn't catch this message" reports are worth just as much — the parsers only know the wordings people have shown them.

Made for anyone who's ever stared at a five-hour countdown. Peace. ☮️