### The gap

Omarchy ships `omarchy.model-usage` to show Claude Code usage in the bar.

[Omaterm](https://github.com/omacom-io/omaterm) — "think of it as a headless Omarchy" — ships **claude-code as one of its default agents**.

Run both together, which is what the two products are for, and the widget shows `0 tokens · 7 days` while all of the actual usage sits inside the Omaterm container.

### Why it can't work today

The widget already has the right mechanism: `syncMode: "On"` + `syncDir` merges every `*.json` snapshot it finds, and that design is good.

But the snapshot can only be *written* by `Main.qml → localSnapshot()`. So aggregation works between Omarchy desktops and nowhere else. Omaterm is headless — no Quickshell, no bar, no way to publish — so the machine that has the usage has no way to report it, and the machine with the bar has nothing to show.

Same for anyone running claude-code in any other container, over SSH on a dev box, or in WSL, but Omaterm is the case that ships this way by default.

### Concretely

I run claude-code exclusively inside Omaterm on a headless server. My laptop's panel read `0 tokens · 7 days` while 19,052 prompts across 33 active days and ~6.2B tokens sat on the server, invisible.

### Suggested fix

Make the snapshot contract usable from outside the Quickshell process. Either:

1. **Document the envelope**, which is already small and stable:

   ```json
   {
     "schemaVersion": 1,
     "deviceId": "<stable id>",
     "updatedAt": "<ISO8601>",
     "providers": { "claude": { ...provider stats... } }
   }
   ```

2. **Add a flag to the scanner you already ship** — `scripts/claude_usage_scanner.py --emit-snapshot --device-id <id>` — so it prints the whole snapshot rather than only the provider stats.

Option 2 looks like the smaller change: the scanner already emits every field `aggregateSnapshots()` reads, and it is stdlib-only Python, so it runs unmodified inside an Omaterm container. One cron line and a shared folder is then the whole integration.

### This works today, which is the argument for supporting it

I implemented option 2 as a workaround: vendored `claude_usage_scanner.py` into the container, wrapped its output in the envelope, added `providerName` / `ready` / `hasLocalStats`, wrote it to a Syncthing folder on a cron. The bar merged it on the next refresh and now shows both machines aggregated.

Two things from doing it that argue for the snapshot seam specifically rather than syncing the data:

- **The snapshot is ~2 KB. `~/.claude/projects` is 301 MB.** Syncing the source would replicate hundreds of megabytes of full conversation transcripts to every device, and transcripts contain whatever was handled in the session — a disclosure problem as much as a size one. The snapshot is counts with no content, which is the right thing to move between machines.
- The full publish, including scanning 301 MB across 238 files, takes **0.8 s**. Cheap at any interval.

The only reason it needed vendoring is that the scanner isn't advertised as a standalone tool and the envelope isn't documented.

Happy to open a PR for option 2 if that direction is welcome.