AgentWatch

Local AI coding-agent session supervisor for Claude and Codex-oriented workflows, including OMX as a Codex wrapper/runtime layer. Supported targets are macOS, Linux, and WSL2. Windows native support is intentionally out of scope for the MVP.

AgentWatch is not a rate-limit bypass. It watches local agent sessions, detects quota/reset messages, converts reset text into time-zone-safe timestamps, schedules a safe resume, and records evidence for follow-up verification.

Install / run

# npm registry, once published
npm i -g @voidmatcha/agentwatch
agentwatch auto

# one-off npm
npx @voidmatcha/agentwatch auto --dry-run

# Bun uses the same npm package
bunx @voidmatcha/agentwatch auto --dry-run
bun install -g @voidmatcha/agentwatch

# shell installer, once hosted
curl -fsSL https://agentwatch.dev/install.sh | sh

For local development from this folder:

npm test
node ./src/cli.js auto --dry-run
bun ./src/cli.js auto --dry-run

Support model

AgentWatch treats OMX as a runtime layer around Codex-oriented workflows, not as a separate LLM engine.

First-class engines:
- Claude
- Codex, including OMX-managed Codex sessions

Runtime / transport adapters:
- tmux panes (resume + pane-capture verify)
- cmux panes (resume; capture verify is an extension point, falls back to state-based)
- Codex `codex exec resume`
- AgentWatch-owned PTY sessions — only within a `run` process; the standalone `watch`
  daemon cannot resume an owned PTY (it reaches external tmux/cmux panes or `codex exec resume`).
- OMX state/log hints when present

Future generic PTY adapters:
- Gemini CLI
- Aider
- OpenCode
- Goose
- custom terminal agents

Commands

agentwatch auto --dry-run
agentwatch parse ./limit.log --json
agentwatch ingest --engine claude --file ./limit.log --session cmux:F88B9E9D/E9509300
agentwatch next --session cmux:F88B9E9D/E9509300
agentwatch status
agentwatch watch --once                      # one supervise tick: resume any due session, verify any due session
agentwatch watch --watch --interval 10000    # continuous loop (Ctrl-C / SIGTERM to stop); or run --once via launchd/systemd
agentwatch watch --once --dry-run            # simulate the tick (record resume_sent without spawning) to preview the loop
agentwatch resume cmux:F88B9E9D/E9509300 --dry-run
# Claude resume requires --pane during ingest/watch; Codex can use codex exec resume.
# Windows native is intentionally unsupported; use WSL2 on Windows.
agentwatch run codex -- codex exec "finish the task"

MVP behavior

• Detects Claude/Codex-style limit messages, including OMX runtime output when it wraps Codex sessions.
• Parses reset strings such as resets 12:40am (Asia/Seoul).
• Stores state atomically under ~/.agentwatch/state.json by default.
• Schedules resume time as reset time + one-minute safety buffer.
• watch runs the real supervise loop: waits until a session's resume time, fires the resume adapter (with a cross-restart double-fire guard), then verifies recovery. --once does a single tick (for launchd/systemd); --watch loops in-process with graceful SIGINT/SIGTERM shutdown.
• Post-resume verify captures live pane output (tmux capture-pane) and re-checks it for limit signals to decide recovered vs still-limited; still-limited retries up to 3 times, then escalates to needs_manual_escalation. cmux pane capture is a documented extension point that falls back to state-based evidence.
• Supports npm, npx, and Bun execution because it is a dependency-free Node ESM package.
• Builds adapter commands for Codex (codex exec resume) and tmux/cmux pane fallback.
• Claude deliberately does not use claude -p (print-mode may be API-token/billing gated and may not resume the original TUI session). Claude recovery therefore requires a live tmux/cmux pane. An AgentWatch-owned PTY only exists inside a run process, so the standalone watch daemon cannot resume one — it reaches external tmux/cmux panes or codex exec resume.
• Supported OS targets: macOS, Linux, and WSL2. Windows native/ConPTY support is intentionally excluded from this MVP.

Design principle

Existing auto-resume scripts often do:

limit text -> sleep -> send continue

AgentWatch is shaped as:

observe -> classify -> schedule -> resume -> verify

The full loop is implemented: parser, scheduler, state store, CLI, the watch supervise loop (schedule → resume → verify with retry/escalation), and pane-output evidence checks via tmux capture-pane. Remaining extension points: cmux pane capture (falls back to state-based evidence today) and a self-bootstrapping always-on daemon (use a launchd/systemd wrapper around watch --once, or watch --watch).

Safety

• No telemetry.
• No provider limit bypass.
• No automatic destructive approval.
• auto --dry-run shows what would be monitored before taking actions.
• Resume commands can be inspected with agentwatch resume <session> --dry-run.