Termux Launcher turns a real Termux session into your Android home screen. You keep the terminal, packages, files, and sessions you expect from Termux, then gain a touch-friendly app dock, fast search, wallpaper-aware styling, an optional built-in keyboard, and an authenticated shell bridge to Android.

The shortest path to a working launcher

1. Read Install & first run and choose the correct edition.
2. Open the app once and let the Termux bootstrap finish.
3. Walk through the in-app Quick start tour.
4. Try the dock and % app search before changing anything.
5. Set it as your Home app only when the terminal and your must-have apps work.

The core launcher does not require Shizuku, notification access, tmux, local AI, or a custom shell. Add those one at a time later.

A first launch that explains itself

New installations open a seven-step, scrollable tour after the Termux bootstrap is ready. It introduces the terminal Home, app search, Material styling, the optional fish/tmux workspace, LauncherCtl, and the optional Shizuku and TAI layers before Android asks you to make any long-term choices.

Existing installations are not interrupted after an upgrade. Replay the tour at any time from Settings → Quick start tour.

What you can grow into

Required, recommended, optional

• Required: one Termux Launcher main APK.
• Recommended: the matching Termux:API and Termux:Styling forks if you use those add-ons.
• Helpful: Unexpected Keyboard if you prefer a mature external terminal keyboard.
• Optional: tmux workspace, Shizuku, notification access, TAI models, MCP clients.

Choose your next page

• Feature tour shows the complete surface with current screenshots.
• The launcher surface teaches the gestures and icon actions.
• Recreate the shell workspace explains the live fish/tmux setup without copying private aliases or keys.
• launcherctl bridge is the beginner entry to shell-to-Android automation.
• Troubleshooting starts with safe checks and escalates only when needed.

Tip: the Quick start tour is always available again under Settings → Quick start tour.

This guide gets you to a safe, reversible first launch. Do not set Termux Launcher as Home until the bootstrap finishes and you can reopen your important apps.

1. Pick the correct edition

The com.termux edition cannot coexist with official Termux because both use the same Android package identity. Back up anything important before replacing an existing installation. If you are unsure, begin with the VAJ edition and read the release notes.

2. Install one matching build family

1. Download the Main APK from the project’s Releases.
2. If you use Termux:API or Termux:Styling, download the matching forks from the same edition family.
3. Do not mix official add-ons, old forks, or APKs signed with a different key. Android will reject shared-UID/signature mismatches.

You only need the Main APK to try the launcher.

3. Let first-run setup finish

Open Termux Launcher normally. The first launch extracts the Termux bootstrap; wait until a prompt appears. The new Quick start popup opens after a genuinely new bootstrap completes, not merely after an app upgrade.

The tour covers:

• the terminal home screen;
• touch and terminal app search;
• appearance and built-in keyboard controls;
• the optional fish/tmux workspace;
• LauncherCtl, Shizuku, and TAI;
• where to choose the default Home app.

Tap Skip if you already know the launcher. Replay it later from Settings → Quick start tour.

4. Verify the basics before changing Home

At the prompt, run:

launcherctl status
launcherctl apps

Then check these touch paths:

1. Tap one pinned app and return Home.
2. Type %settings without pressing Enter; confirm the dock filters.
3. Long-press an app icon; dismiss the actions without changing anything.
4. Long-press the terminal and open More → Settings.

5. Set it as Home

Use either Android’s default-app settings or:

Settings → Apps & Access → Set as home launcher

Keep a fallback route in mind while learning: Android Settings → Apps → Default apps → Home app.

If you plan to switch the Termux package manager from pkg/apt to pacman, do it before making the launcher your default Home. Recovery is easier while another Home app is still selected.

First ten minutes

• Leave Material colors and the default dock enabled.
• Learn % search and the A–Z row.
• Decide whether to use the built-in keyboard or an external one.
• Grant notification access only if you want dots, inline notification views, media, or LauncherCtl notification commands.
• Skip Shizuku and TAI until the core launcher feels stable.

Updating later

Install the newer matching APK over the existing app. Do not uninstall just to update; uninstalling may remove app data.

