Omahub
← All plugins
D

Omarchief

by daventhedude

Your desktop's chief of staff: an Omarchy-native, theme-aware companion that lives at the screen edge, takes orders through your configured AI agent, and keeps session-aware conversations in place. Drag or tuck it, move it across monitors, get replies in a bubble or hand work to Omarchy's native console, and keep status and settings one click away in the bar — without a daemon, hook, or extra package.

GitHub

Security review

Potentially dangerous behavior detected · 2 findings

Deterministic scan — not a security guarantee

High
Risk level
High
Analyzed commit
1c95b98
Scanned
1 month ago
  • high destructive_filesystem tests/model.test.mjs:484

    Destructive operation on the root filesystem or a block device.

    rm -rf /tmp/omarchief-escape",
  • medium package_manager …/workflows/tests.yml:36

    System-wide Python package installation (not --user).

    pip install --disable-pip-version-check --no-deps "$numpy_wheel"

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

The deterministic scan's high finding is a false positive: the `rm -rf /tmp/omarchief-escape` is test-only cleanup of a temporary directory, and the pip install is confined to GitHub Actions CI. The plugin itself is transparent, contains no hidden persistence, telemetry, or install-time destructive commands, and clearly discloses that it launches the user's chosen agent with auto-approval flags.

  • tests/model.test.mjs:484 contains `rm -rf /tmp/omarchief-escape`, but it is test-only cleanup and is not executed during plugin install or runtime.
  • .github/workflows/tests.yml:36 installs NumPy with pip in CI only; it does not affect the user's system.
  • The service launches agent CLIs with auto-approval flags (e.g. `--permission-mode auto`, `--approve-for-me`, `--auto`), so an explicit order can execute commands without per-action confirmation; this is documented in the README and SECURITY.md.
  • The plugin performs a one-time migration that edits Omarchy's shell.json and writes state under XDG state directories; this is scoped and documented.
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/daventhedude/omarchief --enable
Desktop #bar #quickshell #ai

Omarchief

Your desktop's chief of staff — a small, theme-aware companion that can act on an order, carry an agent conversation, and stay one click away in the Omarchy bar.

Gritty, Omarchief's default desktop companion

Omarchief is built around Omarchy 4's native plugin architecture: one resident service owns the creature and its state, while every bar gets a thin view onto that same service. There is one agent turn, one conversation, and one place in the world no matter how many monitors you use.

Install

omarchy plugin add https://github.com/daventhedude/omarchief.git --enable

That is the entire setup. Review Omarchy's unsandboxed-plugin warning, confirm the install, and keep the declared right placement or choose another bar section. Omarchy then starts the service and adds the one canonical widget entry. Do not add a second entry to shell.json.

On upgrade from a pre-4.0 release, Omarchief merges the old settings once and removes duplicate top-level/widget entries automatically. The bar entry is the canonical settings location after migration.

Requirements

  • Runtime: Omarchy 4, including its Quickshell/Hyprland integration, bash, python3, jq, and the regular omarchy-* helpers. Omarchief installs no system package, daemon, hook, or background unit of its own.
  • Orders: an agent CLI already discovered and configured by Omarchy. Claude, Codex, and OpenCode support bubble conversations; other Omarchy agents open in the native console scratchpad. The companion and its non-agent controls remain usable when no agent is selected.
  • Theme repainting: ImageMagick's magick, included by Omarchy. If it is unavailable, the original sheet remains visible and a live tint is used when the pet permits it.
  • Development only: Node.js 22 for model tests; Qt 6 qmllint, jq, and a running Wayland/Omarchy session for integration checks; Python 3, NumPy, and ImageMagick for the artwork builders.

What it feels like

  • Click the creature to ask for something. Enter sends; Escape closes.
  • Right-click the creature for Omarchy's native console scratchpad.
  • On a fresh install it sits at the bottom-right of the active screen; on a one-screen laptop that is simply the built-in display.
  • Drag it along an edge to choose its home. Push it into an outer edge to tuck it away; pull the visible part back out when you want it.
  • Open the bar widget for status, the latest answer, quick actions, and settings. Middle-click asks from that bar's monitor; right-click opens the console there.
  • Start a new conversation whenever context should not carry forward.

Omarchief's native settings with Gritty on the desktop

The creature follows the desktop rather than drawing a second UI language. Its controls use Omarchy's colors, typography, spacing, panels, focus states, and bar conventions. It understands multi-monitor virtual coordinates, Hyprland's outer gap, fullscreen workspaces, the chosen default agent, and Omarchy's rate-limit records.

