Re:T-UI Modules Walkthrough

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 module 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 -dock -toggle`	Shows or hides the dock row immediately and persists that preference.	Does not close the currently active module panel.
`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, reminder, notes, rss, and weather. They are available even if they are hidden from the dock. New installs keep the core default dock small; add extra modules when you want them.

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.

Notes

A compact panel for existing notes. Use TODO: notes as lightweight tasks without a second task store.

RSS

A feed glance panel backed by the existing rss command, including Reddit RSS feeds.

Weather

A dockable weather status panel over the existing tuiweather setup and update flow.

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.

1

Grant access

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

2

Open or dock it

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

3

Navigate safely

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

4

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 also ships as the built-in module-button example, while the other default modules keep their controls in the suggestion row.

$ 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

Notes module

Use notes as a small persistent task surface.

module id: notes

The notes module reads the same notes file as the editor and status label. It does not create a separate todo database; task-like items are just notes with a convention such as TODO:.

Open: module -show notes

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

Add task: notes -add TODO: follow up with tester

Manage: notes -ls, notes -rm 1, notes -cp 1, notes -clear

$ module -dock add notes
              $ notes -add TODO: review theme preset
              $ module -show notes

RSS module

Keep feeds glanceable without turning the terminal into a feed reader.

module id: rss

The RSS module shows cached feed items and offers suggestion chips for listing, refreshing, and opening the first configured feed. Network behavior stays with the existing rss command and its per-feed update interval.

Open: module -show rss

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

Add Reddit: rss -add 1 900 https://www.reddit.com/r/android/.rss

Refresh/read: rss -frc 1, rss -l 1, rss -ls

$ rss -add 1 900 https://www.reddit.com/r/android/.rss
              $ rss -frc 1
              $ module -dock add rss
              $ module -show rss

Weather module

Dock the existing weather status instead of adding another service.

module id: weather

The weather module uses the same tuiweather setup and update behavior as the status label. If weather is disabled or not configured, the panel tells you which command to run instead of silently polling.

Open: module -show weather

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

Setup: tuiweather -enable, tuiweather -tutorial, tuiweather -set_key key

Refresh: tuiweather -update

$ tuiweather -enable
              $ module -dock add weather
              $ module -show weather
              $ tuiweather -update

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.

Preformatted output: normal script output uses the selected launcher font. Wrap terminal art, tables, or code in ::pre, ::ascii, or ::code, then close it with ::end, when alignment must stay monospace. One-line forms such as ::pre text, ::ascii text, and ::code text are also supported.

echo "::title Weather: Chennai"
              echo "::body Weather report: Chennai"
              echo "::ascii"
              curl -s 'wttr.in/Chennai?0T'
              echo "::end"

Lua modules

Use Lua when the module needs launcher-native controls.

module source: lua:<id>

Lua modules share the same dock as built-ins and Termux modules. They are launcher-native scripts stored locally by Re:T-UI, so they can render text, rows, containers, progress glyphs, and native buttons inside the active module panel, or keep the panel clean and publish suggestion chips for keyboard-first use.

Create: module -new lua name, save the Lua source, then module -show name.

Edit/check: module -edit name, module -config name, module -check name, and module -approve name.

Module buttons: ui:button, ui:command_button, ui:module_button, ui:app_button, ui:intent_button, and ui:shortcut_button.

Suggestion chips: ui:suggest_action, ui:suggest_command, ui:suggest_module, and ui:suggest_text.

Layout: ui:render / ui:layout can declare small rows, columns, text, buttons, progress bars, dividers, spacers, and explicit preformatted blocks with pre, ascii, or code.

Refresh: opening the module renders it; tapping the module title forces a refresh. Manual module -refresh remains available.

Font contract: Lua text follows the active launcher font by default. Renderer-owned progress bars, dividers, and explicit pre/ascii/code layout blocks stay monospace so tables and terminal art keep their shape.

Boundary: keep Linux tools, long-running jobs, and shell automation in Termux modules. Use Lua when the user needs a compact launcher-owned UI surface with safe app, intent, shortcut, config, and storage helpers.

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, ::pre/::ascii/::code, 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.

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