Kolahal

#+TITLE: Kolahal #+CAPTION: Kolahal logo [[file:site/public/favicon.svg]] #+END_EXPORT #+SUBTITLE: A keyboard-first terminal launcher for Android

Kolahal (=com.mtwabpin.kolahal=) is a terminal-style home screen for Android 9 and newer. Type a few letters and press Enter to open an app or run a command; every command and its output is kept in a log. It reads RSS and Atom feeds, keeps todos, notes and reminders, controls media and the device, runs your own scripts in Lua 5.4 or JavaScript (QuickJS), and works with the work profile and private space.

#+begin_quote Kolahal is developed with AI assistance. The developers review every change except the tests. #+end_quote

• Status: under review

Kolahal's code is still under review. It is young (0.4), parts of it were written with AI assistance, and the review of the codebase as a whole isn't finished. Expect rough edges and changes between versions, keep a [[https://mtwabpin.github.io/kolahal/guides/backup/][backup]], and report what you find.

• Get it

• APK: the [[https://github.com/mtwabpin/kolahal/releases/latest][latest release]] on GitHub has the full build, with every feature, and the Play build for Google Play. The [[https://mtwabpin.github.io/kolahal/getting-started/install/][install guide]] explains how to sideload them. The full build supports self-updating. Important: Google Play Protect blocks sideloaded apps (installed from a browser, a messaging app or a file manager) that declare an accessibility service or notification access, in India and some other countries. Both builds declare notification access, which shows your notifications in the log, and the full build also has an accessibility service, which only locks the screen.

To install, turn off Play Store → profile → Play Protect → ⚙︎ → Scan apps with Play Protect, then turn it back on. Or use adb install. Once Kolahal is on Google Play, installing it from there avoids the block.

• Google Play: in a closed test; [[https://mtwabpin.github.io/kolahal/getting-started/play-testing/][join it]] to install Kolahal from the Play Store. The Play build leaves out the screen lock, which needs an accessibility declaration on Play, calls in the log, which Play's policy doesn't allow, and =update=, as apps on Play update only through Play.

• Documentation

The user guide is at [[https://mtwabpin.github.io/kolahal/][mtwabpin.github.io/kolahal]].

• Getting started :: [[https://mtwabpin.github.io/kolahal/getting-started/install/][Install]] · [[https://mtwabpin.github.io/kolahal/getting-started/setup/][First run & setup]] · [[https://mtwabpin.github.io/kolahal/getting-started/basics/][Basics]]
• Guides :: [[https://mtwabpin.github.io/kolahal/guides/apps/][Apps]] · [[https://mtwabpin.github.io/kolahal/guides/notifications/][Notifications]] · [[https://mtwabpin.github.io/kolahal/guides/media-and-controls/][Media and device controls]] · [[https://mtwabpin.github.io/kolahal/guides/feeds/][Feeds]] · [[https://mtwabpin.github.io/kolahal/guides/people/][People]] · [[https://mtwabpin.github.io/kolahal/guides/productivity/][Productivity]] · [[https://mtwabpin.github.io/kolahal/guides/web-and-calculator/][Web, calculator & units]] · [[https://mtwabpin.github.io/kolahal/guides/widgets/][Widgets]] · [[https://mtwabpin.github.io/kolahal/guides/gestures/][Gestures]] · [[https://mtwabpin.github.io/kolahal/guides/themes-and-settings/][Themes & settings]] · [[ & moving devices]] · [[ profile & private space]]

• Help

• For questions, ideas and help from other users, join the [[https://discord.gg/3D25w6gXR5][Discord server]].
• To report a bug or request a feature, [[https://github.com/mtwabpin/kolahal/issues/new/choose][open an issue]] with the bug report or feature request form.

• Working on Kolahal

#+begin_src sh ./gradlew :app:assembleRelease # the full APK ./gradlew :app:bundlePlay # the Google Play bundle (-PplayApk :app:assemblePlay: its APK) ./gradlew :app:testDebugUnitTest # JVM tests #+end_src

• [[file:docs/developing.org][docs/developing.org]]: building, the architecture, the repository layout and common changes.
• [[file:docs/codebase-guide.org][docs/codebase-guide.org]]: a guided tour of the code, how its parts fit together and why.
• [[file:docs/release/README.org][docs/release/]]: how releases are built, signed and published, on GitHub and Google Play.
• [[file:site/README.md][site/README.md]]: the website, built with Astro and Starlight from =site/=.

• AI policy

Kolahal is built with AI assistance, and contributions may use it too. Vibe coding (changes nobody has read, understood or tested, prompted until something seemed to work) isn't accepted.

AI assistance is fine as long as you stay the author:

• You read every line you send, and can explain what it does and why in review.
• You built it and tried it on a phone or the emulator; the tests pass, and new behaviour has tests.
• You say in the pull request what the AI did.

Pull requests and issues that look generated and unchecked (large unexplained changes, calls to functions that don't exist, claims nobody verified) are closed without review. The same goes for bug reports: reproduce the problem yourself first.

• Tests

JVM unit tests (=app/src/test=) cover pure logic: parsing, ranking, layout maths and formats. On-device tests (=app/src/androidTest=) cover the script engines and sandbox, commands, storage and backup, and the home and settings screens. The on-device ones install the debug build (package suffix =.debug=) and change its settings; run them on an emulator.

Coverage: 90.8% of the app's code lines (0.4.15), counting a line when either kind of test runs it. It is measured at each release with JaCoCo, on an Android 16 emulator:

#+begin_src sh ./gradlew -Pcoverage :app:createDebugUnitTestCoverageReport :app:createDebugAndroidTestCoverageReport perl tools/coverage.pl # the total, and each package #+end_src