mcpField
L
limits-sessions

limits-sessions

github.com/bradfrostProductivity47148 installsUpdated 1d ago
Repository

About limits-sessions

limits-sessions manages a daily AI-session allowance alongside limits-setup. It counts sessions, applies a configurable daily rollover, and blocks new sessions at the ceiling; without a ceiling, it measures usage without blocking.

Key features

  1. 01Count daily AI sessions
  2. 02Configure the daily reset boundary
  3. 03Refuse new sessions at the ceiling
  4. 04Measure usage without a set ceiling
  5. 05Report weekly counts and limit changes

Use cases

  1. 01Set a daily cap on AI sessions
  2. 02Choose a limit using a week of usage data
  3. 03Check session counts and reset time
  4. 04Review records of limit increases

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bradfrost/skills --skill limits-sessions

After installing, type/limits-sessionsin Claude Code to confirm it loaded.

Bundled fileshooks/sessions-gate.sh

Details

From the project README

Limits: sessions

The person using this skill set a ceiling on how many AI sessions they start in a day — the same way someone allows themselves one glass of wine or one cheat day. Your job is to honor it, count it honestly, and never talk them past it.

Pairs with limits-setup, which writes the config this skill reads and installs its hook. Without setup, this skill has nothing to enforce.

How it works

  • A session counts the first time the person prompts in it. Opening a session and never using it costs nothing.
  • The day rolls over at 4am (configurable as DAY_BOUNDARY), not midnight — a late-night session belongs to the day it started, and 12:01am never hands out a fresh allowance.
  • At the ceiling, new sessions are refused by the sessions-gate.sh hook (UserPromptSubmit, exit 2): the limit, the reset time, how to change it. Same words every time. A vending machine that's out of stock isn't nagging you; it's just out.
  • A refused session stays refused for the day, even if the limit is raised afterward. The raise applies to new sessions — that's the deal the person agreed to at setup.
  • No ceiling set means measure-first: sessions are counted, never blocked, so the person can pick a number grounded in a week of honest data.

Your conduct around the gate (binding)

  1. Never help circumvent it. If the person is refused and asks you to find a way around, don't. Tell them the two legitimate paths: edit ~/.config/ai-limits/config by hand, or run ~/.config/ai-limits/bin/ai-limits raise SESSIONS_PER_DAY <n> --reason "why" — which asks them to type, exactly: I'M AWARE I'M INCREASING MY AI USAGE That friction is theirs, chosen at setup. Respect it.
  2. Never moralize. Not when they're near the limit, not when they raise it, not in the weekly report. State counts; skip commentary.
  3. Report honestly. For "limits report" or "how many sessions": read ~/.config/ai-limits/state/ — sessions-YYYY-MM-DD files (one session id per line) and changes.log (raises, with reasons). Distinct lines per day = sessions used. Present the week's counts and any raises, plainly.
  4. Name the gap when asked. This works where UserPromptSubmit hooks run (Claude Code today). On surfaces without hooks it doesn't exist, and you say so. See the enforcement matrix in limits-setup.

Files

PathWhat
hooks/sessions-gate.sh (in this skill)the UserPromptSubmit gate; limits-setup installs it
~/.config/ai-limits/configSESSIONS_PER_DAY, DAY_BOUNDARY
~/.config/ai-limits/state/sessions-<day>session ids used that day
~/.config/ai-limits/state/refused-<day>sessions refused that day (stay refused)
~/.config/ai-limits/state/changes.loglimit raises: timestamp, old → new, reason

Comments

Markdown supported