awewarm: Subscription Window Warmer

Keep AI coding-plan windows warm with one minimal request.

Connect once; awewarm detects what your Claude Code / Codex account or subscription endpoint can do, then makes sure the next usage window is always already open.

English · 简体中文

Connect once, then never think about 5-hour resets again: awewarm detects what it can do and only then keeps the next window open.

awewarm manages two kinds of connections:

• Account — your local claude / codex CLI logins. awewarm reuses their login state and sends one minimal headless request (Reply with exactly: ok). No credentials are stored.
• Subscription plan — any OpenAI Chat / OpenAI Responses / Anthropic-compatible endpoint with a base URL + API key. The key goes to the macOS Keychain, never to disk.

It schedules those requests in three modes — fixed, interval, and hybrid — explained in Scheduling Modes below. Interval-style renewal stays locked until the window semantics are verified or user-confirmed; fixed is always safe.

Install

Requires Python ≥ 3.9:

pip3 install awewarm

The background scheduler installs on macOS (launchd), Windows (Task Scheduler), and Linux (systemd user timer — loginctl enable-linger $USER first on headless/SSH accounts). Where systemd is unavailable, cron the tick: * * * * * awewarm run.

Windows note: there is no Keychain there, so API keys use ${ENV_VAR} references — persist them with setx AWEWARM_API_KEY_<PLAN> "..." (scheduler tasks inherit user env vars).

Quick Start

Let an AI agent set it up

Working in Claude Code, Codex, or another coding agent? Tell it:

Read https://github.com/wehuman01/awewarm/blob/main/README.ai.md and follow it to install and configure awewarm.

The agent installs the CLI, scans your local accounts (read-only), and tunes schedules on request. Onboarding itself (awewarm init, awewarm add plan) stays in your terminal — it prompts for choices and API keys. After setup you can ask things like "when is the next warm-up?" or "set claude-code to 06:35 and 12:35".

Manual setup

awewarm init        # scan local accounts, pick a schedule, install the scheduler
awewarm status      # see what will happen next

For a subscription endpoint instead:

awewarm add plan

You will be asked for the protocol, API base URL, API key, and model; awewarm tests the endpoint with one minimal request, then stores the key in the Keychain.

Companion Tools

awewarm is part of a small tool family for AI coding agents:

• aweswitch — agent profile switcher for Claude Code, Codex, and OpenCode. aweswitch manages which provider a session launches with; awewarm keeps that provider's subscription window open underneath. If you launch coding-plan profiles with aweswitch, awewarm is the piece that keeps those 5-hour windows from going cold overnight.
• aweskill — CLI skill package manager for AI agents (47+ agents).
• aweshelf — session bookmark manager for Claude Code and Codex.
• awerouter — smart LLM router: flash/pro split by structural signals.

Scheduling Modes

All modes send the same one minimal request — what differs is when it fires. Switch with awewarm enable <id> --mode fixed|interval|hybrid; see the current mode and next due moment with awewarm status.

fixed — absolute times, always safe

One request at each fixed local time (weekday or every-day); each hit opens a fresh window.

• If the machine was asleep at the slot time, the slot still fires late within the catch-up window (default 45 min); past that it is recorded as skipped.
• A slot landing within 30 min of a previous success is skipped — never pay for two windows at once.
• The only mode that works while window semantics are unknown, which is why unverified plans start here.

awewarm times claude-code 06:35 11:40 16:45   # 5 h + 5 min apart: windows chain across a workday
awewarm enable claude-code --mode fixed

Example — a laptop that sleeps at night: slots at 06:35 / 11:40 / 16:45 keep a window open from 06:35 to ~21:45 every weekday. The machine only needs to be awake within 45 min of each slot.

interval — rolling renewal

After each success the next request is scheduled window + grace later (default 300 min + 75 s, plus up to 30 s jitter). The grace runs after the old window has closed — firing earlier would land inside the old window and start nothing. With no success recorded yet, one request fires immediately as the first anchor.

awewarm verify my-plan --confirm                      # 1. one minimal request, timestamped
# ...watch when the plan's quota resets, note the elapsed minutes...
awewarm verify my-plan --duration 300 --user-confirm  # 2. record the window (unlocks interval)
awewarm enable my-plan --mode interval                # 3. rolling renewal

Example — an always-on machine you want warm around the clock, nights and weekends included. After 3 consecutive failures renewal pauses itself (status shows degraded) and resumes on the next success.

hybrid — fixed anchor + interval renewal (recommended)

Both engines run together: interval keeps the chain unbroken, while fixed slots re-anchor it at deterministic times — so each workday still starts where you expect even if the machine slept through the interval due. A slot within 30 min of a recent interval success is skipped automatically.

awewarm enable claude-code --mode hybrid   # window already verified at init
awewarm times claude-code 06:35            # one anchor per workday morning

Example — a verified account with a 06:35 weekday anchor: interval renews all day (renewal ignores the weekday rule and continues over the weekend), and Monday 06:35 re-anchors the chain no matter what happened overnight.

Config

Users never hand-edit config; init / add plan generate it at ~/.config/awewarm/config.json (state at ~/.local/state/awewarm/state.json). The shape, for reference:

{
  "version": 1,
  "connections": {
    "claude-code": {
      "kind": "account",
      "enabled": true,
      "transport": {"kind": "claude-cli", "cliCommand": "claude"},
      "window": {"status": "verified", "durationMinutes": 300},
      "schedule": {
        "mode": "hybrid",
        "fixed": {"at": ["06:35"], "days": "weekday", "catchUpWindowMinutes": 45},
        "interval": {"graceSeconds": 75, "jitterSeconds": 30}
      }
    }
  }
}

Commands

awewarm init                     # interactive onboarding
awewarm discover                 # read-only scan of local CLIs and logins
awewarm add plan                 # add a subscription endpoint
awewarm status                   # human-readable summary
awewarm run [--dry-run]          # one scheduler tick (the background scheduler calls this)
awewarm activate <id> --confirm  # send one real request now
awewarm verify <id> [--confirm] [--duration N --user-confirm]
awewarm anchor <id> --reset HH:MM    # window already open? anchor renewal past its close
awewarm enable <id> [--mode fixed|interval|hybrid]
awewarm times <id> [HH:MM...]  # show or set fixed times, e.g. 06:35 11:40 16:45
awewarm disable <id>
awewarm remove <id>
awewarm install / uninstall      # background scheduler (launchd / Task Scheduler / systemd)
awewarm inspect [<id>] [--json]  # redacted capability dump
awewarm config path              # config / state / log locations
awewarm self-update [--check]    # upgrade to the latest PyPI release

Self-Update

awewarm checks PyPI in the background — at most once a day, and never during scheduler ticks. When a newer release exists, interactive commands print a reminder to stderr.

awewarm self-update            # upgrade to the latest release
awewarm self-update --check    # show versions only

To disable the background check:

export AWEWARM_NO_UPDATE_CHECK=1

Support

If awewarm saves your quota, consider supporting it:

• ⭐ Star the repo — it helps others find it.
• ☕ Ko-fi — buy me a coffee.

Development

pip install -e .
python3 -m unittest discover -s tests

See docs/CONTRIBUTING.md for the engineering doctrine and docs/CHANGELOG.md for release history.