Voice
Omarchy Fans Agent Launcher
By Omarchy plugin: launch Hermes Agent or OpenClaw locally, in Docker, or on a Fly.io Sprite from a keybinding
Install
npm install -gREADME
# Omarchy Agent Launcher
**Run AI agents from your desktop, with a chief of staff.** Press a key and the
**Agent Dashboard** opens on **Jarvis**: an agent that runs on your own GPU by
default, knows what every other agent is doing and what it cost, and hands work
to bigger models when you ask. Create and launch agents on one page, see every
agent's status, jump to any chat, follow a sortable event log, and get notified
when an agent needs you. Agents run in a shell on your machine, inside their
official Docker image, or on a [Fly.io Sprite](https://fly.io/sprites); the
models they use can be local, an API or subscription you sign in to, or a vLLM
server on a [Modal](https://modal.com) GPU you choose.
The dashboard is a persistent window (it stays until you close it) with six
pages, switchable with `1`–`6`:
| Page | What it shows |
|------|---------------|
| **Jarvis** | the chief of staff: its state and Chat, a plain status **Brief**, an **Ask Jarvis** box answered by its model, the numbers (prompt and output tokens, USD, total and today), the **backends** work can go to (with the Modal GPU picker), and **every task** with its tokens and cost. |
| **Agents** | every saved agent with a status pill (running / blocked / done / idle), its job, last event, task count, tokens and USD so far, and **Chat**, Stop, Edit job, Remove. Enter or Chat focuses the agent's window or reattaches its session. |
| **New agent** | the one-page setup form (below) |
| **Events** | the event log: filter by agent, task, level, or text; click a column header to sort |
| **Notifications** | open blockers (things that need you) with Chat and Resolve, recent warnings, and the desktop-notification toggle |
| **Projects** | every registered project (`hermes project create`) with its current waterfall phase, percent complete, and open blocker count, read from its bound Hermes kanban board — double-click jumps to Events filtered to that project's agent |
The bar button opens the dashboard; right-click opens a quick agent switcher;
a red badge counts open blockers.
The **New agent** page asks for:
| Step | Choices |
|------|---------|
| **Agent** | [Hermes Agent](https://github.com/NousResearch/hermes-agent) (Nous Research) · [OpenClaw](https://openclaw.ai) |
| **Runtime** | local shell · Docker container · Fly.io Sprite (needs your Sprites API token) |
| **Model** | **Local GPU (offline)**, Anthropic, OpenAI, OpenAI Codex, Nous Portal, xAI, OpenRouter, Gemini, DeepSeek, local Ollama, a **backend endpoint** (a Modal server you deployed from the Jarvis page, or a shared URL), or any custom model id. The list is live: the newest models of each provider with **prices per million tokens**, from the open [models.dev](https://models.dev) catalog |
| **Sign-in** | browser OAuth with your own account (where the agent supports it) or an API key, saved once with mode 600 |
| **Skills** | checkboxes over your installed skill library, plus hub install for Hermes |
| **Job** | the instructions / job description, written in `$EDITOR`, typed inline, or taken from a file |
| **Mode** | interactive chat that starts on the job, or an unattended one-shot run |
Every agent gets **its own isolated home** (config, keys, skills, memory)
under `~/.local/share/omarchy-agent-launcher/agents/<name>/`. Your real
`~/.hermes` and `~/.openclaw` are never written; only their skill libraries
are read so you can pick skills. Saved agents can be
relaunched, edited, or destroyed from the same menu.
**An [omarchy.fans](https://omarchy.fans) project.** Open source under the MIT
license; modpunk is the main contributor. The plugin is free and always will
be: agents run on your own machine, in a container, or on a cloud account you
hold. omarchy.fans will also offer **hosted cloud runtimes** for these agents as
a paid convenience, with the price shown in the setup form before you launch
(see [Hosting](#hosting-your-own-or-omarchyfans-cloud) below).
## Install
```bash
omarchy plugin add https://github.com/OmarchyFans/omarchy-fans-agent-launcher
omarchy plugin enable fans.omarchy.agent-launcher
```
The plugin is not yet listed in the Omarchy plugin marketplace; installing by
URL, as above, is the supported path. `omarchy plugin add` clones the repo into
`~/.config/omarchy/plugins/fans.omarchy.agent-launcher/` and lands it
**disabled** so you can read it first. It runs no code, no installer, no sudo.
Enabling adds a robot button to the bar; clicking it opens the **Agent
Dashboard** window (right click: quick agent switcher). Updating from a
version before 0.5, or from 0.6 to 0.7 (which adds the Jarvis page's QML
files), adds and renames QML files, so run `omarchy restart shell` once after
`omarchy plugin update`.
After an `omarchy plugin update` that adds or renames QML files, run
`omarchy restart shell`: the shell's QML engine caches a plugin folder's type
list, and a stale cache surfaces as a bogus "File name case mismatch" error.
Requirements: Omarchy 4.x, `gum`, `jq` (both ship with Omarchy). Then, per
runtime:
- **local** — the agent itself: `hermes` on PATH (see the Hermes install
docs) or `openclaw` (`npm install -g openclaw@latest --allow-scripts=openclaw`).
- **docker** — `omarchy install docker`. Omarchy keeps your user out of the
docker group by default, so the launcher runs `sudo docker` and the
terminal asks for your password.
- **sprite** — the [Sprites CLI](https://docs.sprites.dev/quickstart/). If the
CLI isn't signed in yet, the launcher offers `sprite org auth` (browser, your
Fly.io account) or a pasted API token from <https://sprites.dev/account>,
stored once in `~/.config/omarchy-agent-launcher/secrets.env` (mode 600).
A sprite is a persistent Ubuntu 25.10 VM (user `sprite`, home
`/home/sprite`, Node/Python/git preinstalled) that sleeps when idle and
keeps its filesystem; you pay for CPU and RAM only while it is awake.
### Keybinding and window rule (recommended)
Plugins cannot ship keybindings, so add one line to `~/.config/hypr/bindings.lua`
(SUPER + ALT + A is unbound by default). It summons the dashboard, so the
widget must be enabled:
```lua
o.bind("SUPER + ALT + A", "Agent dashboard", "omarchy-shell shell summon fans.omarchy.agent-launcher '{}'")
```
The dashboard is a Quickshell window (class `org.quickshell`); Omarchy tiles it
unless you add a rule to `~/.config/hypr/looknfeel.lua`:
```lua
o.window({ class = "^org.quickshell$", title = "^Agent Dashboard$" }, { float = true, center = true, size = { 1180, 760 } })
```
Prefer a terminal? The same setup exists as step-by-step prompts:
`omarchy-agent-launcher --popup new` (also the form's "Terminal wizard" button).
Hyprland reloads on save; verify with `hyprctl configerrors`.
The payload picks the page: `'{"tab":"jarvis"}'` (default), `agents`, `new`,
`events`, `notifications`.
### Omarchy menu entry (optional)
Append the snippet in [`extensions/omarchy-menu.snippet.jsonc`](extensions/omarchy-menu.snippet.jsonc)
to `~/.config/omarchy/extensions/omarchy-menu.jsonc` to get an **Agents**
submenu (new / relaunch / manage) in the Omarchy menu.
### `install.sh` (optional helper)
The repo also carries a small helper that does the optional steps for you,
each only after you confirm: symlink the CLI into `~/.local/bin`, add the
keybinding, add the window rule, add the menu entries. It is not run by
`omarchy plugin add`, and it upgrades an older keybinding line in place.
```bash
~/.config/omarchy/plugins/fans.omarchy.agent-launcher/install.sh
```
## Jarvis, the chief of staff
Jarvis is one more agent, saved as `jarvis` with the role *chief of staff*. What
makes it different is what it is told and what it can reach:
- **It runs on your machine.** By default on the **local GPU** (the llama.cpp
server of the Omarchy Help plugin, see below): offline, private, $0. Pick any
other ready backend from the **Runs on** dropdown, or
`omarchy-agent-launcher jarvis setup anthropic`.
- **It sees the whole fleet.** Inside its session the launcher is on `PATH`, and a
bundled skill (`skills/jarvis/SKILL.md`, copied into its home) teaches it
`status --json`, `usage --json`, `backends list`, `delegate`, `result`, `stop`,
`remove`. Jarvis is a *user* of the same CLI the dashboard uses; there is no
second control plane.
- **It hands work to bigger models.** `delegate` creates a worker agent on the
backend Jarvis chooses (a paid API, your ChatGPT or Claude subscription via
browser sign-in, a Modal GPU endpoint, a sandbox), runs the job unattended in
its own window, and keeps the output under the worker's home so
`omarchy-agent-launcher result NAME` (and Jarvis) can read it. Workers carry
`parent: jarvis`, show "for jarvis" on the Agents page, and roll up in usage.
- **It asks before spending.** Its identity file and skill say so: state the
backend and price, then wait for a yes, before deploying a Modal GPU or
delegating to a paid model. You can also tell it to be bolder in its job
description (`omarchy-agent-launcher job jarvis`).
On the **Jarvis** page: **Chat** opens its window (and sets it up the first
time); **Brief** prints a plain status brief computed from the launcher's own
data, no model call; **Ask Jarvis** sends one question to Jarvis' model and shows
the answer inline. From a terminal:
```bash
omarchy-agent-launcher jarvis # chat (sets up on the default backend first)
omarchy-agent-launcher jarvis setup [BACKEND] [MODEL]
omarchy-agent-launcher jarvis brief # agents, blockers, tokens, USD: plain text
omarchy-agent-launcher jarvis ask "what did today cost, and who is blocked?"
printf '%s\n' "Write release notes for v0.7" | omarchy-agent-launcher delegate --backend anthropic --name notes --task-title "Release notes" --job-stdin
omarchy-agent-launcher result notes # the worker's output, when it is done
```
Jarvis on a small local model is a real constraint: a 4B model with a 3
... (truncated)
voice
Comments
Sign in to leave a comment