Skip to content

About

Omarchy-styled five-tile UI for Android Auto and Android phones

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Omarchy Auto

Android CI Version Platform Renderer Themes License: MIT

Website Build & Install Android Auto Architecture Credits

An Omarchy-styled car UI for Android Auto and Android phones. The car display is the primary target: a Car App Library NavigationTemplate app. On Android Auto the navigation surface draws the same Omarchy shell as the phone launcher: themed wallpaper, title, footer, and the 4-tile right-side rail (Drive / Media / Comms / Home) around one large stage. The Drive tile is the map and draws turn-by-turn guidance and ETA directly inside the Omarchy stage (while NavigationManager and NavigationAlerts sync trip metadata to the host). Address search opens the host SearchTemplate popup (Search on the action strip or ⌕ SEARCH ADDRESS on the Drive stage); all other workflows (Drive, Media, Comms, and Home themes & car setup) stay inside the Omarchy canvas. The Vehicle tile is hidden until its data source is real.

Omarchy Auto rail-and-stage UI over Tom Ballard's Tokyo Studio artwork

Omarchy Auto with Tom Ballard's Tokyo Studio artwork, credited in CREDITS.md. Synthetic layout render, not real-car footage. Project code is MIT-licensed; the artwork is third-party and credited separately.

Status — public pre-alpha (2026-11-03)

Omarchy Auto is a pre-alpha project prepared for public source release. The phone launcher and Android Auto dashboard are usable on a test device. The routing alpha in navigation-spike/ is a separate experimental app and is not part of the dashboard release yet. The old Linux/Quickshell path remains in shell/ as future work.

Built and checked on this machine:

  • ./gradlew assembleDebug produces the dashboard APKs. The optional routing spike builds separately as :navigation-spike:assembleDebug.
  • Phone launcher runs on an Android 15 emulator and a Samsung S24 FE (Android 17). Theme switch, live MediaSession, live notifications, a GPS fix, stage selection, tile launch, Back return, and portrait/landscape rotation were exercised at 1280×720 and 1080×2400.
  • The layout is a narrow right-side rail of small tiles plus one large content stage. Tap a rail tile to engage it. Media has in-app previous, play/pause, and next controls; the stage OPEN button launches the real app configured in Setup (MEDIA TILE APP).
  • Android Auto 0.1.1 was verified on the owner's real Kia Android Auto screen over USB using Play Internal App Sharing. That build drew the phone-style shell on the car surface. Current source is 0.1.18 (versionCode 19). It keeps the OpenFreeMap dark basemap, the unified MEDIA TILE APP selector, and opt-in crash reporting / SEND LOGS, and it draws the refined Omarchy canvas shell on the Android Auto surface without duplicate host routing cards or gray host list takeovers.
  • The Desktop Head Unit was attempted, but the emulator image's Android Auto app is a Play Store stub and the image has no Play Store.

Live data is ordered as requested: clock + theme, now playing (MediaSession), notifications (NotificationListener), GPS speed, and battery level/charging. The Vehicle tile is hidden behind FeatureFlags.SHOW_VEHICLE_TILE; Torque is intentionally not wired up yet. The phone launcher and the Android Auto surface both draw the title, footer, and rail. The host still supplies the routing card and the action strips.

Build

Prerequisites: JDK 17+ and Android SDK platform 37.

Toolchain: Gradle 9.8.2, AGP 9.5.0, built-in Kotlin (no separate KGP), compileSdk 37, targetSdk 36. CI uses the current action runtimes (checkout@v7, setup-java@v6, setup-gradle@v6, upload-artifact@v7) on ubuntu-26.04; there is no Node/JavaScript app in this repository.

export ANDROID_HOME=/path/to/android-sdk
./gradlew assembleDebug

Tom Ballard’s Tokyo Studio image is tracked as the Tokyo Night theme background, so default builds include it. The private local-override flag is only needed for an owner-specific image:

./gradlew assembleDebug -Pomarchy.includeLocalAssets=true

Default builds exclude local-assets/; that flag is for private overrides, not for Tom’s image. Before a public-track release, run the asset guard:

./gradlew verifyPublicReleaseAssets

It builds the release archives and fails if any local-assets/ file appears in them. APKs:

auto/build/outputs/apk/debug/auto-debug.apk
launcher/build/outputs/apk/debug/launcher-debug.apk
navigation-spike/build/outputs/apk/debug/navigation-spike-debug.apk

