Omarchy Singularix

README

<p align="center">
  <img src="docs/img/banner.svg" alt="Omarchy Agent Launcher" width="960">
</p>

<h1 align="center">Your desktop, staffed.</h1>

<p align="center">
  <b>One key. A chief of staff named Rix. A team of AI agents that runs for free on your own GPU and calls in the big models only when you say so.</b><br>
  No config files. No accounts to start. Nothing leaves your machine unless you send it.
</p>

<p align="center">
  <code>omarchy plugin add https://github.com/OmarchyFans/omarchy-fans-agent-launcher</code>
</p>

<p align="center">
  <img src="docs/img/dashboard.png" alt="The Agent Dashboard: every agent, its status, and a Chat button" width="960">
</p>

---

<h2 id="dead-simple-seriously"><img src="docs/img/h-dead-simple-seriously.svg" alt="Dead simple. Seriously." height="44"></h2>

Install the plugin. Press **SUPER + ALT + A**. Rix says hello. That's the setup.

Want an agent of your own? One page, six questions: which agent, where it runs,
which model, how it signs in, which skills, what the job is. Click **Launch**.
No YAML, no dotfiles, no "first configure your environment". If you can fill
in a form, you can run a team.

<h2 id="free-as-in-0"><img src="docs/img/h-free-as-in-0.svg" alt="Free. As in $0." height="44"></h2>

Pick **Local GPU** and your agents run on a model that lives on your graphics
card. No API key. No subscription. No meter. Run one agent or ten, all night,
every night: the bill is zero, and it stays zero.

Rix runs there by default, so your chief of staff costs nothing to keep on
duty.

<h2 id="delegate-the-heavy-lifting-to-whoever-you-trust"><img src="docs/img/h-delegate-the-heavy-lifting-to-whoever-you-trust.svg" alt="Delegate the heavy lifting to whoever you trust." height="44"></h2>

Some jobs deserve a frontier model. Tell Rix, and it hands the task to the
provider you choose: **Anthropic, OpenAI, Grok, Gemini, DeepSeek, OpenRouter**,
your own OpenAI-compatible endpoint, or a private GPU machine on omarchy.fans cloud. It shows you
the model and the price per million tokens first, waits for your yes, and
brings the result back to your desktop with the cost written next to it.

And Rix itself is not chained to your GPU. Run your chief of staff on Claude,
on GPT, on Grok, on anything you can sign in to, and switch whenever you like.
Your agents, your models, your choice, per task.

<h2 id="private-by-design-future-proof-by-choice"><img src="docs/img/h-private-by-design-future-proof-by-choice.svg" alt="Private by design. Future-proof by choice." height="44"></h2>

**Privacy.** A local agent cannot leak what it never sends. Your files, your
keys, your prompts stay on the machine. Every agent gets its own isolated home,
secrets live in a mode-600 file, and the dashboard only ever runs the plugin's
own commands. When you do delegate, you see exactly what goes where, and to whom.

**Future-proofing.** Open-weight models get better every month, and they are
yours to keep: no provider can deprecate them, reprice them, or train on your
data. Build your workflow on agents that run wherever you point them, from your
laptop to a GPU in the cloud, and you will never be held hostage by a pricing
page again.

<h2 id="coming-to-omarchy-fans-cloud-your-own-frontier-gpus"><img src="docs/img/h-coming-to-omarchy-fans-cloud-your-own-frontier-gpus.svg" alt="Coming to omarchy.fans cloud: your own frontier GPUs." height="44"></h2>

Behind the scenes we are building the thing power users keep asking for:
**dedicated GPU endpoints** for the very best open-weight frontier models,
private to you, ready in minutes, billed by the hour with the price on the form
before you launch. Bring your data and **tune the weights** to your work; the
model you shape stays yours. Point Rix at it like any other backend. Same
privacy story as your laptop, with far more horsepower. No accounts to create
until the day you want it; the free runtimes never change.

<h2 id="everything-else-you-get"><img src="docs/img/h-everything-else-you-get.svg" alt="Everything else you get" height="44"></h2>

🖥️ **A dashboard that stays.** Every agent with a status pill, its job, last event, tasks, tokens and USD; one click to chat, stop, edit, remove.

📟 **Sessions that refuse to die.** Close the window, switch workspaces, come back tomorrow: the conversation is still there. Sign-in prompts wait for you.

🚨 **Blockers find you.** When an agent needs a decision, it lands in Notifications and as a desktop toast that opens the right page. A red badge on the bar counts what's waiting.

