Omahub
← All plugins
5

Agent Watcher

by 5d0tal1gat0r

Every Claude Code, Codex, Gemini CLI and OpenCode session across your workspaces in one bar pill — it blinks when an agent finishes or waits for you.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
976a715
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
976a715
Reviewed
1 month ago

The plugin is a bar widget that monitors AI agent sessions by installing hooks into agent config files. It only writes state files under $XDG_RUNTIME_DIR, reads process/window info from /proc and hyprctl, and modifies agent configs only when the user explicitly enables hooks, with backups and atomic writes. No network access, obfuscation, or destructive behavior was found.

  • The setup script modifies user config files (~/.claude/settings.json, ~/.codex/hooks.json, etc.) when hooks are enabled, but only adds entries containing 'agent-watcher-hook', creates backups, and validates JSON before changes.
  • The hook script walks /proc and calls hyprctl to resolve window addresses; this is read-only and does not execute anything from agent payloads.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/5d0tal1gat0r/omarchy-agent-watcher --enable
Widgets #bar #quickshell #ai

Agent Watcher for Omarchy

One bar pill for every AI-agent session on your desktop. Claude Code, Codex, Gemini CLI and OpenCode sessions are listed per Hyprland workspace with their state — working, waiting for you, done, idle — and the pill blinks (green = finished, yellow = needs a permission) whenever that happens in a window you are not looking at. Focus the window and the blink stops; click a row in the panel to jump straight to it.

preview

Install

omarchy plugin add https://github.com/5d0tal1gat0r/omarchy-agent-watcher.git --enable

Then open the panel (click the camera), expand Hooks and flip the switch next to each agent you use. That adds a few hook entries to the agent's own config:

agent what gets written note
Claude Code ~/.claude/settings.json → hooks (SessionStart, UserPromptSubmit, PermissionRequest, Notification, PostToolUse, Stop, SessionEnd)
Codex ~/.codex/hooks.json run /hooks inside Codex once to trust them
Gemini CLI ~/.gemini/settings.json → hooks
OpenCode ~/.config/opencode/plugins/agent-watcher.js

Claude Code picks the hooks up live in most cases; if a session doesn't show up, restart it. Codex, Gemini CLI and OpenCode load hooks at startup. Headless codex exec runs need --dangerously-bypass-hook-trust to fire hooks that haven't been trusted yet.

A backup <file>.agent-watcher.bak is written before every change, only entries pointing at agent-watcher-hook are ever added or removed, and flipping the switch off undoes it. The same works from a shell:

~/.config/omarchy/plugins/io.github.5d0tal1gat0r.agent-watcher/bin/agent-watcher-setup status all
~/.config/omarchy/plugins/io.github.5d0tal1gat0r.agent-watcher/bin/agent-watcher-setup install claude
~/.config/omarchy/plugins/io.github.5d0tal1gat0r.agent-watcher/bin/agent-watcher-setup remove claude

Before removing the plugin, switch the hooks off for each agent (or run agent-watcher-setup remove <agent>); the hooks are absolute paths into the plugin directory and would otherwise fail on every agent turn.

Usage

where action effect
pill left click open / close the panel (Esc closes, Tab switches panels, Enter refreshes)
pill middle click refresh now
panel click a session focus its window (switches workspace)
panel Hooks header expand / collapse the per-agent switches (opens by itself while nothing is installed)
panel agent switch install / remove that agent's hooks

Pill: 󰞮 2 · 1 = 2 sessions working, 1 needs attention. Dimmed icon = no sessions. Blink colors come from your theme (green / yellow).

Each row is named after the session: OpenCode's session title (it renames itself after the first exchange), Claude Code's task summary (read from the terminal title it sets), otherwise the project folder; the working directory sits underneath. Every agent has its own mark and color so rows are easy to tell apart at a glance.

IPC (for keybindings): omarchy-shell io.github.5d0tal1gat0r.agent-watcher toggle|open|close|refresh

Configure

omarchy bar set io.github.5d0tal1gat0r.agent-watcher blinkOnDone false --json
omarchy bar set io.github.5d0tal1gat0r.agent-watcher blinkOnWaiting false --json
key default meaning
blinkOnDone true blink (green) when an agent finishes responding in an unfocused window
blinkOnWaiting true blink (yellow) when an agent is blocked on a permission prompt

How it works

Each agent's native hook calls bin/agent-watcher-hook, which writes a tiny JSON file per session under $XDG_RUNTIME_DIR/omarchy-agent-watcher/ and pings the shell. The hook finds its own terminal window by walking up the process tree, so the panel knows the workspace and can focus it; the shell reads live window titles and focus from Hyprland. Sessions vanish on SessionEnd, when their process is gone, or when their terminal window is closed (re-checked whenever a window appears or disappears, and every 15 s). Nothing leaves your machine.

Hyprland ≥ 0.56 dispatches through a Lua API, so the plugin sends both the Lua (hl.dsp.focus{window=…}) and the classic (focuswindow) form when focusing a window — click-to-focus works on both generations.

Limitations

  • Vertical bars show the attention color but don't pulse.
  • A shell restart resets the "seen" memory, so unacknowledged sessions blink again even if you'd already looked at them.
  • Sessions without a Hyprland window (tmux/screen, SSH) appear under Other, without click-to-focus. An agent that outlives its closed terminal (OpenCode ignores the hangup) is dropped from the list within a second — the process itself keeps running until you kill it.
  • Sub-agent sessions (Claude Code subagents, OpenCode child sessions) and Claude Code's own background plumbing (the claude daemon and the bg-pty-host sessions it pre-spawns) are intentionally not listed — only the sessions you opened are.

Develop

node --test test/model.test.js
bash test/hook.test.sh
omarchy plugin validate .

MIT — see LICENSE.