Overview and settings

The popout opens on a compact overview: current agent and state, monitor, energy, latest answer, console, and only the actions that matter now. The settings view keeps durable choices together:

  • agent and conversation lifetime;
  • companion and size;
  • home monitor, follow-focus behavior, and fullscreen avoidance;
  • idle expressions, theme recoloring, and reduced motion.

Choices are changed in place. The panel stays open, keyboard navigation is supported, and options that do not apply to the selected pet are left out.

Agents

Omarchief discovers the agents Omarchy knows about and follows the desktop default unless you choose another. Claude, Codex, and OpenCode can answer in the bubble with session-aware follow-ups. The native console is always the escape hatch for a longer or interactive job.

An order is never retried implicitly. While an agent turn is active, a second order is refused instead of replacing it, and Stop ends that exact turn. Timeout, cancellation, and process exit are terminal states; an old cleanup callback cannot affect a later request.

Be clear about the trust boundary: a bubble order runs the selected agent headlessly and unattended. Depending on the agent and CLI version, its adapter may grant automatic approval or bypass an approval or sandbox boundary. The standing instructions tell it to avoid irreversible work unless explicitly ordered, but instructions are not a sandbox.

The console is Omarchy's native scratchpad, including its Quake treatment when the installed Omarchy provides it. It makes the work visible, interactive, and steerable. It does not make the agent sandboxed or promise per-tool confirmation. Omarchief follows Omarchy's launcher when it follows the desktop default; an explicitly selected or resumed agent uses that CLI's compatible interactive launch mode. Treat both paths as having the filesystem and network reach of the selected CLI.

Omarchief does not install agent hooks and does not edit another application's settings. It may passively read an existing OmaPets-compatible status record to reflect working, waiting, success, or error on the creature's face. Without that record, window and rate-limit state provide the fallback.

The plugin makes no network request and sends no telemetry. The agent you choose has its own network behavior, exactly as it does in a terminal. Private vulnerability reports follow SECURITY.md.

Bring your own companion

Three companions are bundled:

  • gritty — the default, with drawn moods, a blink, and idle expressions;
  • quattro — the rally car from Omarchy's Tokyo Night wallpaper, adapted as a still, theme-aware companion under Omarchy's MIT licence;
  • gritty-front — the same weathered machine facing straight ahead, kept as a deliberately stark still companion.

Drop a folder containing pet.json and its spritesheet into:

~/.config/omarchief/pets/<id>/

OmaPets folders under ~/.config/omapets/pets/<id>/ are also discovered. User pets take precedence over bundled pets with the same id. Unsafe ids and relative paths containing traversal are rejected.

Omarchief supports Codex/Petdex-style animated atlases and compact expression grids. A pet can declare a walk cycle, mood cells, blink, idle performances, and a themeable hue range. The complete schema is in docs/pets.md.

Useful commands

omarchy-shell omarchief ask
omarchy-shell omarchief order "open my calendar"
omarchy-shell omarchief stop
omarchy-shell omarchief summon
omarchy-shell omarchief fresh
omarchy-shell omarchief travel DP-2
omarchy-shell omarchief tuck on
omarchy-shell omarchief show
omarchy-shell omarchief hide
omarchy-shell omarchief status

Every mutation validates its value before changing state. The JSON status snapshot lives at $XDG_STATE_HOME/omarchy/omarchief/status.json (normally ~/.local/state/omarchy/omarchief/status.json) for read-only integrations. It is output, not the control plane; the bar talks to the service directly.

Remove

omarchy plugin remove io.github.daventhedude.omarchief

Confirm Omarchy's removal prompt. Omarchief installs no hooks, background unit, or command outside its plugin folder. Its optional local history and recolored-sheet cache remain in $XDG_STATE_HOME/omarchy/omarchief/ (normally ~/.local/state/omarchy/omarchief/) so an accidental reinstall does not erase them. They can be removed separately if that history is no longer wanted.

Develop and verify

omarchy plugin validate .
node --test tests/*.test.mjs
tools/coldstart-check

The cold-start test uses an isolated HOME/XDG environment and a real plugin manifest plus shell configuration, so an installed user pet cannot mask a missing bundled asset. Architecture, visual checks, and the release gate are documented in docs/development.md.

License

MIT. The bundled Gritty artwork is original work distributed under the same terms. Quattro retains its upstream notice in THIRD_PARTY_NOTICES.md; each pet also carries a local NOTICE. Omarchief is independent and is not endorsed by Omarchy or the owners of marks visible in upstream artwork.