After an update:

termux-reload-settings
launcherctl update-scripts

launcherctl update-scripts refreshes repo-owned helpers with timestamped backups. It does not overwrite ~/.tmux.conf.

This is the current Termux Launcher surface, captured live on the Nothing phone used for development. Start with the core launcher; every integration later on this page is optional.

Watch the first-launch tour

Terminal-first Home

Your active terminal is the wallpaper, workspace, and control surface. Normal Termux sessions, packages, files, selection, URLs, and Extra Keys remain available. tmux can keep sessions, panes, and status widgets alive across app switches.

Open and organize Android apps

• Tap pinned icons for one-touch launch.
• Type % plus a name to filter from terminal input.
• Drag across A–Z to narrow the catalog; swipe upward to launch the highlighted result.
• Long-press icons to pin, move, group into folders, choose shortcuts, change icons, open app info, or uninstall where Android allows it.
• Enable a Most used page if you prefer learned ranking next to explicit pins.
• Discover cloned/work-profile launch targets when Android exposes them to the launcher.

The live recording below shows % filtering followed by the long-press menu. No app is opened or changed.

Style one connected surface

Wallpaper-derived Material colors can flow through the terminal, ANSI palette, cursor, dock, built-in keyboard, and tmux plugin. Appearance controls include theme mode, wallpaper handling, terminal opacity, blur, glass opacity and grain, dock height, icon count, labels, icon normalization, monochrome/material icons, shadows, and icon packs.

Pick your keyboard

Use any Android keyboard, or enable the launcher’s built-in terminal keyboard. The built-in path supports system/custom themes, per-key color-scheme editing, dock matching, drag-to-resize sizing, typography, haptics, key sounds, optional extra keys, and custom layout files.

Recreate the live shell workspace

The public setup mirrors the safe foundation of the live device:

• fish with an empty greeting and optional tmux auto-attach;
• Oh My Posh using the termux-launcher theme;
• eza aliases and zoxide navigation;
• tmux with the Termux Launcher plugin;
• wallpaper Material colors and status helpers;
• optional Shizuku-backed btop wrappers.

Private aliases and API keys are intentionally not copied. See Recreate the shell workspace for the guarded installer and a file-by-file explanation.

Bridge the shell and Android

launcherctl exposes a localhost, bearer-token-authenticated API and friendly shell commands. It can launch apps, read resource snapshots, expose media and notification state after access is granted, stream events, restart its bridge, generate client configs, and route confirmation-gated agent tools.

launcherctl status
launcherctl resources
launcherctl launch maps
launcherctl client-config codex

Bind safe calls to tmux keys or use the MCP stdio bridge with a compatible client.

Optional privileged and AI layers

• Shizuku: optional lock-screen backend, privileged shell, richer system helpers, and btop integration.
• TAI / Termux AI: on-device LiteRT-LM and MNN model hosting, catalog downloads/imports, language and embedding roles, and OpenAI/Ollama-compatible localhost APIs.
• Agent & MCP: shared LauncherCtl tool registry with explicit risk levels and confirmation gates.
• Termux add-ons: matching API and Styling forks extend normal Termux workflows.

TAI marks its sensitive settings window secure, so Android screenshots of endpoint/token details are intentionally blocked. The docs never ask you to disable that protection.

Capability checklist

The terminal is Home. Launcher controls sit around it and disappear back into the same Material surface instead of replacing your shell with a separate app drawer.

Read the screen from top to bottom

1. Status and terminal: your Termux or tmux session.
2. Apps row: pinned, ranked, or filtered launch targets.
3. A–Z row: direct catalog filtering and launch gestures.
4. Navigation/Extra Keys row: configurable terminal and tmux controls.
5. Keyboard: Android IME or the optional built-in keyboard.

Apps row

Tap an icon to launch it. Swipe between dock pages when more icons are available.

Long-press an icon for the actions Android and the current item support:

• pin or unpin;
• move within the dock;
• move into or out of a folder;
• launch an app shortcut;
• change or reset its icon;
• open app info;
• uninstall.

Long-press empty dock space to open list-based pin and folder management. Your explicit pins stay under your control even when usage ranking is enabled.