They are debug-signed. Verify with:

$ANDROID_HOME/build-tools/37.0.0/apksigner verify --print-certs \
  auto/build/outputs/apk/debug/auto-debug.apk

A clean clone only needs ANDROID_HOME (or local.properties with sdk.dir=...). local.properties is ignored.

Install and run

adb install -r auto/build/outputs/apk/debug/auto-debug.apk
adb install -r launcher/build/outputs/apk/debug/launcher-debug.apk
# Optional routing spike:
adb install -r navigation-spike/build/outputs/apk/debug/navigation-spike-debug.apk

Phone launcher

adb shell am start -n com.omarchy.auto.launcher/.MainActivity

Or choose Omarchy Auto Launcher as the home app. It is a rail-and-stage demo launcher, not a full app drawer.

The app opens with all tiles minimized — including Drive/navigation — so the wallpaper is the first thing you see. Tap a rail tile to expand it; tap the same tile again to minimize. The stage has an OPEN action for real apps:

Rail tile Stage OPEN action
Drive MapLibre/OpenFreeMap map, live GPS, and an OSRM route when navigation is active Google Maps
Media large now-playing/audio art + play/pause selected in Setup: auto, Spotify, YouTube Music, YouTube, ChatGPT, Grok, etc.
Comms large notification list default SMS app
Vehicle hidden until OBD/Torque is real none — deferred
Home clock, theme chips, setup Android Settings

Back from the launched app returns to the launcher. The phone top-right THEME button opens the Home theme picker with ten themes: Tokyo Night, Osaka Jade, Gruvbox, Catppuccin, Kanagawa, Everforest, Nord, Ethereal, Ristretto, and Hackerman. Tokyo Night uses Tom Ballard’s Tokyo Studio image; the other themes load their matching Omarchy background. Setup also offers MEDIA TILE APP, SEND LOGS, CHOOSE BACKGROUND, USE TOM BACKGROUND (private builds), and USE THEME BACKGROUNDS; a custom choice overrides every theme until it is reset. The Android Auto app and the phone launcher are separate packages, so choose the background, media target, and notification text size in each app's Setup if you use both.

A geo: link opened on the phone shows START ROUTE / NOT NOW and does not start guidance until you confirm. The same link delivered to the car service (ACTION_NAVIGATE) starts immediately. While a car session is connected and the host has not reported parked, the phone hides its web stage, custom keyboard, and notification list. A stop in traffic does not unlock them. Ending the session clears that lock. The theme picker stays on the phone; the car action strip does not open it.

Routing alpha (optional)

:navigation-spike is a separate experimental app (com.omarchy.auto.navspike) for evaluating turn-by-turn with Ferrostar and hosted Valhalla. It is not part of the dashboard APK and does not replace the Drive stage yet.

./gradlew :navigation-spike:assembleDebug
adb install -r navigation-spike/build/outputs/apk/debug/navigation-spike-debug.apk
adb shell am start -n com.omarchy.auto.navspike/.SpikeActivity

Use the owner's own Stadia Maps key at runtime for live routing; no API key is embedded. The debug build also has a keyless recorded-route replay:

adb shell am start -n com.omarchy.auto.navspike/.ReplayActivity

Emulator tests prove the native engine, guidance events, off-route detection, and replay UI. Live routing, audible speech, real GPS and the Android Auto head unit remain follow-up validation.

Roadster background

Setup's background picker is the supported path. Tom Ballard’s Tokyo Studio image is tracked at core/src/main/assets/themes/tokyo-night.webp and is the default Tokyo Night background in normal debug and release builds. USE TOM BACKGROUND locks that image across theme changes; USE THEME BACKGROUNDS returns to the active theme’s bundled image. local-assets/ remains optional for owner-specific private overrides with -Pomarchy.includeLocalAssets=true, but it is no longer required for Tom’s image. See docs/ASSETS.md.

Permissions

The phone launcher has a Home-tile SETUP · PERMISSIONS button. The Android Auto APK also has a Setup launcher icon with the same permissions, MEDIA TILE APP target selector, background controls, and SEND LOGS button. The same grants can be made with ADB:

adb shell cmd notification allow_listener \
  com.omarchy.auto/com.omarchy.auto.core.OmarchyNotificationListener
adb shell cmd notification allow_listener \
  com.omarchy.auto.launcher/com.omarchy.auto.core.OmarchyNotificationListener
