Watchcat is a local reliability manager for AI coding sessions. watchcatd
owns provider connections, discovers recent sessions, classifies
structured failures, and applies bounded recovery policies. The watchcat CLI
controls the background service.
Codex supports discovery, logs, recovery, send, and interrupt. Claude Code supports automatic discovery and logs from its native local transcripts. Claude live-session recovery, send, and interrupt are not supported; Watchcat does not launch a second Claude process against an existing conversation.
watchcat CLI ─ framed JSON RPC ─ watchcatd ─ Codex App Server
local socket │
├─ policies and hot reload
├─ watchlist and lifecycle
└─ runtime state and events
The service listens only on a current-user Unix socket. It does not open a TCP
port or store provider credentials. The socket directory is mode 0700, the
socket is mode 0600, and macOS/Linux peers must have the daemon user's UID.
macOS and Linux release archives include watchcat and watchcatd:
curl --proto '=https' --tlsv1.2 -LsSf \
https://raw.githubusercontent.com/hx-w/watchcat/main/scripts/install.sh | shRun the same command again to update. The installer verifies the release
checksum and replaces both watchcat and watchcatd. Run watchcat service stop
before updating and watchcat service start after installation. Stop foreground
instances with Ctrl-C. Always upgrade CLI and server together.
Install a specific version or destination when reproducibility matters:
curl --proto '=https' --tlsv1.2 -LsSf \
https://raw.githubusercontent.com/hx-w/watchcat/main/scripts/install.sh \
| WATCHCAT_VERSION=v0.7.0 WATCHCAT_INSTALL_DIR="$HOME/bin" shBuilding from source requires Rust 1.85 or newer:
cargo install --git https://github.com/hx-w/watchcat --locked --binsSupported platforms: macOS and Linux. Windows server transport is not implemented.
Watchcat uses the authenticated codex command on the same machine. It needs no
separate OpenAI API key.
watchcat config init
watchcat service install
watchcat service start
watchcat service statusThe service starts at login and runs independently of your terminal. See
Background services for logs and custom paths. Use watchcatd --dry-run for a foreground check.
Then:
watchcat session list
watchcat session add SESSION_ID --label "release task"
watchcat service statusAll runtime commands require watchcatd and use local RPC. The CLI never starts
provider processes or runs recovery itself. There is no offline execution mode.
watchcat service status
watchcat service stop
watchcat service start
watchcat service restart
watchcat service uninstallService management uses launchd on macOS and systemd user services on Linux. Uninstalling the service preserves all configuration, watchlists, and history. Service lifecycle is the only global on/off control. There is no separate guard switch.
Watchcat subscribes to NSWorkspace.runningApplications changes with KVO,
including newly launched background and LSUIElement apps, then installs an
Accessibility observer for each matching app. Existing apps and windows are
checked once at startup. New window, sheet, focus, and layout events trigger
rule matching; there is no periodic desktop scan. A newly discovered app whose
AX interface is temporarily unavailable gets at most four subscription attempts
through one-shot callbacks, not repeated clicks.
Grant the installed watchcatd executable Accessibility access in
System Settings → Privacy & Security → Accessibility, then restart the
service. watchcat service status shows permission readiness, observer counts,
unavailable candidates, and click results. An observer count is not proof that a
particular permission dialog can be handled; inspect the event log for coverage.
The built-in directory-access rule handles known English and Chinese Desktop,
Documents, Downloads, removable-volume, and network-volume consent headings on
system-owned UI hosts. It is enabled by default and applies across the desktop,
independently of session membership. Add custom window rules through the CLI:
watchcat config dialog list
watchcat config dialog set helper-ready --app org.example.Helper \
--title "Ready to continue" --button "Continue"
watchcat config dialog disable helper-ready
watchcat config dialog enable helper-ready
watchcat config dialog remove helper-ready
watchcat config dialog disable directory-access--app matches an exact bundle ID or absolute executable path of the window
owner, which can differ from the app requesting access. --title matches the
exact window title; --text matches text within the primary dialog heading.
Specify at least one of them; when both are present both must match. --button
matches an exact enabled button label. Rules cannot press ambiguous buttons or
windows matching multiple rules, and windows containing editable/credential
fields are skipped. Custom rules authorize their specified button beyond the
built-in directory-consent categories; keep selectors specific.
Rules are stored under [dialogs.rules.NAME] in the existing TOML config and
apply immediately through the CLI. Direct file edits use the existing config
hot reload. No restart is needed for rule changes. Rule commands require the
service; log commands also work after it stops.
watchcat service logs --limit 30
watchcat service logs --clicks --limit 50
watchcat service logs --jsonLogs show local time with timezone, event, app/PID, rule, button, and outcome.
They distinguish process discovery, successful subscriptions (including AX event
names), unavailable AX interfaces, skipped windows, click intent, click sent,
window closed, and unconfirmed results. click.sent does not mean the window
closed or the original tool succeeded. Repeated identical skip reasons are
collapsed per window. Events persist in dialog-events.jsonl alongside the
existing daemon logs and use engine.log_retention; full window text and
screenshots are not stored. Counters in service status cover the current daemon
run; event logs survive restarts. History starts with this implementation and
cannot recover click records absent from earlier versions.
watchcatd --dry-run records matches without clicking. Stopping the service
prevents further clicks; it does not revoke permissions already granted by
macOS. A logged-in desktop and an AX-capable window owner are required. KVO
covers applications represented by NSWorkspace, not every arbitrary Unix
process. Real macOS permission prompt compatibility remains unverified.
Every poll (10 seconds by default) discovers Codex and Claude Code sessions,
including existing sessions active within the last three days. No hooks or
manual registration are required. Disable an adapter with
[providers.codex] enabled = false or [providers.claude] enabled = false.
watchcat session list
watchcat session list --provider claude
watchcat session search --provider codex
watchcat session add SESSION_ID --provider claude
watchcat session remove SESSION_ID --provider claudelist shows managed sessions across providers. search browses a provider's
catalog, including excluded and old sessions; JSON output includes its next cursor.
Manual removal remains excluded across polls and restarts. A manual add clears
that exclusion. Removal never deletes provider transcripts or stops their work.
[lifecycle]
stale_after_seconds = 259200Entries expire after three days without provider activity. Polling, recovery logs, metadata writes, and unresolved failures do not extend that time. A manual add grants a fresh three-day window. Automatically expired sessions rejoin when new provider activity appears. Active sessions and sessions whose provider cannot be checked are retained until their activity can be established.
Every known condition is editable. A retry policy owns its action, backoff kind, initial and maximum delays, attempt limit, and exact recovery prompt.
watchcat config policy list
watchcat config policy set capacity.model_overloaded \
--action retry \
--backoff exponential \
--initial-delay 15s \
--max-delay 5m \
--max-attempts 8 \
--prompt "Continue the unfinished task. Attempt {attempt}/{max_attempts}."Prompt templates support {provider}, {model}, {condition},
{provider_code}, {attempt}, and {max_attempts}. Unknown conditions skip by
default. Daemon-side changes are validated, written atomically, and published as
a new revision. Valid external edits are hot-reloaded; invalid edits leave the
last good settings active.
watchcat session send SESSION_ID "Continue with the release checklist."
watchcat session interrupt SESSION_ID
watchcat session logs SESSION_ID --limit 30
watchcat session logs SESSION_ID --category capacityActivity is always scoped to a named session. Watchcat stores a bounded JSONL history of failure and recovery events, not a copy of the full conversation. Provider messages are read on demand.
Manual retry is accepted as a durable background operation and returns an operation ID before provider work begins. Repeating an unacknowledged request returns the existing operation. RPC callers can follow it to success, failure, or an explicit unknown result when a provider acknowledgement is lost or the service restarts; it never claims that an uncertain recovery was not sent.
The recovery counter advances only after the recovery turn is observed as completed. Starting a retry is not counted as success. The hands-free percentage is automatic successful recoveries divided by all successful recoveries.
- Automatic session continuations require current watchlist membership; exclusions revoke recovery.
- macOS directory consent is desktop-wide and follows the service lifecycle, independently of the watchlist.
- Each failed turn is handled at most once.
- Every retry is delayed and bounded.
- The failed turn is rechecked immediately before a continuation is sent.
- A changed session cancels the pending continuation.
- Automatic recovery starts a new turn and never steers active work.
- Unknown failures skip by default.
- One server owns a state directory.
- Mutations can carry an expected revision and fail on stale client state.
Configuration and watchlist schemas are version 4, control state is version 2,
runtime recovery state stays at version 3, and RPC is version 2. Other versions
are rejected without modification. There is no automatic migration.
To reset an older installation, stop its service, back up the paths printed by
watchcat config path, move the old config and state files aside, and run
watchcat config init before starting the new server.
cargo test --all-targets --locked
cargo fmt --all --check
cargo clippy --all-targets --locked -- -D warningsSee Architecture, Background services, and the Security policy.