A–Z row

• Drag horizontally to filter by initial letter.
• Keep dragging to preview the focused result.
• Swipe upward from a letter to launch the highlighted app.
• Double-tap the row to lock only after choosing a lock method under Apps & Access.

The lock method can be off, accessibility-backed, or Shizuku-backed depending on your setup. Normal launcher use does not need either privileged option.

Search from terminal input

The default split character is %. Type it before an app name without pressing Enter:

%maps

Backspace clears the query. Change the split character under Settings → Apps & Access if % conflicts with your shell habits.

Notifications and media

With notification-listener access, the launcher can show notification dots, controlled notification popups/replies, current media, and the corresponding LauncherCtl data. Without that permission, the dock and app launching still work normally.

Never grant notification access just because a setup guide mentions it; grant it only if you want those features.

Settings map

Open Settings by long-pressing the terminal and choosing More → Settings.

Live wallpapers can prevent reliable blur capture. Set blur to zero for clear glass, or use a static/launcher-managed wallpaper when tuning the frosted dock.

launcherctl is the launcher’s command-line bridge to Android. The app installs it when the launcher starts and serves an authenticated API on localhost. Begin with read-only commands; add permissions and automation only when you need them.

Confirm it is ready

launcherctl status
launcherctl apps
launcherctl resources

• status reports the bridge and optional backend state.
• apps lists launch targets exposed to the launcher, including profiles Android makes visible.
• resources returns a current CPU, memory, battery, thermal, network, and storage snapshot.

If the command is missing, reopen Termux Launcher. If it exists but cannot connect, run launcherctl restart.

Launch an app

launcherctl launch maps

Queries are fuzzy. Use a more specific label or package fragment when two apps match. This is the same catalog used by the dock and % search.

Optional data sources

No permission is required for ordinary app launch or the basic resource snapshot.

Endpoint and token

The current endpoint and bearer token live in:

~/.launcherctl/endpoint
~/.launcherctl/token

The server binds to localhost by default. Treat the token as a secret: do not paste it into screenshots, bug reports, shell history, dotfile repositories, or chat. If it leaks:

launcherctl token rotate

Existing clients must reread the new token.

Use it in tmux and scripts

bind -n M-m run-shell 'launcherctl launch maps >/dev/null 2>&1 || tmux display-message "Launch failed: Maps"'

For scripts, prefer JSON-capable commands/routes and check exit status. Avoid high-frequency polling; use the event stream or event tail routes for changing state.

Keep helpers current

launcherctl update-scripts

This validates downloaded repo-owned helpers, writes timestamped backups when replacing them, and does not modify ~/.tmux.conf.

Clients and automation

Generate starting configurations instead of hand-copying endpoint/token values:

launcherctl client-config codex
launcherctl client-config opencode
launcherctl client-config ollama

For risk-classified tools and natural-language routing, continue to Agent & MCP. For every endpoint and request body, use the Termux AI page’s API reference.

The launcher works with the default Termux shell. This page recreates the optional fish/tmux workspace seen in the screenshots using secret-free repo examples derived from the live device.

What the guarded installer changes

It does not copy the developer phone’s private aliases, personal paths, or API keys.

Run it

Download the script so you can inspect it before execution:

curl -fsSL https://raw.githubusercontent.com/PickleHik3/termux-launcher/main/docs/en/examples/setup-tmux-btop -o ~/setup-shell
chmod 700 ~/setup-shell
sed -n '1,220p' ~/setup-shell
~/setup-shell

Choose:

1. All: fish + Oh My Posh, tmux plugin, and optional Shizuku btop helper.
2. tmux only: TPM and the Termux Launcher tmux plugin.
3. btop only: the rish-backed helper; use this only after Shizuku setup.
4. Exit: make no setup choice.

New users should choose tmux only first, or leave the default shell unchanged until the launcher feels familiar.

How the pieces fit

The live phone keeps tmux auto-start disabled in fish until explicitly enabled. The public config follows the same conservative default:

set -g fish_auto_tmux 0