adb shell pm grant com.omarchy.auto android.permission.ACCESS_FINE_LOCATION
adb shell pm grant com.omarchy.auto.launcher android.permission.ACCESS_FINE_LOCATION

Notification access enables both the Comms tile and MediaSession discovery. Without it the UI says so instead of inventing data.

Android Auto — test install

Current test build: 0.1.18 (versionCode 19). Build the signed AAB with:

./gradlew :auto:bundleRelease

Android Auto does not trust an ADB-sideloaded Car App Library app. The documented test route is Play Internal App Sharing, which installs from Play without a public listing or review. The 0.1.12 AAB includes MapLibre native libraries, the tracked Tokyo Studio Tokyo Night background, the unified MEDIA TILE APP selector in Setup, and SEND LOGS / crash reporting.

The car app declares only the Car App Library NAVIGATION category. It draws into NavigationTemplate through AppManager.setSurfaceCallback. The canvas is the Omarchy shell: themed wallpaper, title, footer, and the 4-tile right rail (Drive / Media / Comms / Home). The Drive tile fills the stage frame edge-to-edge with the map, route, vehicle marker, turn-by-turn guidance card, zoom/recenter controls, and OpenFreeMap / OSM credit. Live speed sits in the footer, and a larger speed box appears bottom-left only while the vehicle is moving. Theme chips and the top-bar THEME button change the palette on the canvas, and SETUP · CAR & DISPLAY OPTIONS inside the Home stage toggles map orientation, notification text size, and wallpaper mode. Media previous, play/pause, and next run from the Media tile. Search is a host SearchTemplate opened from the Drive stage's search button and from the action-strip Search button; the host keeps the keyboard parked-only while voice input and result rows still work while driving. The Comms tile displays notifications in-stage when stationary/parked and locks while moving. Menu on the action strip toggles the Home stage on the canvas rather than pushing a stock host list screen. A NAVIGATE/geo intent lands on the Drive map. The main strip is Search and Menu on every stage; the Drive stage adds Heading while idle, End while a route is active, Reroute when off-route, and Retry on route/location errors. Zoom, recenter and pan are canvas controls inside the Drive stage only; there is no host map strip, so those buttons no longer cover the rail or stay on Media, Comms and Home. The guidance card adds previous/next step buttons, and an off-route warning can be tapped away or recovers by rerouting automatically after three consecutive off-route fixes. Video and the in-stage browser are not drawn on the car surface.

Sideloading caveat: current Google documentation says the Android Auto "Unknown sources" developer option applies to media, messaging, and parked apps, but not to Car App Library apps. There is also a 2026 field report of sideloaded navigation apps disappearing from the AA launcher. Internal App Sharing / an Internal Test Track is the documented private test route. The debug build uses HostValidator.ALLOW_ALL_HOSTS_VALIDATOR; the release build now allows the official AA host certificates. The car path has been seen on the owner's Kia with 0.1.1; use Internal App Sharing for each new build and verify the new surface changes on the car.

Architecture

core/                         shared Kotlin Android library
  Theme.kt                    10 Omarchy palettes + background ids
  Model.kt                    TileId, DashboardState, MediaSnapshot, NotificationItem
  TileRenderer.kt             Canvas renderer; car and phone share the shell
  CarPlatformPolicy.kt        shell on both surfaces; browser and keyboard stay off AA
  DistractionLock.kt          car-session lock until the host reports parked
  NavigationController.kt     OSRM route, lanes, off-route, held ETA
  NavigateIntent.kt           geo and google.navigation parsing
  LiveDataStore / Controller  in-process state and source lifecycle
  MediaWatcher                MediaSessionManager + MediaController
  OmarchyNotificationListener NotificationListenerService
  LocationWatcher             GPS speed + held heading at low speed + last-known seed
  MapFollowPolicy.kt          snapshot refresh while following or panned
  MapSnapshotController       MapLibre/OpenFreeMap snapshots at the stage size
  MapSnapshotStore / Viewport latest map bitmap, size + staleness
  LaunchTargetStore           persisted Media tile app target
  SetupActivity               permissions, media target, backgrounds, logs, phone route confirm
  diag/                       opt-in crash reporting, ring buffer, LogShare

