OmaRivian

A read-only Rivian status widget for the Omarchy Quattro bar. Click the Rivian-inspired mark to see your vehicle's configured artwork, battery and range, charging, closures and locks, cabin climate, optional location, software, odometer, and last-contact information.

[!WARNING] OmaRivian uses Rivian's private, unsupported owner API. It is not affiliated with or endorsed by Rivian and may stop working when that API changes. Although OmaRivian ships no vehicle-control operations, the account session it stores may have broader authority. Protect your desktop keyring accordingly.

Project status

OmaRivian is an early-development 0.x release. Expect continued testing and interface or API changes while marketplace verification and broader vehicle coverage progress.

R2 telemetry is validated against the maintainer's vehicle. The legacy R1 path is intentionally retained, but the maintainer does not own an R1 and cannot fully validate it firsthand. R1 owners are especially welcome to test the widget and report model/year, missing fields, or regressions through GitHub issues.

Highlights

• Compact bar panel inspired by mobile vehicle widgets
• Automatically inherits the user's active Omarchy colors, typography, spacing, and display scaling
• Rivian-provided artwork matching the vehicle model, paint, wheels, and configuration
• Multiple-vehicle switcher
• Honest stale and offline states with last-known data
• Read-only request allowlist—no unlock, climate, charging, or wake commands
• Password and one-time code entered in a terminal, never in QML or process arguments
• Tokens stored in Linux Secret Service, not shell.json or plaintext files
• Location disabled by default and omitted entirely from the local state file

Screenshots

Bar widget

The compact charge label is optional. Enable it from the settings gear in the panel header, through Omarchy's bar settings, or run:

omarchy bar set io.github.ttiimmaahh.omarivian showChargeInBar true --json

Vehicle panel

All visible identity, location, and telemetry values in these screenshots are synthetic demo data.

Requirements

• Omarchy 4 with the Quattro shell
• Python 3.10+
• secret-tool from the libsecret package
• An unlocked Secret Service provider such as GNOME Keyring or KWallet
• A Rivian owner account with at least one vehicle

No Python packages are required; the helper uses only the standard library.

Install

Install directly from GitHub:

omarchy plugin add https://github.com/ttiimmaahh/omarivian.git --enable

The widget defaults to the right side of the bar. Click its Rivian-inspired mark, open the settings gear in the panel header, and choose Link account. OmaRivian opens a terminal for email, hidden password, and MFA input. The password and MFA code are never saved.

To run linking manually from the plugin directory:

./tools/omarivian link

Usage

• Left/right click: open or close the panel
• Middle click: refresh status
• R: refresh while the panel is open
• Escape: return to vehicle details from settings, or close the panel from details
• Tab / Shift-Tab: switch between adjacent Omarchy panels

Use the in-panel vehicle pills to switch cars. The selected vehicle alone is refreshed, reducing calls to the unofficial API.

Configuration

The percentage and location options are available from the settings gear in the panel header. All options can also be configured from Omarchy's bar settings or set on the widget entry in ~/.config/omarchy/shell.json:

Location is sensitive and disabled by default, including after a clean installation. Enable it from the settings gear in the panel header, through Omarchy's bar settings, or run:

omarchy bar set io.github.ttiimmaahh.omarivian locationEnabled true --json

Changing location from the panel automatically refreshes the vehicle. When location is disabled, coordinates are not requested and are removed from ~/.local/state/omarivian/state.json. When enabled, coordinates are sent to OpenStreetMap only if Open in maps is clicked. If the panel shows Not reported, Rivian did not provide a location during that refresh; a sleeping or offline vehicle may report it after reconnecting.

Security and privacy

The QML panel invokes a narrow local helper. That helper contains only:

• Authentication operations required to establish a session
• getUserInfo to enumerate vehicles
• GetVehicleState to read an allowlisted set of legacy R1 status fields
• A bounded, read-only ParallaxMessages snapshot for missing R2 lock, closure, power-state, cabin-climate, and opt-in location fields
• getVehicleImages to discover Rivian's configured, display-only vehicle render