Change it to 1 only after tmux starts and detaches cleanly on your device.

Material colors

Keep Settings → Appearance → Material colors enabled. The launcher exports its palette, and the shell/plugin reads the exported values with built-in fallback colors.

Add app-launch keybinds safely

List the labels LauncherCtl knows:

launcherctl apps

Then add only the bindings you want to ~/.tmux.conf:

bind -n M-m run-shell 'launcherctl launch maps >/dev/null 2>&1 || tmux display-message "Launch failed: Maps"'

In tmux syntax, M-m means Alt+m. Avoid copying a large personal binding list: start with one app, test it, then add more.

Refresh after an app update

launcherctl update-scripts
tmux source-file ~/.tmux.conf

The first command refreshes repo-owned scripts with backups; it leaves ~/.tmux.conf unchanged. The second reloads your tmux config.

Manual alternative

If you prefer full control, open the public examples before copying them:

• fish config
• Oh My Posh theme
• tmux config

Back up any destination you already maintain and merge the pieces you understand instead of overwriting the whole file.

tmux is optional, but it is the easiest way to keep a terminal workspace alive as Android apps open over it. The Termux Launcher plugin adds Material themes, Android-friendly bindings, and status widgets backed by LauncherCtl.

Install it through Recreate the shell workspace, then start:

tmux new-session -A -s main

Learn one key first

Press Alt+e inside the plugin to open the current key reference. It is more trustworthy than memorizing an old screenshot.

The public config uses Ctrl+Space as the main prefix and Ctrl+b as a fallback.

Essential actions

The full table remains visible in the plugin popup.

Status widgets

The live configuration uses a compact top bar for sessions/windows plus CPU, memory, weather, and latency/date context. Available plugin options include:

• system resource widgets;
• weather mode;
• current media;
• storage, battery, CPU temperature, and battery temperature;
• rounded, sleek, and purem3 visual themes;
• top or bottom status position.

Enable only the widgets you read. LauncherCtl-backed resource snapshots avoid aggressive shell polling.

set -g @termux-launcher-tmux-system-widgets on
set -g @termux-launcher-tmux-weather on
set -g @termux-launcher-tmux-now-playing on
set -g @termux-launcher-tmux-theme sleek
set -g @termux-launcher-tmux-status-position top

Launch Android apps

Ask LauncherCtl for exact labels, then add deliberate bindings:

launcherctl apps

bind -n M-m run-shell 'launcherctl launch maps >/dev/null 2>&1 || tmux display-message "Launch failed: Maps"'

Do not copy the developer phone’s full personal binding list; conflicts depend on your apps and keyboard.

Reload and recover

tmux source-file ~/.tmux.conf
termux-reload-settings

If tmux itself is broken, start a normal shell/failsafe session and temporarily move only your tmux config out of the way after making a backup. Do not clear the entire Termux app just to debug tmux.

Shizuku is optional. Skip this page unless you want a privileged lock method, a rish shell, or the Shizuku-backed btop helpers. App launch, search, styling, keyboards, normal tmux, and basic LauncherCtl do not need it.

Before you start

• Install Shizuku from a source you trust.
• Follow its official setup guide.
• Understand that Shizuku grants selected apps elevated Android service access while its service is running.

The launcher shows backend state as OFF, READY, SHELL, or DENIED in Settings.

Set up rish

1. In Shizuku, open Use Shizuku in terminal apps.
2. Generate rish and rish_shizuku.dex.
3. Put both in a directory already on your Termux $PATH, such as ~/.local/bin after you add that directory to PATH.
4. Check the launcher edition:

printf '%s\n' "$TERMUX_APP__PACKAGE_NAME"

1. Set the bottom of rish to that exact package:

# Termux edition
RISH_APPLICATION_ID="com.termux"

# VAJ edition
RISH_APPLICATION_ID="io.vaj.tl"

1. Make the script executable and run it once:

chmod +x "$(command -v rish)"
rish

Approve the Shizuku prompt only for the launcher edition you installed.

Verify before adding btop

launcherctl tty-doctor
rish -c 'id'

Read the reported identity and errors. Do not continue if rish points at the wrong package or Shizuku is not running.

