Omahub
← All plugins
F

Ambient Agent

by fjalvarezdd

Screen-edge ambient glow that reflects AI agent state

GitHub

Security review

Review recommended · 1 finding

Deterministic scan — not a security guarantee

Low
Risk level
Low
Analyzed commit
15c3574
Scanned
1 month ago

Flagged patterns appear only in documentation files (README / docs) — descriptive examples, not executable code.

  • Docs external_hosts README.md:20

    Downloads or connects to an external HTTP(S) host.

    git clone https://github.com/fjalvarezdd/omarchy-ambient-agent

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
15c3574
Reviewed
1 month ago

The plugin is a benign Quickshell overlay that reads a state file and config to draw an edge glow; it performs no network access, no destructive operations, and no credential handling. The deterministic finding about an external host refers only to a documented git clone in the README, which is not part of the executable code.

  • The install.sh copies files and installs a CLI, but all actions are explicit and confined to user directories; no system-wide changes or hidden behavior.
  • The Service.qml spawns python3 subprocesses to read files with O_NOFOLLOW, which is safe and avoids symlink attacks.
  • No obfuscation, persistence, or data exfiltration mechanisms were found in the sampled source.
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/fjalvarezdd/omarchy-ambient-agent --enable
Developer Tools #Hyprland #quickshell #ai

Ambient Agent 🫧

Your Omarchy desktop feels what your AI agents are doing — no pop-ups.

The screen edge breathes cyan while an agent works, warms to amber the moment one needs your call, and gives a quiet green pulse when it's done. Peripheral awareness, not interruption.

omarchy.agents shows agent usage and limits. Ambient Agent shows the thing that actually costs you time when you run several agents at once: which one is silently waiting for you.

▶ Live demo & docs · by @fjalvarezdd

demo

Install

# 1) the overlay (Quickshell plugin)
omarchy plugin add https://github.com/fjalvarezdd/omarchy-ambient-agent --enable

# 2) the agent-ambient helper CLI + a default config
git clone https://github.com/fjalvarezdd/omarchy-ambient-agent
cd omarchy-ambient-agent && ./install.sh

The overlay itself only ever reads its state — it never writes to your filesystem. Prefer no CLI? Anything can drive it by writing one word (working/needs/done/error/idle) to ~/.local/state/omarchy/agent-ambient.

Drive it

Set the state from anywhere:

agent-ambient working   # slow cyan breathing
agent-ambient needs     # amber pulse — an agent is blocked on you
agent-ambient done      # green flash, then calm
agent-ambient error     # red pulse
agent-ambient idle      # off

Wrap any long task so the edge tracks it automatically:

agent-ambient working; npm run build; agent-ambient done

If your agent or editor can run a command on events, point it at agent-ambient <state> — e.g. starting a task → working, waiting for your approval → needs, finished → done. A ready-to-adapt hook example lives in hooks/.

Theming

By default the glow uses your selected Omarchy theme accent (Color.accent), so it matches whatever theme you're on. The done state is a solid blue. Override any of it in the config (colors, doneColor).

Configure it

Edit ~/.config/omarchy/ambient-agent.json — it hot-reloads, no restart:

{
  "enabled": true,
  "borderWidth": 3,
  "glowWidth": 26,
  "glowOpacity": 0.40,
  "radius": 16,
  "colors": { "working": "#7dcfff", "needs": "#e0af68", "done": "#9ece6a", "error": "#f7768e" },
  "periods": { "working": 3800, "needs": 1500, "error": 1100 },
  "doneTimeoutMs": 2500
}

Match your theme with colors; calm it down with a smaller glowWidth / glowOpacity; slow the breathing with bigger periods; set "enabled": false to switch it off without uninstalling.

State Color Motion
working cyan #7dcfff breathe 3.8s
needs you amber #e0af68 pulse 1.5s
done green #9ece6a flash once
error red #f7768e pulse 1.1s
idle — off

How it works

A tiny Quickshell layer-shell overlay (transparent, click-through, WlrLayer.Overlay) draws the edge glow, driven by a one-word state file at ~/.local/state/omarchy/agent-ambient. No daemon, no dependencies beyond Omarchy's shell.

Uninstall

omarchy plugin remove ambient-agent
rm -f ~/.local/bin/agent-ambient ~/.config/omarchy/ambient-agent.json

Roadmap

  • Per-agent orbs in the bar (N agents); the edge shows the most urgent state.
  • Soft blurred glow and per-edge direction hints.

MIT · built for Omarchy.