auto/                         Android Auto app (com.omarchy.auto)
  OmarchyCarAppService        CarAppService, foreground live-data service
  OmarchyScreen               root NavigationTemplate, routing card, action strips
  CarHomeScreen               host ListTemplate hub: Map, Search, Media, Notifications, Settings
  CarMediaScreen              driving-safe now playing + play/pause/next/previous
  CarCommsScreen              notification list (titles) + parked-only detail
  PlaceSearchScreen           host SearchTemplate (voice while driving; host keyboard parked-only)
  CarSettingsScreen           host settings ListTemplate (theme, map, phone setup, about)
  NavigationAlerts            guidance notification, separate from the foreground service
  AaosHostUx                  AAOS parked/driving reflection; absent on phones
  CarSurfaceRenderer          Surface.lockCanvas -> TileRenderer shell

launcher/                     phone launcher (com.omarchy.auto.launcher)
  MainActivity                immersive launcher, app intents
  TileView                    shared renderer + hit testing

No Compose or QML runtime is on the car surface. shell/ remains the QML prototype for future Linux work.

What works

Area Status
Five-tile layout, cut-out legends, mono type, 2px borders Phone launcher and the Android Auto shell
Themes 10 Omarchy palettes + matching backgrounds (Tokyo Night: Tom Ballard); phone switch verified
Background Custom image picker, bundled Tom background, or theme backgrounds; custom choice survives theme changes
Bars Phone and Android Auto title and footer. The host still draws the routing card and action strips
Clock Live; idle redraws align to the next minute, media progress stays 1 Hz
Battery Footer icon + percentage; charging accent; state-driven redraw
Media Live MediaSession metadata/art/progress + MEDIA TILE APP target selector in Setup for both packages
Notifications Live listener + existing-notification load; OTP/2FA and banking filter; optional package allow-list; bodies not logged
GPS speed Location/GPS speed; launcher got a fix at 0 km/h on the bench
Vehicle Hidden by FeatureFlags.SHOW_VEHICLE_TILE until OBD/Torque is real
Right rail + large stage Phone launcher and the Android Auto shell. Phone verified on emulator and phone; the car shell has not had a new head-unit pass
Rotation Portrait/landscape reflow verified on the S24 FE
Media play/pause/previous/next Phone launcher and the Android Auto Media tile, both via MediaTransport
AA NavigationTemplate + SurfaceCallback Themed shell on the map surface. 0.1.1 shell was seen on a Kia; this restoration has no new head-unit pass
AA host cards and strips Routing card, travel estimate, search (host keyboard parked-only, voice while driving), in-car hub with media/notifications/settings; canvas zoom/recenter/pan on Drive only; no host map strip; unit-tested
Turn-by-turn Public OSRM demo, roundabout exit, lane arrows when OSM has them, auto-reroute after three off-route fixes, previous/next step buttons, ETA held across small changes
Real map OpenFreeMap dark style via MapLibre snapshots on the phone Drive stage and the AA map surface, plus a live location puck
Diagnostics Opt-in crash queue + SEND LOGS share button in Setup
Routing alpha Separate Ferrostar + hosted Valhalla app; emulator replay/UI tests pass; live key/car validation pending
Notification detail Full-screen card overlay; S/M/L text size in Setup; phone verified
Stage OPEN + Back Verified with YouTube Music/Maps path
README hero docs/img/hero-tokyo-night.webp (Tom Ballard Tokyo Studio render, credited)

Verification

  • ./gradlew assembleDebug — passes; both APKs are debug-signed.
  • Emulator: Android 15 Google APIs, API 35.
  • Phone launcher: 1280×720 landscape and 1080×2400 portrait screenshots.
  • Car previews: rendered at 1920×720, 1280×720, and 800×480; rail, full-bleed top bar, footer, 10-theme grid, and Drive map fit without clipping. Synthetic renders are captioned and are not car footage.
  • Theme button changed Tokyo Night → Gruvbox/Hackerman.
  • Background picker: selected an image, enabled it, changed the theme, and confirmed the custom image survived; reset to theme backgrounds.
  • Notification text S/M/L applied to Comms rows; LARGE and SMALL previews checked at 800×480.
  • Media tile showed a real MediaSession from YouTube Music playing a local test WAV; progress/play state updated.
  • Comms tile showed a real system notification posted with cmd notification plus existing notifications after listener reconnect.
  • Tile-to-YouTube-Music and Back-to-launcher verified.
  • GPS provider returned a fix; speed read zero while stationary.
  • Android Auto host: 0.1.1 verified on the owner's real Kia screen, when the surface drew the phone-style shell. This shell restoration and the Ferrostar routing alpha still need that car pass.
  • Unit tests on this tree: ./gradlew :core:testDebugUnitTest :auto:testDebugUnitTest (65 tests, 0 failures on 2026-11-10). Those tests do not drive a head unit.
  • Routing spike: :navigation-spike:assembleDebug, JVM tests, lint and native emulator tests pass. Live Stadia routing, audible speech, real GPS and the Android Auto head unit remain unverified.
  • Real map: MapLibre snapshot of https://tiles.openfreemap.org/styles/dark with a live location puck and OpenStreetMap/OpenFreeMap attribution. Route geometry is a separate OSRM request, drawn on top of that snapshot. It has not been driven on a head unit.