Install the optional helper

Run the guarded shell installer and choose btop only or All:

~/setup-shell

The wrappers are btop-shizuku and mini-btop-shizuku. On Android 14+, keep rish_shizuku.dex non-writable as Shizuku recommends.

Lock methods

Under Settings → Apps & Access, the A–Z double-tap lock can remain off or use a configured accessibility/Shizuku method. Test the selected method manually before relying on it. Never weaken the device lock screen to make a launcher gesture work.

Termux Launcher supports three layers that are easy to confuse:

1. an Android keyboard such as Unexpected Keyboard;
2. the launcher’s optional built-in keyboard;
3. Termux Extra Keys, the configurable row above either keyboard.

Use whichever combination feels reliable. None is required for the app dock.

Built-in keyboard

Open Settings → Keyboard to enable it and choose theme, per-key colors, dock matching, size and shape, font, haptics, sound, and optional keys.

The built-in keyboard stays available when returning from other apps. Use the size-and-shape editor if it consumes too much terminal space, especially in landscape.

External keyboard

Unexpected Keyboard remains a good terminal-oriented choice. Disable the built-in keyboard first if you want Android to use your selected IME.

Extra Keys file

Termux Extra Keys live in:

~/.termux/termux.properties

After every edit:

termux-reload-settings

Compact tmux row

Start with one row. It assumes Ctrl+b is available as a tmux prefix:

extra-keys = [[ \
  {macro: "CTRL b F12", display: "♼"}, \
  {macro: "CTRL b h", display: "𝍣", popup: {macro: "CTRL b v", display: "𝍬"}}, \
  {macro: "CTRL b 1", display: "⓵"}, \
  {macro: "CTRL b 2", display: "⓶"}, \
  {macro: "CTRL b 3", display: "⓷"}, \
  {macro: "CTRL b [", display: "✎"}, \
  {key: KEYBOARD, popup: PASTE}, \
  {macro: "CTRL b", display: "㋡"} \
]]

The keyboard key toggles the IME; its popup pastes. The tmux plugin can use F12 to reload Termux settings.

Two rows

Two rows give dedicated modifiers and more pane controls, but cost terminal height. Enable compact dock spacing and test portrait plus landscape before keeping them.

extra-keys = [[ \
  {macro: "CTRL b h", display: "𝍣"}, \
  {macro: "CTRL b v", display: "𝍬"}, \
  {macro: "ALT LEFT", display: "⬸"}, \
  {macro: "CTRL b c", display: "+"}, \
  {macro: "ALT RIGHT", display: "⤑"}, \
  {macro: "CTRL b [", display: "✏"}, \
  {macro: "CTRL b z", display: "□"}, \
  {macro: "CTRL b x", display: "×", popup: {macro: "CTRL b k", display: "⊠"}} \
], [ \
  {key: ESC, display: "Esc", popup: {macro: "CTRL b F12", display: "⟲"}}, \
  {key: TAB, display: "TAB"}, \
  {key: SHIFT, display: "SHFT"}, \
  {key: CTRL, display: "CTRL"}, \
  {key: ALT, display: "ALT"}, \
  {key: LEFT, popup: DOWN}, \
  {key: RIGHT, popup: UP}, \
  {key: KEYBOARD, popup: PASTE} \
]]

If a macro behaves differently from typing the same keys, first confirm the tmux prefix in ~/.tmux.conf, then run tmux source-file ~/.tmux.conf and termux-reload-settings.

TAI is the optional on-device model host built into Termux Launcher. It can serve compatible chat, tool-use, vision/audio, and embedding models through OpenAI- and Ollama-shaped localhost APIs.

You do not need TAI to use the launcher or LauncherCtl.

Check the device first

Model downloads are large and runtime memory use can be significant. Open:

Settings → TAI · Termux AI

Read the device profile, compatible accelerators, minimum memory, model size, and license before downloading. Start with the smallest compatible model that satisfies your use case.

TAI protects the sensitive settings window with Android screenshot security. A black screenshot is expected; do not disable the protection to capture endpoints or tokens.

