Skip to content
agent-watchdog

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. handoff generate is an internal, machine-facing helper the menu bar runs to request an agent-authored handoff for one session; it takes its own fixed arguments (not the options below) and prints one JSON result. 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.
--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.
--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.
--inactive-after <duration> 30m all Both / shared CLI or config Hide sessions in the menu bar’s Inactive section after this long without activity.
--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 follows codex harness watch Codex CLI or config Monitor Codex subscription allowance (default: follow Codex harness).
--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> 40 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> 80 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 follows claude harness watch Claude Code CLI or config Monitor Claude subscription allowance (default: follow Claude harness).
--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> 40 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> 80 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-probe true watch Claude Code CLI or config Read Claude allowance with Claude Code’s headless usage command.
--anthropic-usage-interval <duration> 5m watch Claude Code CLI or config Claude allowance polling interval (2m to 1h).
--anthropic-claude-path <path> unset; see meaning watch Claude Code CLI or config Explicit Claude Code executable for allowance reads (default: ~/.local/bin/claude, then PATH).
--anthropic-usage-state <path> ~/.local/state/agent-watchdog/usage/claude.json watch, usage-bridge Claude Code CLI or config Private Claude bridge state path.
--anthropic-usage-renderer-timeout <duration> 5s usage-bridge Claude Code CLI or config How long the Claude status-line bridge waits for its renderer (500ms to 30s).
--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.
--setup-usage true install Both / shared CLI only Configure enabled subscription usage sources during install; –no-setup-usage leaves provider setup unchanged.
--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. The daemon only ever notifies; it never types into an agent’s terminal. Detailed CLI examples and the configuration reference explain scoping, units, and precedence.