timeout

Timeout - Break Reminder Plugin for Claude Code

A lightweight plugin that estimates task duration, automatically opens a timer, and reminds you to step away while Claude works. Reduce passive screen time during AI-assisted coding.

Install

claude plugin marketplace add timeout-plugin --source github --repo almandsky/timeout
claude plugin install timeout@timeout-plugin --scope user

Restart your Claude Code session to activate.

How It Works

1. You send a task — Claude estimates how long it will take. For prompts longer than a few words, you'll see a ⏰ [Timeout] system message reminding you that /break is available.
2. Auto timer — If the estimate is 3+ minutes, Claude opens a Google timer in your browser and starts working immediately. No confirmation needed.
3. Multi-step work — When Claude creates sub-tasks, you'll get a one-time reminder per prompt to step away while it plans.
4. Task reminders — While Claude works on a single task, you'll see ⏰ [Timeout] reminders every 3 minutes in your terminal.
5. Session reminders — After 30 and 60 minutes of continuous session time, you'll get a nudge to take a break.

Skills

Skill	Description
/break [minutes]	Manually open a break timer (default: 5 min)
/timeout-status	Show session stats
/timeout-settings	Configure the plugin

Configuration

Run /timeout-settings or edit ~/.timeout-plugin/config.json:

Setting	Default	Description
enabled	true	Enable/disable the plugin
reminder_thresholds_minutes	[30, 60]	Session duration reminders
default_break_minutes	5	Default break duration

Uninstall

claude plugin uninstall timeout@timeout-plugin
rm -rf ~/.timeout-plugin

Privacy

This plugin stores only timestamps and counters locally in ~/.timeout-plugin/. No conversation content, code, or personal data is collected or transmitted. See PRIVACY.md for details.