CLI reference
Commands
Run agent-watchdog --help for command help. watch polls sessions,
status prints a snapshot, install registers background services,
uninstall removes those services, and link links a source build.
config schema prints the settings schema and config validate checks a file.
usage-bridge bind and usage-bridge ingest connect Claude’s status line
to menu-bar usage monitoring; they do not print usage reports.
See command details.
Options
Generated from apps/watchdog/src/cli/options.ts. Defaults below are raw
option values; “unset” means detection, fallback, or no override as explained
in the meaning column. Harness applicability describes the affected metric
or service, not a restriction on parsing the flag. Cache metrics are Claude
only. Both harnesses require known context capacity for percentage alerts.
Command-line values override file values. Config list values are JSON arrays.
| Option | Default | Commands | Harness | Where | Meaning |
|---|---|---|---|---|---|
--help |
false | all | Both / shared | CLI only | Show this help. |
--version |
false | all | Both / shared | CLI only | Print the version. |
--verbose |
false | all | Both / shared | CLI or config | Debug logging. |
--cmux-path <path> |
unset; see meaning | all | Both / shared | CLI or config | Path to the cmux binary (default: search PATH and the Homebrew dirs). |
--state-file <path> |
~/.local/state/agent-watchdog/state.json | all | Both / shared | CLI or config | Where per-session alert state is persisted. |
--config <path> |
~/.config/agent-watchdog/config.json | all | Both / shared | CLI only | Config file to read settings from (a flag always wins over the file). |
--no-config |
false | all | Both / shared | CLI only | Do not read any config file. |
--interval <duration> |
30s | watch | Both / shared | CLI or config | Poll interval. |
--once |
false | watch | Both / shared | CLI only | Run one poll and exit. |
--dry-run |
false | watch | Both / shared | CLI or config | Evaluate and log actions without notifying or sending anything. |
--json |
false | watch, status, config | Both / shared | CLI only | watch: emit one JSON line per poll (snapshots and actions) instead of log lines. status: print one JSON document. config validate: print the result as JSON. |
--sidebar |
true | watch | Both / shared | CLI or config | Keep a cmux sidebar status pill per workspace, re-asserted every poll (disable with –no-sidebar; –once and –dry-run never touch the sidebar). |
--status-file <path> |
~/.local/state/agent-watchdog/status.json | watch | Both / shared | CLI or config | Write a JSON status document here after every poll (read by the menu bar app). Under –once the file is only written when this flag is given explicitly. |
--no-status-file |
false | watch | Both / shared | CLI only | Do not write the status file. |
--tolerate-config-error |
false | watch | Both / shared | CLI only | Keep running on flags and defaults when the config file is invalid, publishing the error instead of exiting (install always bakes it into the launch agent). |
--scan-transcripts |
true | all | Both / shared | CLI or config | Also discover sessions by scanning enabled harness transcript folders (disable with –no-scan-transcripts). |
--stale-after <duration> |
6h | all | Both / shared | CLI or config | Ignore sessions with no activity for longer than this. |
--idle-after <duration> |
2m | all | Both / shared | CLI or config | Treat a session as idle after this much inactivity. |
--harnesses <list> |
claude,codex | all | Both / shared | CLI or config | Comma list of agent harnesses to watch: claude,codex. |
--codex-home <path> |
unset; see meaning | all | Codex | CLI or config | Codex data directory (default: CODEX_HOME or ~/.codex). |
--openai-usage |
false | watch | Codex | CLI or config | Monitor Codex subscription allowance. |
--openai-usage-notifications |
true | watch | Codex | CLI or config | Send Codex allowance alerts while monitoring is enabled. |
--openai-usage-warning |
true | watch | Codex | CLI or config | Enable the Codex allowance warning. |
--openai-usage-warning-pct <pct> |
80 | watch | Codex | CLI or config | Codex allowance warning percentage. |
--openai-usage-critical |
true | watch | Codex | CLI or config | Enable the Codex allowance critical alert. |
--openai-usage-critical-pct <pct> |
95 | watch | Codex | CLI or config | Codex allowance critical percentage. |
--openai-usage-exhaustion |
true | watch | Codex | CLI or config | Alert on confirmed Codex allowance exhaustion. |
--openai-usage-interval <duration> |
60s | watch | Codex | CLI or config | Codex allowance polling interval. |
--openai-codex-path <path> |
unset; see meaning | watch | Codex | CLI or config | Explicit Codex executable for allowance reads (default: search PATH). |
--anthropic-usage |
false | watch | Claude Code | CLI or config | Monitor a bound Claude allowance source. |
--anthropic-usage-notifications |
true | watch | Claude Code | CLI or config | Send Claude allowance alerts when source evidence supports them. |
--anthropic-usage-warning |
true | watch | Claude Code | CLI or config | Enable the Claude allowance warning when supported. |
--anthropic-usage-warning-pct <pct> |
80 | watch | Claude Code | CLI or config | Claude allowance warning percentage. |
--anthropic-usage-critical |
true | watch | Claude Code | CLI or config | Enable the Claude allowance critical alert when supported. |
--anthropic-usage-critical-pct <pct> |
95 | watch | Claude Code | CLI or config | Claude allowance critical percentage. |
--anthropic-usage-exhaustion |
true | watch | Claude Code | CLI or config | Alert on confirmed Claude allowance exhaustion when supported. |
--anthropic-usage-state <path> |
~/.local/state/agent-watchdog/usage/claude.json | watch, usage-bridge | Claude Code | CLI or config | Private Claude bridge state path. |
--codex-store <path> |
~/.cmuxterm/codex-hook-sessions.json | all | Codex | CLI or config | Path to the cmux Codex session store. |
--codex-context-window <tokens> |
unset; see meaning | all | Codex | CLI or config | Override Codex context capacity (default: use session evidence). |
--codex-handoff-dir <path> |
unset; see meaning | all | Codex | CLI or config | Directory for Codex handoff files (default: session working directory). |
--session <id-prefix> |
unset; see meaning | all | Both / shared | CLI or config | Only sessions matching an id prefix or harness:id prefix. Repeatable. |
--cwd <path> |
unset; see meaning | all | Both / shared | CLI or config | Only sessions whose working directory is this path or lives under it. Repeatable. |
--warn-context <pct> |
35 | all | Both / shared | CLI or config | Notify when context usage reaches this percentage. |
--critical-context <pct> |
75 | all | Both / shared | CLI or config | Critical threshold; keep it below the auto-compact point (above 90). |
--cache-min-context <pct> |
20 | all | Claude Code | CLI or config | Cache-expiry alerts only apply at or above this context percentage. |
--cache-lead <duration> |
10m | all | Claude Code | CLI or config | Alert when the prompt cache expires within this lead time. |
--cache-ttl <duration> |
unset; see meaning | all | Claude Code | CLI or config | Force the Claude prompt-cache TTL (default: detect, else 1h). |
--context-window <tokens> |
200000 | all | Claude Code | CLI or config | Claude context window assumed for models without an override. |
--model-window <model=tokens> |
unset; see meaning | all | Claude Code | CLI or config | Claude context window for a model id (exact or prefix match). Repeatable. |
--message-agents |
false | all | Both / shared | CLI or config | Allow typing into conversations; also select stop or handoff for each trigger. |
--on-critical <list> |
notify | all | Both / shared | CLI or config | Critical actions: notify, stop, handoff. Automatic requests also require –message-agents. |
--on-cache-expiry <list> |
notify | all | Claude Code | CLI or config | Cache-expiry actions: notify, handoff. Automatic requests also require –message-agents. |
--stop-message <text> |
unset; see meaning | all | Both / shared | CLI or config | Custom stop message; placeholders {pct} {minutes} {model} {sessionId} {handoffFile} {now} {cwd}. |
--handoff-message <text> |
unset; see meaning | all | Both / shared | CLI or config | Custom handoff message; placeholders {pct} {minutes} {model} {sessionId} {handoffFile} {now} {cwd}. |
--cache-handoff-message <text> |
unset; see meaning | all | Claude Code | CLI or config | Custom cache-expiry handoff message; placeholders {pct} {minutes} {model} {sessionId} {handoffFile} {now} {cwd}. |
--print |
false | install | Both / shared | CLI only | Print the launchd plist instead of writing and loading it. |
--dir <path> |
~/.local/bin | link | Both / shared | CLI only | Directory to place the agent-watchdog symlink in. |
--menubar-bin <path> |
unset; see meaning | install, link | Both / shared | CLI only | Menu bar app binary (apps/menubar/.build/release/agent-watchdog-menubar after yarn workspace @agent-watchdog/menubar build). install: also run it as a launchd agent. link: also symlink it as agent-watchdog-menubar. |
Examples and settings
Start with notification settings. Terminal messages require explicit per-trigger opt-in. Detailed CLI examples and the configuration reference explain scoping, units, and precedence.