There is no generic query CLI and no vehicle command implementation. Session tokens are stored under the omarivian application label through Secret Service. Each scheduled or manual refresh checks the access token's expiry before requesting data and renews it if expired or within five minutes of expiry. This avoids relying on Rivian's error labels: expired tokens can produce a generic INTERNAL_SERVER_ERROR rather than an authentication error. Decoded expiry is only a scheduling hint, not authentication proof, and is never written to the status cache.

Explicit authentication failures still trigger renewal and one retry, including for opaque tokens without readable expiry. Each poll performs at most one renewal and saves rotated credentials immediately, before further API work. Polling continues while the panel is closed; after downtime, the next poll renews an expired access token. No separate daemon or saved password is required. A revoked or expired refresh token still requires Link account; temporary network/keyring failures can recover on later polls. Last-known data and local artwork remain available, marked stale, including after a shell restart.

Authenticated HTTP requests reject redirects and cross-origin responses, and network, keyring, state, and preference reads have strict byte limits.

The sanitized state cache is mode 0600 and contains vehicle status plus identity summaries; full VINs are never written. Vehicle artwork is downloaded only from Rivian-controlled HTTPS hosts into ~/.cache/omarivian/vehicle-artwork, using mode 0700 directories and mode 0600 image files. QML loads the local file and never contacts Rivian directly. Unlinking removes that artwork cache.

OmaRivian does not collect analytics, operate a relay, or retain location history. Avoid posting state files or screenshots containing location information.

Unlink and remove

Unlink, under the settings gear in the panel header, requires confirmation and deletes the saved keyring session. You can also run:

./tools/omarivian unlink
omarchy plugin remove io.github.ttiimmaahh.omarivian

Removing the plugin does not automatically delete Secret Service entries or the local status cache; unlink first. To erase the non-secret cache afterward:

rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/omarivian" \
       "${XDG_CACHE_HOME:-$HOME/.cache}/omarivian"

Development

Omarchy scaling conventions

The shell derives typography and layout density from the user's theme and display preferences. QML contributions should:

• Use Style.font.* for text and icon sizes.
• Use Style.space(...) or semantic Style.spacing.* tokens for dimensions, margins, padding, gaps, controls, and hairlines.
• Use Style.bar.* for bar geometry and fittedContentWidth / fittedContentHeight for panels.
• Avoid manual device-pixel-ratio scaling and raw visual pixel sizes; reserve unscaled numbers for ratios, opacity, timing, and source-image crop fractions.

An importable, secret-free Postman collection and example environment for the same read-only API surface are in postman/. Rivian's private owner API uses its own GraphQL session/token flow rather than a documented OAuth 2.0 service.

GitHub Actions runs the Python and JavaScript tests plus Omarchy manifest validation and QML linting on every pull request, push to main, and release tag.

omarchy plugin validate .
qmllint -I "$OMARCHY_PATH/shell" BarWidget.qml Panel.qml
python3 -m unittest discover -s tests -p 'test_*.py'
node tests/model.test.js

For local shell testing, use the checkout helper. It validates the plugin, replaces an installed release with a symlink to this Git checkout, waits for Omarchy discovery, and enables it so saved source changes hot-reload:

./tools/local-plugin install
./tools/local-plugin status

Remove only the local symlink, or replace it with a clean clone pinned to the latest stable release tag:

./tools/local-plugin uninstall
./tools/local-plugin release
# Or validate a specific release:
./tools/local-plugin release v0.2.0

Switching modes preserves Secret Service credentials and cached state. Use the panel's Unlink action separately only when intentionally testing clean account onboarding.

To compare what Rivian actually returns against what the panel decides, dump the raw responses for the linked account:

./tools/dump-sample-data
# Include coordinates in the dump:
./tools/dump-sample-data --location

This writes vehicles.json, vehicle-state.json, parallax-state.json, and the derived normalized-vehicle.json to sample-data/. The dump is unredacted account data—VIN, vehicle identifiers, and optionally coordinates—so the directory is git-ignored and written with owner-only permissions. Nothing in the shipped plugin reads it.

Credits

The API behavior was independently implemented using public, unofficial community references including rivian-python-client (MIT) and Riviamigo (GPL-3.0) as documentation. No source from Riviamigo is included in this repository.

License

MIT. See LICENSE.