Limitations

  • The restored Android Auto shell and its OSRM guidance still need a real-car acceptance pass. 0.1.1 was verified there with the older shell. A navigation-only app that draws a custom shell can fail Play / Android Auto quality review. That risk is accepted for this build.
  • Sideloaded Car App Library availability is subject to Google's host policy; use Play Internal App Sharing for the trusted install.
  • The Android Auto canvas draws the rail and the drive-stage guidance card. It does not draw the custom keyboard or the web stage. Notification bodies stay hidden until the host reports parked; the host list shows titles while driving. The phone hides the same distracting paths until the host reports parked or the car session ends.
  • Routing uses the public OSRM demo (router.project-osrm.org) and address search uses Photon, then Nominatim. A route sends the current fix and the destination to that demo. There is no toll exclusion and no posted speed limit. Lane arrows appear only when the response includes turn lanes. Driving more than 40 m off the line for two fixes shows an off-route message; a third consecutive fix rebuilds the route from the current position (15 s cooldown). The warning can also be tapped away, and the guidance card has previous/next step buttons. The displayed ETA holds until the step changes or the estimate moves by about 30 seconds.
  • NavigationTemplate still requires an action strip. Search and Menu are always present so the driver can never be stranded. Heading, Reroute/Retry and End appear only while the canvas is on the Drive stage. Map zoom, recenter and pan are canvas controls in that stage; there is no host map action strip.
  • The routing alpha has not been validated with a live Stadia key, audible speech, real GPS, or a real Android Auto head unit. Its replay tests are not a claim of fresh routing quality.
  • Media controls send play/pause, previous, and next through MediaController.
  • Notification privacy is documented in docs/NOTIFICATION-PRIVACY.md; OTP/2FA and banking filtering plus the optional allow-list are implemented.
  • Redraw budget and remaining 30-minute car measurements are documented in docs/PERFORMANCE.md.
  • Location privacy: when the map is showing, the phone's location is sent to OpenFreeMap tile servers to render the basemap. Starting a route also sends the origin and destination to the public OSRM demo, and address search sends the query to Photon or Nominatim. Omarchy Auto does not store a location history. There is no map-off switch yet.
  • Vehicle data is mock and the tile is hidden until OBD-II; Torque is not wired up.
  • The Tokyo Studio artwork is included in the README, public site, and app builds with Tom Ballard’s permission and credit. Other Omarchy-derived theme backgrounds still need per-image rights checks before a public release.
  • No public Play listing, store review, or production launch yet. The public source release is being prepared; see the publication gates below.
  • Linux/Quickshell remains future work; it is not in the APKs.

Publication gates

Before flipping the repository or app to public:

  • Confirm the media rights for the nine Omarchy-derived theme backgrounds (omarchy-jnn.7). Tokyo Studio is cleared with Tom Ballard's permission.
  • Complete the real-car dashboard and routing-alpha passes and capture dated evidence.
  • Finish the Android Auto host allowlist check and the public Play listing.
  • Keep the routing alpha keyless by default; live routing needs each tester's own Stadia key or a separately designed server.
  • Review THIRD_PARTY.md, CREDITS.md and docs/ASSETS.md in the public tree.

License

Project code and original assets are released under the MIT License. See CREDITS.md for Tom Ballard's Tokyo Studio artwork, Omarchy theme credits, and third-party asset notes. The MIT license does not relicense third-party artwork. AndroidX / Car App Library is Apache-2.0. Full component notices are in THIRD_PARTY.md.

About

Omarchy-styled five-tile UI for Android Auto and Android phones

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages