agent-auto-resume 0.1.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,65 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best for the overall community, not just the individual
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and unwelcome sexual attention or
+  advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, questions, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement. All complaints
+will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.

package/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to agent-auto-resume
+
+We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+
+## Development Setup
+
+1. Fork and clone the repository.
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Run in development mode:
+   ```bash
+   npm run dev
+   ```
+4. Run tests:
+   ```bash
+   npm run test
+   ```
+
+## Pull Request Process
+
+1. Create a new branch for your feature or bug fix:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+2. Make your changes and write unit tests if applicable.
+3. Ensure types and code formatting are correct:
+   ```bash
+   npm run typecheck
+   npm run format
+   ```
+4. Run all tests to make sure everything passes:
+   ```bash
+   npm run test
+   ```
+5. Submit a Pull Request with a clear description of your changes.
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-auto-resume 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,184 @@
+# agent-auto-resume (aar)
+
+Daemon-based auto-resume CLI tool for Claude Code, OpenAI Codex CLI, and Google Antigravity CLI.
+
+---
+
+## What it does
+
+`agent-auto-resume` (command: `aar`) acts as a wrapper and watcher daemon for popular AI agent command-line interfaces. 
+When an agent stops due to a provider-declared usage limit, rate limit, or quota exhaustion, `aar` detects the limit pattern, extracts the reset/retry time, waits until that time in a daemon background worker, and automatically resumes the session safely.
+
+## What it does not do
+
+**This tool does not bypass, evade, or spoof usage limits.**
+It does not rotate API keys, switch accounts, or trick provider servers. It simply respects the provider-declared reset time by waiting locally, and then automatically resumes the existing session on your machine once the limit resets.
+
+---
+
+## Why daemon mode?
+
+Running AI agents can take hours to complete complex tasks. If they hit a limit while you are away (or asleep), you lose valuable time. 
+With `agent-auto-resume` running in the background, you don't need to manually check the terminal or click "resume" when the quota resets; it will automatically trigger the resume command when the time comes.
+
+---
+
+## Installation
+
+```bash
+npm install -g agent-auto-resume
+```
+
+---
+
+## Quick start
+
+1. Run the interactive setup:
+   ```bash
+   aar setup
+   ```
+2. Start the background daemon:
+   ```bash
+   aar daemon start
+   ```
+3. Run your AI agents as usual:
+   ```bash
+   claude
+   codex
+   agy
+   ```
+
+---
+
+## Architecture & Modes
+
+`agent-auto-resume` operates in three cooperative modes:
+
+### 1. Managed Command Mode (`aar managed`)
+When you launch an agent, it is wrapped inside a Pseudoterminal (PTY) runner. 
+- It captures all stdout/stderr, pipe it to your terminal, and scans it in real-time for limit patterns.
+- When a limit occurs, it captures the reset time, saves the session state, and safely kills the PTY process.
+
+### 2. Shell Shim Mode
+Installed via `aar setup`. It adds shell functions (in `~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`) so that calling `claude`, `codex`, or `agy` automatically runs them under `aar managed`.
+> [!NOTE]
+> `agent-auto-resume` works best after `aar setup`, which installs shell functions so future `claude`, `codex`, and `agy` sessions are launched in managed mode.
+
+### 3. Watcher Daemon Mode (`aar daemon`)
+A background process that:
+- Periodically scans `~/.agent-auto-resume/sessions/` for sessions in `waiting_limit_reset`.
+- Calculates the wait time (reset time + `bufferSeconds`).
+- Triggers the resume command via a background PTY when the wait expires.
+- (Optional) Watches local transcript directories and `tmux` panes.
+
+---
+
+## Provider Support Matrix
+
+| Provider | Command | Managed mode | Daemon resume | Transcript watcher | tmux watcher | Headless resume |
+|---|---|---:|---:|---:|---:|---:|
+| Claude Code | `claude` | Yes | Yes | Experimental | Experimental | Partial |
+| Codex CLI | `codex` | Yes | Yes | Experimental | Experimental | Yes |
+| Google Antigravity CLI | `agy` | Yes | Yes | No | Experimental | Experimental |
+
+---
+
+## Details on Provider Support
+
+### Claude Code (`claude`)
+- **Detection**: Matches patterns like `5-hour limit reached`, `usage limit reached`, or `Your limit will reset at YYYY-MM-DD...`
+- **Resume Strategy**: Resumes via PTY input (`continue\n`) if running, or executes `claude --continue`.
+- **Transcript Watcher**: Watches `~/.claude/projects` for session events.
+
+### Codex CLI (`codex`)
+- **Detection**: Matches patterns like `try again at HH:MM` or `resets_at: YYYY-MM-DD...`
+- **Resume Strategy**: Resumes by executing `codex exec resume --last "<CODEX_SAFE_RESUME_PROMPT>"`.
+- **Transcript Watcher**: Watches `~/.codex/sessions`.
+
+### Google Antigravity CLI (`agy`)
+- **Detection**: Matches common Antigravity quota messages.
+- **Resume Strategy**: Queries `agy --help` dynamically to find available subcommands (`agy resume --last`, `agy continue`, `agy c`, `agy conversation --last`) and falls back to `agy` with an interactive safe resume prompt.
+- **Status**: **Experimental**.
+> [!WARNING]
+> Antigravity CLI support is experimental because its resume behavior may change across versions. If Antigravity requires workspace trust, tool permissions, or review confirmations, `agent-auto-resume` does not automatically bypass them. The user may still need to approve them manually.
+
+---
+
+## Watcher Extras (Experimental)
+
+### tmux watcher
+By enabling the `tmux` watcher (via `--tmux` flag or config), the daemon scans open tmux panes. 
+It captures the screen content, parses it for limit text, and sends keypresses to resume when the time comes.
+- Enable via config: `"tmux": { "enabled": true }`
+- Run daemon: `aar daemon start --tmux`
+
+### transcript watcher
+The daemon can watch logs written to `~/.claude/projects` or `~/.codex/sessions` and record limit-reached events in the background, even if the session was not started inside `aar managed`.
+- **Note**: It cannot reliably read arbitrary terminal output from sessions that were started before setup unless tmux watcher or transcript watcher can detect them.
+
+---
+
+## Commands Reference
+
+### setup
+```bash
+aar setup
+```
+Initializes `~/.agent-auto-resume/`, generates default `config.json`, and guides shell configuration.
+- `--shell <zsh|bash|fish>`: Specific shell configuration.
+- `--no-shell-modify`: Setup directories but do not edit rc files.
+- `--print-shell-snippet`: Only output the snippet to add.
+
+### daemon
+```bash
+aar daemon start   # Start background daemon
+aar daemon stop    # Stop background daemon
+aar daemon restart # Restart daemon
+aar daemon status  # View daemon PID status
+aar daemon logs    # Print daemon log output
+```
+
+### status
+```bash
+aar status
+aar status --json
+```
+Prints the daemon status and a list of currently waiting sessions, including time remaining.
+
+### sessions
+```bash
+aar sessions
+aar sessions --json
+```
+Lists all saved session logs and statuses.
+
+### recover
+```bash
+aar recover
+aar recover --last
+aar recover --id <session-id>
+```
+Manually triggers recovery for a failed or waiting session in the background.
+
+### retry-now
+```bash
+aar retry-now --id <session-id>
+aar retry-now --last
+aar retry-now --force
+```
+Immediately resumes a session, bypassing the waiting time. If the reset time hasn't passed, it will warn you unless `--force` is provided (not recommended).
+
+---
+
+## Safety & Security Design
+
+1. **No Evading Limits**: Does not evade limits or abuse providers. Respects declared wait times.
+2. **Safe Resume Prompts**: When resuming, `aar` passes instruction prompts to inspect repository states (`git status`, `git diff`) and resume only the remaining, incomplete parts.
+3. **No Automatic Tool/Trust Approval**: Does not bypass "Workspace Trust" or "Tool Confirmations" (like file writes). These must still be approved by the user when required.
+4. **Environment Warning**: Since `aar` runs commands in background PTYs, make sure your environment is secure. Do not leave sensitive files uncommitted.
+
+---
+
+## License
+
+MIT License. See [LICENSE](file:///Volumes/MOVESPEED/Documents/GitHub/agent-auto-resume/LICENSE) for details.

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Supported Versions
+
+We support security updates for the following versions:
+
+| Version | Supported |
+| ------- | --------- |
+| < 1.0.0 | Yes       |
+
+## Reporting a Vulnerability
+
+We take the security of this project seriously. If you find a security vulnerability, please do not report it publicly via GitHub Issues. Instead, please report it privately.
+
+Please report security issues by opening a private vulnerability report on GitHub if available, or contact the project maintainers directly.
+
+We will acknowledge your report within 48 hours and provide a detailed response with next steps, including proposed patches or mitigation instructions.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node