- Shell 61%
- Kotlin 39%
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 -versionreports 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/.