autolimit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 autolimit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,366 @@
+# autolimit
+
+`autolimit` is a terminal-agnostic PTY wrapper for interactive command-line runners.
+
+It was built for Claude Code style session-limit messages such as:
+
+```text
+You've hit your session limit · resets 7:40pm (Asia/Seoul)
+```
+
+When a configured limit message appears, `autolimit` parses the reset time. After that reset time plus a small grace period, it automatically sends the contents of `~/.config/autolimit/message.txt` to the still-running interactive session. If the same limit message is still on screen after the send (the session did not actually unblock), it retries a few times with backoff (60s / 120s / 240s). Time-of-day resets (`resets 7:40pm`, `resets 19:40`) and dated resets (`resets Jul 8 at 10:59am`) are both recognized.
+
+If the wrapped process exits after printing the limit message — or exits right after an auto-send, before the message could be processed — `autolimit` can run a runner-specific fallback command after the reset time. Built-in fallback profiles are included for `claude` and `cc`.
+
+## Installation
+
+From this project directory:
+
+```bash
+npm install
+```
+
+The install step creates:
+
+```text
+~/.config/autolimit/message.txt
+~/.config/autolimit/config.json
+~/.local/bin/autolimit -> <this package>/bin/autolimit.js
+```
+
+When installation runs in an interactive terminal, `autolimit` may ask whether
+you want to star the GitHub repository. Answering `y` uses an authenticated
+`gh` CLI session, or `GH_TOKEN` / `GITHUB_TOKEN`, to star
+`https://github.com/betive37/autolimit`. Set
+`AUTOLIMIT_GITHUB_STAR_PROMPT=0` to skip the prompt. With npm versions that run
+lifecycle scripts in the background, use `npm install --foreground-scripts` if
+you want to see and answer the prompt.
+
+If `autolimit` is not found after installation, add `~/.local/bin` to your shell PATH:
+
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Requirements:
+
+- Node.js 16+
+- Python 3.9+
+- macOS or Linux interactive terminal
+
+The Python runtime uses only the standard library.
+
+## Quick start
+
+Wrap `cc`:
+
+```bash
+autolimit --cc
+```
+
+Pass arguments to `cc`:
+
+```bash
+autolimit --cc --model sonnet
+```
+
+Wrap Claude Code directly:
+
+```bash
+autolimit --claude
+```
+
+Wrap any command:
+
+```bash
+autolimit -- npx some-runner --flag
+```
+
+or:
+
+```bash
+autolimit python3 my_repl.py
+```
+
+## Why `--cc` works
+
+The first non-wrapper argument of the form `--NAME` is interpreted as the command `NAME`.
+
+So this:
+
+```bash
+autolimit --cc --model sonnet
+```
+
+runs this inside the wrapper:
+
+```bash
+cc --model sonnet
+```
+
+Similarly:
+
+```bash
+autolimit --claude --dangerously-skip-permissions
+```
+
+runs:
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+## Shell aliases and functions
+
+By default, `autolimit` runs the target command through your interactive shell:
+
+```bash
+$SHELL -i -c '<command>'
+```
+
+This means shell aliases and functions usually work. For example, if your `.zshrc` contains:
+
+```bash
+alias cc='claude --dangerously-skip-permissions'
+```
+
+then:
+
+```bash
+autolimit --cc
+```
+
+uses that alias.
+
+If you want exact binary execution without shell alias expansion, put `--direct` before the runner selector:
+
+```bash
+autolimit --direct --cc
+```
+
+To force shell mode explicitly:
+
+```bash
+autolimit --shell --cc
+```
+
+## Message configuration
+
+Edit the message that gets sent after reset:
+
+```bash
+nano ~/.config/autolimit/message.txt
+```
+
+Default:
+
+```text
+이어서 계속 진행해줘.
+```
+
+You can override it per run:
+
+```bash
+AUTOLIMIT_MESSAGE='continue from where you left off' autolimit --cc
+```
+
+## Fallback after process exit
+
+Live auto-send works only while the wrapped process is still running.
+
+If the process exits after printing the limit message, `autolimit` uses a fallback profile if one is configured. The default `config.json` includes:
+
+```json
+{
+  "runners": {
+    "claude": {
+      "fallback": ["{runner}", "{args}", "-c", "-p", "{message}"]
+    },
+    "cc": {
+      "fallback": ["{runner}", "{args}", "-c", "-p", "{message}"]
+    }
+  }
+}
+```
+
+So `autolimit --cc --model sonnet` falls back to roughly:
+
+```bash
+cc --model sonnet -c -p '<message>'
+```
+
+The actual fallback is run through the same mode as the original invocation. In default shell mode, aliases and functions are respected.
+
+The fallback also covers two exit-time edge cases:
+
+- The process exits within ~10 seconds of a live auto-send: the message was probably never processed, so the fallback delivers it instead.
+- The live auto-send itself fails because the process is already gone.
+
+The wait before a fallback is capped by `max_fallback_wait_hours` (default 26). Press Ctrl-C during the wait to abort cleanly.
+
+If your original command already contains a positional prompt or `-p`, adjust the runner's fallback template so the resumed invocation stays valid (`{args}` re-inserts all original arguments).
+
+Disable fallback:
+
+```bash
+autolimit --no-fallback --cc
+```
+
+or:
+
+```bash
+AUTOLIMIT_DISABLE_FALLBACK=1 autolimit --cc
+```
+
+## Config file
+
+Default config path:
+
+```text
+~/.config/autolimit/config.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "message_file": "/Users/you/.config/autolimit/message.txt",
+  "log_file": "/Users/you/.config/autolimit/limit-watch.log",
+  "default_timezone": "Asia/Seoul",
+  "send_grace_seconds": 5,
+  "max_schedule_ahead_hours": 12,
+  "max_fallback_wait_hours": 26,
+  "patterns": [
+    {
+      "name": "Claude-style session limit",
+      "regex": "You[\\u2019']?ve\\s+hit\\s+your(?:\\s+[\\w-]+)?\\s+limit.{0,120}?resets\\s+(?P<hour>\\d{1,2})(?::(?P<minute>\\d{2}))?\\s*(?P<ampm>[aApP]\\.?[mM]\\.?)?\\s*\\((?P<tzname>[^)]{1,64})\\)"
+    },
+    {
+      "name": "Claude-style dated limit",
+      "regex": "You[\\u2019']?ve\\s+hit\\s+your(?:\\s+[\\w-]+)?\\s+limit.{0,120}?resets\\s+(?P<month>[A-Za-z]{3,9})\\.?\\s+(?P<day>\\d{1,2})(?:st|nd|rd|th)?,?\\s*(?:at\\s+)?(?P<hour>\\d{1,2})(?::(?P<minute>\\d{2}))?\\s*(?P<ampm>[aApP]\\.?[mM]\\.?)?\\s*\\((?P<tzname>[^)]{1,64})\\)"
+    }
+  ],
+  "runners": {
+    "claude": {
+      "fallback": ["{runner}", "{args}", "-c", "-p", "{message}"]
+    },
+    "cc": {
+      "fallback": ["{runner}", "{args}", "-c", "-p", "{message}"]
+    }
+  }
+}
+```
+
+Settings:
+
+- `send_grace_seconds`: extra seconds to wait after the parsed reset time before sending.
+- `max_schedule_ahead_hours`: a parsed reset time further ahead than this is treated as stale scrollback text and ignored (date-carrying patterns are allowed up to 8 days). This prevents an already-handled message from re-scheduling a next-day send.
+- `max_fallback_wait_hours`: upper bound on how long the post-exit fallback will wait for a reset.
+
+A `config.json` that still contains the v0.1 default pattern is upgraded to the current defaults automatically on the next run (custom patterns are left untouched).
+
+### Custom runner fallback
+
+Add a runner profile if a tool can resume non-interactively.
+
+```json
+{
+  "runners": {
+    "myrunner": {
+      "fallback": ["{runner}", "resume", "--message", "{message}"]
+    }
+  }
+}
+```
+
+Template tokens:
+
+- `{runner}`: the executable name, such as `cc`
+- `{args}`: all original arguments after the executable
+- `{command}`: the full original command list
+- `{message}`: the configured resume message
+
+For commands with complex spacing, prefer JSON array templates instead of string templates.
+
+### Custom limit patterns
+
+Patterns are Python regular expressions. A pattern must provide these captures, either by name or by positional group:
+
+- `hour`, required
+- `minute`, optional
+- `ampm`, optional; omit it to accept 24-hour clocks
+- `tzname`, optional; an IANA name (`Asia/Seoul`), a common abbreviation (`KST`, `PST`, ...), or an offset (`UTC+9`); unknown names fall back to `default_timezone` and are logged
+- `month` / `day`, optional named groups for date-carrying messages such as `resets Jul 8 at 10:59am`
+
+Named captures are recommended. Keep the gap between the anchor text and the time bounded (for example `.{0,120}?` instead of `.*?`) so unrelated output cannot bridge a match:
+
+```json
+{
+  "patterns": [
+    {
+      "name": "example",
+      "regex": "resets at (?P<hour>\\d{1,2}):(?P<minute>\\d{2})(?P<ampm>[ap]m) \\((?P<tzname>[^)]+)\\)"
+    }
+  ]
+}
+```
+
+## Utility commands
+
+Show help:
+
+```bash
+autolimit --help
+```
+
+Show resolved configuration:
+
+```bash
+autolimit --show-config
+```
+
+List fallback runner profiles:
+
+```bash
+autolimit --list-runners
+```
+
+Test the default parser:
+
+```bash
+autolimit --test-parser
+```
+
+Show how a command would be wrapped:
+
+```bash
+autolimit --dry-run --cc --model sonnet
+```
+
+## Logs
+
+Default log path:
+
+```text
+~/.config/autolimit/limit-watch.log
+```
+
+Follow logs:
+
+```bash
+tail -f ~/.config/autolimit/limit-watch.log
+```
+
+Disable logs:
+
+```bash
+AUTOLIMIT_LOG=0 autolimit --cc
+```
+
+## Notes
+
+`autolimit` does not bypass usage limits. It only waits until the reset time reported by the wrapped tool and then sends a configured message.
+
+The wrapper must start the process itself. It cannot attach to an already-running terminal process.

