omarchy-agents-grok

Stock Omarchy draws an Agents panel from JSON records in ~/.local/state/omarchy/agents/usage/. Claude, Codex, and Fireworks ship a collector. Grok does not. This repo is the Grok collector, the Grok marks, and the live sd.agents panel that shows them.

make test
make install-user
systemctl --user enable --now omarchy-agent-usage-grok.timer omarchy-agent-usage-grok.path

make install-user copies the collector to ~/.local/lib/omarchy/, links it onto ~/.local/bin, symlinks ~/.config/omarchy/plugins/sd.agents at plugin/sd.agents, and installs the user units.

The shell does not follow that symlink. After a QML edit, restart the shell with omarchy-restart-shell. omarchy-shell shell rescanPlugins often keeps the previous component.

Write a record by hand with:

omarchy-agent-usage-grok --write
omarchy-agent-usage-grok --force --write

--force ignores the session-scan cache. --limits-only reuses a scan up to 15 minutes old and still probes billing. --write stores grok.json. With no flag the command prints the record.

• Session tokens from ~/.grok/sessions turn completions, last 7 days. GROK_HOME overrides that directory.
• Weekly credits from GET {base}/billing?format=credits. The base is GROK_CLI_CHAT_PROXY_BASE_URL or https://cli-chat-proxy.grok.com/v1. That call does not send a prompt. If it fails, the collector uses the newest open reading in ~/.grok/logs/unified.jsonl.
• User timer every 2 minutes (extras/systemd/), plus a path unit on ~/.grok/active_sessions.json. Both run omarchy-agent-usage-grok --write.
• Scan cache of 20 seconds unless you pass --force or --limits-only.

plugin/sd.agents/ is My Agents (sd.agents), stock omarchy.agents as of Oct 2026 (one list of every agent, limits first) plus the extras below. Details are in plugin/sd.agents/README.md.

• Expand an agent by clicking its name, or Enter on its mark. Its details open under its limits. Agent order is stock's: drag a mark, or Ctrl+Up/Down.
• All agents at the bottom sums every agent when at least two have data. Expand it for the combined chart, the plan total, eight models, and Export.
• Days under 10M hidden. The day header is the average of the days that remain. A span longer than a week uses M/D.
• Allowance estimate for each week or month meter (Weekly allowance ≈ 868M/week), in the expanded details. Cursor's Other Models meter and All agents skip it. Once the meter has ticked twice a whole point apart, the estimate is the tokens between those ticks over the percents between them, so it stops jumping each time a whole-percent meter moves. Readings live in ~/.local/state/omarchy/agents/meter-ticks.json.
• Export button in All agents copies JSON draft Usage Bench reports to the clipboard: tokens, meter percents and token mix per meter. Nothing is sent anywhere. Scripts can get the same JSON with omarchy-shell sd.agents exportReports.
• Monthly price under Weekly Total. The line under the field is that price × 12/52, over the Saturday–Friday token total ($75.00 this week · $0.058 / 1M). All agents adds every priced plan, and 0 counts.
• Grok mark is assets/grok.svg (white) or assets/grok-light.svg on a light bar. assets/grok.txt is an unused braille transcription.
• Cursor has marks here and no collector. A cursor.json from elsewhere still gets a section.

The panel's own refresh is refreshIntervalSec (default 900). That runs omarchy-agent-usage-update for every enabled agent. It is separate from the 2-minute Grok timer.

• patches/ is an old Grok-only delta. Trust plugin/sd.agents/ when they disagree.
• extras/ is the local timer, path unit, and login hook.

omarchy-agent-usage-update runs every omarchy-agent-usage-* binary in $OMARCHY_PATH/bin. The smallest Grok PR is the collector plus the two marks:

1. bin/omarchy-agent-usage-grok
2. shell/plugins/agents/assets/grok.svg
3. shell/plugins/agents/assets/grok-light.svg
4. A row in shell/plugins/agents/README.md

Leave plugin/sd.agents/ and extras/ out. The stock widget already shows Grok (upstream added its own collector in Oct 2026). Do not copy this tree into an Omarchy checkout until you are opening that PR.

MIT. See LICENSE.