Beginner flow

1. Open Browse Catalog.
2. Filter by the capability you need: chat, tools, vision/audio, or embeddings.
3. Read license/terms and hardware requirements.
4. Download or import one model.
5. Load it with the recommended/automatic accelerator.
6. Check status from the shell.

tai status
tai models
tai runtime

tai manages the host and models; it is not an interactive chat client.

Connect a client safely

Generate a config when supported:

launcherctl client-config codex
launcherctl client-config opencode
launcherctl client-config ollama

Or read the endpoint/token at runtime from ~/.launcherctl/. Never commit the token or paste it into screenshots.

export OPENAI_BASE_URL="$(sed -n '1p' ~/.launcherctl/endpoint)/v1"
export OPENAI_API_KEY="$(cat ~/.launcherctl/token)"

Compatible clients can then use chat completions, responses, embeddings, or Ollama-shaped chat/generate endpoints according to model capability.

Runtime habits

• Keep only one generation model resident.
• Use preflight before loading an unfamiliar model.
• Prefer auto acceleration until you have a reason to force CPU or GPU.
• Unload when finished to release memory.
• Cancel a stuck load/generation before restarting the whole launcher.

tai doctor
tai runtime

For role assignment, import metadata, exact endpoints, streaming, rate limits, and error bodies, open the full Termux AI API page from the site navigation.

LauncherCtl exposes one shared tool registry to shell scripts, local/remote model clients, and MCP-capable agents. It does not hide a model inside the router: the client decides what to request, while the bridge enforces schemas, risk levels, and confirmations.

Inspect before executing

launcherctl agent --dry-run "open maps"
launcherctl agent "open maps"

Use dry-run while learning which tool and arguments a natural-language request resolves to.

Risk model

• Low-risk read-only tools can run without an extra confirmation.
• Medium-, high-, and critical-risk tools require explicit confirmation.
• Android/Shizuku permissions remain separate from the model’s decision.
• A model cannot gain access that the launcher itself does not have.

Treat tool confirmation as a security boundary, not an annoyance. Read the resolved tool and arguments before approving changes.

MCP stdio bridge

Install Python, then start the bridge:

pkg install python
launcherctl mcp

Generate a client preset when available:

launcherctl client-config codex
launcherctl client-config opencode

The bridge speaks over stdio; the authenticated Android/TAI server remains on localhost. Keep ~/.launcherctl/token out of version control and shared logs.

Optional web tools

Settings can generate a LauncherCtl MCP preset for supported web-search providers. Provider API keys stay in app preferences and are injected into that MCP server’s environment. They are not part of the public fish/tmux dotfiles.

Local model pairing

Pair MCP with TAI for an on-device model path, or use a remote model client you already trust. Local inference does not make every tool action local or harmless; the confirmation and Android permission rules still apply.

Start with the smallest safe check. Do not clear app data, uninstall, or delete dotfiles as a first response.

Launcher or terminal feels stale

termux-reload-settings
launcherctl status

If only tmux looks wrong:

tmux source-file ~/.tmux.conf

If the bridge does not respond:

launcherctl restart
launcherctl status

Symptom map

TAI

tai doctor
tai status
tai runtime

• Model incompatible: recheck ABI, backend, role, and accelerator support.
• Out of memory: unload, choose a smaller model/context, close other heavy apps, and avoid repeated immediate load attempts.
• Secure settings screenshot is black: expected behavior, not a rendering failure.
• Client 401: reread the current LauncherCtl token.
• Endpoint unavailable: reopen launcher and check launcherctl status before touching model files.

Shell setup

The guarded installer keeps existing fish/Oh My Posh files and only appends missing tmux plugin lines. If your custom setup behaves differently, compare against the public examples rather than overwriting your files.

Collect a useful report

Include:

• edition and app version;
• Android/device model;
• exact path and command;
• whether the app is the selected Home launcher;
• relevant permission/backend state;
• a screenshot with tokens and private notification text removed;
• the smallest app-scoped log excerpt that contains the failure.

Never include ~/.launcherctl/token, provider/API keys, private notifications, or unrestricted device logs.