package/bin/autolimit.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const script = path.join(__dirname, '..', 'lib', 'autolimit.py');
+const args = process.argv.slice(2);
+
+function candidatePythons() {
+  const out = [];
+  if (process.env.AUTOLIMIT_PYTHON) out.push(process.env.AUTOLIMIT_PYTHON);
+  out.push('python3', 'python');
+  return [...new Set(out)];
+}
+
+// Probe before running: a Python 2 `python` would otherwise die with a
+// confusing SyntaxError instead of a version message.
+function pythonUsable(python) {
+  const probe = spawnSync(python, ['-c', 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else 3)'], {
+    stdio: 'ignore'
+  });
+  if (probe.error) return probe.error.code === 'ENOENT' ? 'missing' : 'error';
+  return probe.status === 0 ? 'ok' : 'too-old';
+}
+
+const skipped = [];
+for (const python of candidatePythons()) {
+  const usable = pythonUsable(python);
+  if (usable !== 'ok') {
+    skipped.push(`${python} (${usable})`);
+    continue;
+  }
+  const result = spawnSync(python, [script, ...args], { stdio: 'inherit' });
+  if (result.error) {
+    console.error(`[autolimit] Failed to run ${python}: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (typeof result.status === 'number') {
+    process.exit(result.status);
+  }
+  if (result.signal) {
+    console.error(`[autolimit] Python wrapper terminated by signal ${result.signal}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+console.error('[autolimit] Python 3.9+ is required, but no suitable interpreter was found.');
+if (skipped.length) console.error(`[autolimit] Tried: ${skipped.join(', ')}`);
+console.error('[autolimit] Set AUTOLIMIT_PYTHON to a Python 3.9+ executable to override.');
+process.exit(127);