Re:T-UI module walkthrough

Use modules without mixing up the dock, the panel, and the registry.

Modules are small terminal panels for status, controls, script output, and guided input. This page is the practical walkthrough: what each module does, how the dock works, and which commands change the visible panel versus the saved module list.

Built-in modules Dock commands Reminder prompts Termux script modules Battery-friendly habits

Start with dock behavior Jump to modules Back to showcase

Mental model

There are three separate things.

The module system is easier once these are separate in your head. A module can exist in the registry, appear in the dock, and be open on screen. Those are related, but they are not the same state.

Registry: all known modules. Built-ins always exist; custom script modules are registered with module -add.

Dock: the row of module buttons shown on the home widgets page. Change it with module -dock add, module -dock remove, or module -hide.

Active panel: the module currently visible above the terminal tray. Change it with module -show or close it with module -close.

Dock commands

The dock controls buttons, not whether a module exists.

The dock is a saved ordered list. Re:T-UI renders one button for each module in that list, then appends an X button that closes the active panel.

Command	What it changes	What it does not do
`module -ls`	Prints all known modules and the current dock order.	Does not open or change anything.
`module -show music`	Opens the music module as the active panel.	Does not add music to the dock.
`module -close`	Clears the active panel and unselects the dock button.	Does not remove anything from the dock.
`module -dock add music timer`	Adds known modules to the dock row.	Does not create custom modules.
`module -dock remove music`	Removes module buttons from the dock row.	Does not delete the module.
`module -hide music`	Convenience command for removing one module from the dock.	Does not delete built-in modules.
`module -add server termux:/path/script.sh`	Registers a custom script module and adds it to the dock.	Does not run forever; refreshes are explicit.
`module -rm server`	Deletes a custom script module from Re:T-UI's registry and dock.	Does not delete the Termux script file.

$ module -ls
$ module -dock add notifications timer reminder
$ module -show notifications
$ module -close

Built-in modules

Start with the native panels before adding scripts.

These modules are built into the launcher: music, notifications, timer, calendar, and reminder. They are available even if they are hidden from the dock.

Music

Playback controls and now-playing state. Suggestions expose previous, play, next, info, and stop.

Notifications

A pager for selected Android notifications, with open and reply actions when Android exposes them.

Timer

A focused countdown panel backed by the same timer command used from the terminal.

Calendar

A small month surface for orientation. Use it as a glanceable home panel.

Reminder

Local reminders with guided add, edit, and remove prompt sessions.

Custom scripts

Termux scripts can become modules when they print clean output and exit.

Music module

Use media controls without leaving the launcher.

module id: music

Open the panel with module -show music. When active, suggestions give quick controls. The raw music command also works from the terminal.

Open: module -show music

Dock: module -dock add music or module -hide music

Controls: music -play, music -next, music -previous, music -stop

Library: music -ls, music -select song, music -info, music -seekto seconds

Notifications module

Page through notifications and reply from the terminal flow.

module id: notifications

The notification module needs Android notification access. It shows one selected notification at a time, so the panel stays readable instead of becoming a noisy feed.

Grant access

Run notifications -access, then enable Re:T-UI in Android notification access settings.

Open or dock it

Run module -show notifications to open now, or notifications -on / module -dock add notifications to keep the button visible.

Navigate safely

Use notifications -prev, notifications -next, and notifications -open. Suggestion chips run these quietly when the module is active.

Reply intentionally

Bind an app with reply -bind app, select the target notification, then run notifications -reply. The selected item is preserved while you type.

$ notifications -access
$ module -show notifications
$ notifications -next
$ reply -bind signal
$ notifications -reply

Timer module

Use a timer as both a command and a docked panel.

module id: timer

The timer panel reflects the timer command. If a timer is already running, timer -add extends it directly. Typing a plain new duration while one is active asks for confirmation.

Open: module -show timer

Start: timer 5m or timer -add 30s

Inspect: timer -status

Stop: timer -stop

Calendar module

Keep a small date surface in the dock.

module id: calendar

The calendar module is intentionally simple: a glanceable month panel for the home screen. It is useful docked near timer and reminder because those workflows often start from date/time context.

$ module -show calendar
$ module -dock add calendar
$ module -dock remove calendar

Reminder module

Let the launcher own reminder scheduling.

module id: reminder

The reminder module uses native prompt sessions. During a session, normal command execution pauses until you save, edit, remove, or cancel.

Add

module -prompt reminder add asks for reminder text, date, time, and confirmation.

Edit

module -prompt reminder edit asks which reminder to change, then walks through replacement values.

Remove

module -prompt reminder remove asks which reminder to delete and confirms before removal.

$ module -show reminder
$ module -prompt reminder add
> What do you want to be reminded about?
$ submit Play Store update
> What date?
$ 08/05/2026
> What time?
$ 10:30AM

Custom Termux modules

Scripts should print output, then exit.

A good module script is boring in the best way: gather data, print a small body, offer a few suggestions, and finish. Avoid infinite loops and high-frequency polling; Re:T-UI should refresh modules on demand or through deliberate callbacks.

Minimal script

#!/data/data/com.termux/files/usr/bin/sh

echo "::title Server"
echo "::body prod-api ONLINE"
echo "::body checked: $(date +%H:%M)"
echo "::suggest refresh | command | module -refresh server"

Register it

$ termux -setup
$ module -add server termux:/data/data/com.termux/files/home/retui/server-health.sh
$ module -refresh server
$ module -show server
$ module -dock add server

Battery rule: do not build modules around while true loops or one-second polling. Let the launcher show cached output while idle, then refresh from a command, suggestion, callback, or Android event.

Build modules with Codex

Generate Termux-backed modules without guessing the plumbing.

The Re:T-UI module maker skill teaches Codex how to create launcher-friendly shell modules: scripts that print ::title, ::body, and ::suggest lines, keep expensive work in Termux only when needed, and let Re:T-UI own UI behaviors such as pagination, reply prompts, refresh chips, and quiet module controls.

Launcher first: use Re:T-UI variables and module primitives when the launcher already knows the state.

Termux when needed: use Linux tools and Termux:API for data Android only exposes through the shell layer.

Clean setup: keep Termux script commands separate from Re:T-UI registration commands.

Share the skill as a folder. A Codex user can install it by copying the folder below into their Codex skills directory.

~/.codex/skills/retui-module-maker/
  SKILL.md
  references/module-contract.md
  references/linux-termux-programming.md
  references/pagination-and-reply.md

Troubleshooting

Fast checks when modules feel confusing.

A module vanished from the dock

Run module -ls. If it still exists, add it back with module -dock add name.

`-close` did not remove it

That is expected. module -close only closes the active panel. Use module -dock remove name to remove the button.

A custom module has stale output

Run module -refresh name. Script modules store the last output until refreshed.

Notifications do not appear

Run notifications -access, enable access, then reopen with module -show notifications.

Reminder prompt got stuck

Type cancel in the prompt. Then reopen the module with module -show reminder.

Dock order feels wrong

Remove and add modules in the order you want. The dock preserves insertion order.