From setup-claude-token-optimiser
Interactive setup of a cron-based heartbeat to straddle Claude's 5-hour token windows, doubling budget in short or spread-out work days. Includes macOS sleep management.
How this skill is triggered — by the user, by Claude, or both
Slash command
/setup-claude-token-optimiser:setup-claude-token-optimiserThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Sets up a scheduled "kick" that opens Claude usage windows on a clock, so a developer who spreads
Sets up a scheduled "kick" that opens Claude usage windows on a clock, so a developer who spreads their work out across the day can straddle window resets and access extra token budget. This is an interactive setup: explain the mechanic, ask questions, then install.
macOS-focused (cron + pmset/launchd). The kick+cron logic is portable to Linux, but the sleep
section is macOS-only — on Linux, note that and skip it (or suggest a systemd timer with
Persistent=true).
How it works. Claude meters usage in a rolling 5-hour window: the window opens on your first message and grants a fixed token budget B; it closes exactly 5h later regardless of use, and the next message opens a fresh window with a fresh B.
A tiny scheduled "kick" (a one-word
"Hi"to headless Claude, costing ~nothing) opens a window on a fixed clock, before you start work. So when you begin, you're already partway through a window — and it resets in the middle of your session, opening a second window. One work session then spans two windows → up to 2× the budget (2B).The sweet spot is the reset landing roughly mid-session (so you can actually burn budget on both sides). The kicks are spaced ~5h05m apart to tile your day with back-to-back windows.
Then state, clearly, when it helps and when it doesn't:
B, it changes nothing (just costs the trivial kick).It is most valuable for someone who takes long breaks and spreads their hours — that is the explicit assumption.
AskUserQuestion)Ask these (combine into one AskUserQuestion call where sensible):
cron does NOT run jobs while the Mac is asleep
and never catches up. To guarantee the kicks fire, the Mac must stay awake. I can set up
state-aware sleep disabling (an offsleep/onsleep pair + a boot daemon that restores your
choice). This keeps the laptop awake 24/7 — best on AC power." Options: Yes, set up sleep
control / No, cron only (accept missed kicks while asleep).Then ask, in plain prose (free-form answers are fine):
If the user picked the ">5h continuous block" pattern, do not pretend it helps — confirm whether they still want a minimal kick (e.g. one or two/day just to keep a window primed) or to abort.
The kick runs headless, so it needs a Claude Code OAuth token at ~/.ssh/claude-token.
~/.ssh/claude-token exists and is non-empty, use it.claude setup-token, then save the printed token:
printf '%s' '<token>' > ~/.ssh/claude-token && chmod 600 ~/.ssh/claude-token. This is the
user's action (it prints a secret) — give them the commands; don't capture the token yourself.Resolve the Claude binary path: command -v claude (cron has a minimal PATH, so the script MUST
use the absolute path). Create ~/.claude/token-optimiser/kick-claude.sh with this content,
substituting __CLAUDE_BIN__ with the resolved path:
#!/bin/bash
ts() { date '+%Y-%m-%dT%H:%M:%S%z'; }
token=$(cat ~/.ssh/claude-token 2>/dev/null) || {
echo "=== $(ts) kick FAILED: cannot read ~/.ssh/claude-token ==="
exit 1
}
export CLAUDE_CODE_OAUTH_TOKEN="$token"
echo "=== $(ts) kick start ==="
echo "Hi" | __CLAUDE_BIN__ -p --model claude-haiku-4-5 --disallowedTools "*"
status=$?
echo "=== $(ts) kick end (exit $status) ==="
exit $status
mkdir -p ~/.claude/token-optimiser && chmod +x the script. bash -n it.
Compute the kick times with the bundled helper (it places the first window --lead minutes — 180
by default — before the first start so the first reset lands ~2h in, then tiles every 5h05m):
python3 <this-skill-dir>/scripts/compute_schedule.py \
--first-start <HH:MM> --last-end <HH:MM> \
--script "$HOME/.claude/token-optimiser/kick-claude.sh" \
--log "$HOME/.claude/token-optimiser/kick-claude.log"
Use the absolute $HOME-expanded paths (cron runs via /bin/sh, which expands $HOME, but
absolute is safest — substitute the real home). Show the user the computed times and confirm.
Then update the crontab non-interactively (no editor, no sudo) — strip any prior kick lines first so re-runs don't duplicate:
( crontab -l 2>/dev/null | grep -v 'token-optimiser/kick-claude.sh' ; \
<the cron lines, without the comment lines> ) | crontab -
Verify with crontab -l | grep kick-claude.
Create three things. Substitute __HOME__ with the absolute home path (the daemon runs as root,
so $HOME would be root's home — paths MUST be absolute).
a) State-aware functions in the user's shell profile (~/.zshrc if $SHELL is zsh, else
~/.bash_profile). Add only if not already present:
CLAUDE_SLEEP_STATE="$HOME/.claude/token-optimiser/sleep-disabled"
offsleep() { sudo pmset -a disablesleep 1 || return 1; mkdir -p "$(dirname "$CLAUDE_SLEEP_STATE")"; echo 1 > "$CLAUDE_SLEEP_STATE"; }
onsleep() { sudo pmset -a disablesleep 0 || return 1; mkdir -p "$(dirname "$CLAUDE_SLEEP_STATE")"; echo 0 > "$CLAUDE_SLEEP_STATE"; }
b) Boot apply-script at ~/.claude/token-optimiser/apply-sleep-state.sh (chmod +x, bash -n):
#!/bin/bash
ts() { date '+%Y-%m-%dT%H:%M:%S%z'; }
state_file="__HOME__/.claude/token-optimiser/sleep-disabled"
want=0
[ -r "$state_file" ] && want="$(cat "$state_file" 2>/dev/null)"
if [ "$want" = "1" ]; then
/usr/bin/pmset -a disablesleep 1 && echo "=== $(ts) boot: re-applied disablesleep 1 ==="
else
/usr/bin/pmset -a disablesleep 0 && echo "=== $(ts) boot: disablesleep 0 ==="
fi
c) LaunchDaemon plist at ~/.claude/token-optimiser/local.claude-token-optimiser.sleep.plist
(validate with plutil -lint):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>local.claude-token-optimiser.sleep</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>__HOME__/.claude/token-optimiser/apply-sleep-state.sh</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StandardOutPath</key>
<string>__HOME__/.claude/token-optimiser/apply-sleep-state.log</string>
<key>StandardErrorPath</key>
<string>__HOME__/.claude/token-optimiser/apply-sleep-state.log</string>
</dict>
</plist>
Seed the state to match the user's intent (they're opting in, so 1):
mkdir -p ~/.claude/token-optimiser && echo 1 > ~/.claude/token-optimiser/sleep-disabled.
Then hand the user the sudo install block to run themselves (this needs root — do NOT try to run sudo yourself; present it and let them paste it):
sudo cp __HOME__/.claude/token-optimiser/local.claude-token-optimiser.sleep.plist /Library/LaunchDaemons/ \
&& sudo chown root:wheel /Library/LaunchDaemons/local.claude-token-optimiser.sleep.plist \
&& sudo chmod 644 /Library/LaunchDaemons/local.claude-token-optimiser.sleep.plist \
&& sudo launchctl bootstrap system /Library/LaunchDaemons/local.claude-token-optimiser.sleep.plist
Tell them: bootstrap loads it now and RunAtLoad fires it immediately; if they ever re-run the
block and see Bootstrap failed: 5: Input/output error, that just means it's already loaded
(harmless). Then source their profile so offsleep/onsleep are live, and run offsleep
once to actually disable sleep now.
crontab -l | grep kick-claude → the new lines.tail ~/.claude/token-optimiser/kick-claude.log
→ a kick end (exit 0) line.cat ~/.claude/token-optimiser/apply-sleep-state.log (boot line) and
pmset -g | grep SleepDisabled (→ 1 after offsleep).Summarise what was installed, the chosen kick times, and restate the caveat: this pays off only when they spread work / take long breaks / do ≤5h days, and never for one continuous >5h block.
To uninstall later: remove the kick lines from crontab -e, and
sudo launchctl bootout system/local.claude-token-optimiser.sleep && sudo rm /Library/LaunchDaemons/local.claude-token-optimiser.sleep.plist.
sudo yourself — hand sudo commands to the user.npx claudepluginhub samthebest/dump --plugin setup-claude-token-optimiserAudits Claude Code or Codex setup for context window waste, recovers 5–25% via config cleanup and compaction.
This skill should be used when the user asks to "fix claude code", "fix claude", "optimize claude", "improve claude performance", "fix my settings", "setup claude code", "configure claude code", "claude code settings", "tune claude", "fixclaude", "claude is broken", "claude is slow", "claude is lazy", "claude is not working", "make claude better", "keep session alive", "session timer", "rate limit", "avoid rate limits", "rate limited", "fix claude code settings", or wants to optimize their Claude Code installation for maximum performance. Provides an interactive wizard walking through performance settings, rate limit optimization via session timer bump, and optional plugin improvements step by step.
Manages scheduled Claude Code tasks: add recurring/one-off skills/prompts/scripts, list/pause/resume/remove, view results/logs, test execution with safety controls and notifications. Cross-platform (macOS/Linux/Windows).