A free/open-source launcher and vehicle-data platform for aftermarket Android head units.
README.md

FreeAuto #

A free, open-source launcher and vehicle-data platform for aftermarket Android head units.

Status: pre-alpha, Phase 0. There is no usable app yet — this repository is the skeleton, the contracts, and the rules. See docs/ROADMAP.md for what gets built and when.

Why this exists #

Existing open-source car launchers are shells: they draw a dashboard and stop there. None offers a plugin API, and none can read the car. FreeAuto's bet is the layer nobody has built — a vehicle-bus HAL with trace replay, and a plugin platform — with a deliberately ordinary shell on top. The evidence is in docs/PRIOR-ART.md; read it before assuming this is a duplicate of something.

Toolchain #

Requires JDK 21 and the Android SDK (platform 35, build-tools 35).

A newer JDK (22+) will fail: the Android Gradle Plugin does not support it yet. If java -version reports 25, install 21 and select it for this project.

One-time setup, no Android Studio:

sudo apt install openjdk-21-jdk unzip
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64     # AGP 8.7 rejects JDK 22+
./scripts/setup-toolchain.sh

It installs the Android command-line tools into ~/Android/Sdk (platform 35, build-tools 35.0.0), accepts the licences, and generates the Gradle wrapper. Then add the ANDROID_HOME and PATH lines it prints to your shell profile.

Do not install Gradle system-wide: the wrapper pins 8.13, and apt's Gradle (4.4.1) is far too old for AGP 8.7.

Build and check #

./scripts/check.sh              # docs + guards + build
./scripts/check.sh --no-build   # docs + guards only (no SDK needed)
./gradlew check

scripts/check.sh is the single source of truth for what "passing" means; CI only calls it.

Documentation #

File What it covers
AGENTS.md The contract for anyone — human or agent — writing code here.
docs/ROADMAP.md Phases, exit criteria, risks.
docs/BACKLOG.md The work queue, one packet per session.
docs/ARCHITECTURE.md Modules, the two HAL buses, the plugin API.
CONTRIBUTING.md How to contribute.
AI_POLICY.md Rules on AI assistance. Read it first.

Licence #

The launcher is GPL-3.0-or-later. hal/api and plugin/api are Apache-2.0 so plugins may be closed-source and other launchers may adopt the HAL. Details: LICENSING.md.

Hosting #

Developed in public on Tangled: https://tangled.org/chevindu.com/free-auto.

git clone https://tangled.org/chevindu.com/free-auto                  # read
git clone chevindu.com@tangled.org:did:plc:3lnsq3vsxondwoktul2syctv  # push

Tangled has no GitHub-style Releases or artefact hosting, so APKs will ship from a static Site plus a version index (Phase 5). CI is Spindles, driven by .tangled/workflows/.