🧾 **Every event, sortable.** Filter by agent, task, or level; click a column to sort.

🧠 **Costs at a glance.** Prompt and output tokens and USD, today and total, per agent and per task, from the agents' own session stores.

🧭 **Projects with a pulse.** Register a project and see its phase, percent complete, and open blockers.

🐧 **Runs where you say.** Your shell. A Docker container. A hosted machine on omarchy.fans cloud that sleeps when idle.

🎛️ **Looks like Omarchy.** A Quickshell window drawn with the shell's own tokens, so it wears your theme and switches with it.

<p align="center">
  <img src="docs/img/dashboard-rix.png" alt="Rix: brief, ask, tokens and cost" width="470">
  <img src="docs/img/dashboard-notifications.png" alt="Notifications: a blocker waiting for you" width="470">
</p>

**An [omarchy.fans](https://omarchy.fans) project.** Open source, MIT, on GitHub as
[OmarchyFans](https://github.com/OmarchyFans); modpunk is the main contributor.
The plugin is free and stays free. The paid part, when it arrives, is a
convenience: machines and GPUs we run for you, sold under omarchy.fans' terms.

<h2 id="get-it-in-a-minute"><img src="docs/img/h-get-it-in-a-minute.svg" alt="Get it in a minute" height="44"></h2>

```bash
omarchy plugin add https://github.com/OmarchyFans/omarchy-fans-agent-launcher
omarchy plugin enable fans.omarchy.agent-launcher
~/.config/omarchy/plugins/fans.omarchy.agent-launcher/install.sh   # optional: keybinding and menu entry (asks first)
```

`omarchy plugin add` clones the repo 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 dashboard, right-click opens a quick agent
switcher. The plugin is not yet in the Omarchy plugin marketplace; installing by
URL is the supported path. After an update that adds QML files, run
`omarchy restart shell` once.

Then install what your first agent needs:

| You want | You need |
|----------|----------|
| an agent for free, offline | the [Omarchy Help](https://github.com/OmarchyFans/omarchy-fans-help) plugin's local model service, and one `local-server tune` (below) |
| an agent in your shell | [Hermes Agent](https://github.com/NousResearch/hermes-agent) (`hermes` on PATH) or [OpenClaw](https://openclaw.ai) |
| an agent in a container | `omarchy install docker` (the launcher uses `sudo docker`, Omarchy's default) |
| an agent on omarchy.fans cloud | an omarchy.fans account (`omarchy-agent-launcher cloud login`) and `websocat` for the console (`omarchy pkg add websocat`) |
| persistent sessions | `tmux` (ships with Omarchy) |

Everything below is the detail. You don't need it to start.

---

## Under the hood

### The dashboard

A persistent window with six pages, switchable with `1`–`6`, `j`/`k` to move,
Enter to open the selected agent's chat, `r` to refresh, Esc to close.

| Page | What it shows |
|------|---------------|
| **Rix** | the chief of staff: its state and Chat, a plain status **Brief**, an **Ask Rix** box answered by its model, the numbers (prompt and output tokens, USD, total and today), the **backends** work can go to, 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 |
| **New agent** | the one-page setup form |
| **Events** | the event log: filter by agent, task, level, or text; click a column header to sort |
| **Notifications** | open blockers ("NEEDS YOU") and recent warnings; click a row (or press Enter on it) to expand what it is, why it matters, and what's recommended, with buttons named by effect — Dismiss, Hand to Rix, Approve/Decline, Open in Projects, Chat — plus the desktop-notification toggle |
| **Projects** | every registered project with its waterfall phase, percent complete, and open blocker count; double-click jumps to its events |

### The New agent page

| Step | Choices |
|------|---------|
| **Agent** | Hermes Agent (Nous Research) · OpenClaw |
| **Runtime** | local shell · Docker container · omarchy.fans cloud |
| **Model** | **Local GPU (offline)**, Anthropic, OpenAI, OpenAI Codex, Nous Portal, xAI, OpenRouter, Gemini, DeepSeek, Ollama, a **backend endpoint** (a GPU machine on omarchy.fans cloud, or a shared URL), or any custom model id. Lists are live from the open [models.dev](https://models.dev) catalog, with prices per million tokens |
| **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, 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.

### Rix, the chief of staff

Rix is your AI orchestrator, the way J.A.R.V.I.S.\* is to Tony Stark.
Before 0.9 it was called Jarvis: the old profile is renamed to `rix` the first
time the launcher runs (stop a running Jarvis session to let it finish), and
`omarchy-agent-launcher jarvis …` keeps working as an alias for 

... (truncated)