my-term

my-term is a Java 21 terminal emulator with two frontends over one shared terminal kernel:

• GUI (default): a LibGDX/LWJGL3 desktop window.
• TUI (--tui): a JLine application running in the current terminal.

The GUI includes pane and tab-group management, a directory sidebar, and a syntax-highlighted file preview. Both frontends run real shell processes behind PTYs and share the same terminal, layout, and workspace model.

Install a JDK 21, then use the repository's Gradle wrapper from the repository root:

# Compile, run tests, and assemble every module
./gradlew build

# Run all tests without assembling distribution artifacts
./gradlew test

Run either frontend:

# GUI mode is the default
./gradlew :app:run

# TUI mode takes over the current terminal
./gradlew :app:run --args='--tui'

# Print the supported command-line options
./gradlew :app:run --args='--help'

--gui explicitly selects the default GUI mode; --tui selects the terminal frontend.

Tests are module-local. Always run a filtered test through its owning module's task; a root ./gradlew test --tests ... forwards the filter to every module and fails in modules that do not contain that test.

# One test class
./gradlew :app:test --tests com.myterm.app.ArgParserTest

# One test method
./gradlew :core:test --tests \
  com.myterm.core.model.ScreenBufferTest.putCharAutoWrapsAtRightEdge

Use :gui:test or :tui:test in the same way for frontend tests.

• Architecture guide: module dependencies, runtime data flow, thread boundaries, package ownership, and diagrams.
• Configuration reference: GUI settings and shortcuts.
• Persistent-memory backup snapshot: the reviewed, project-scoped baseline.
• Memory backup and recovery guide: safe refresh and manual, per-item recovery procedures.

On macOS, choose the distribution format that suits the installation method:

# Standalone application bundle for development or manual copying
./scripts/package-mac-app.sh

# Distributable disk image for drag-and-drop installation
./scripts/package-mac-dmg.sh 1.2.3

# Build and directly install into /Applications/my-term.app
./scripts/install.sh 1.2.3

The scripts can be called from any working directory and use this repository's Gradle wrapper rather than a Gradle installation on PATH.

package-mac-app.sh creates:

app/build/jpackage/my-term.app

package-mac-dmg.sh creates:

app/build/jpackage/my-term-<version>.dmg

Open the DMG in Finder and drag my-term.app onto its Applications shortcut. Then eject the disk image and launch my-term from Applications, Spotlight, or:

open -a my-term

The app bundle and DMG include a Java runtime. Building them requires macOS and a JDK 21 installation available to the Gradle toolchain; macOS artifacts cannot be produced on another operating system. A release version is optional and must have one to three numeric components; versions such as 0.1.0 are supported. Without an argument, the packaging tasks use version 1.0.0.

Use install.sh instead of a DMG when building from this checkout and installing directly. It replaces only an existing /Applications/my-term.app, requesting sudo only when write access is required. For development or script testing, set INSTALL_DIR to an existing absolute directory instead.

Build the installer on Windows 10 or 11 from Command Prompt. The build requires a JDK 21 installation available to the Gradle toolchain and WiX Toolset 3.x with candle.exe and light.exe available on PATH.

REM Build with the default version, 1.0.0
scripts\package-windows-exe.bat

REM Or supply an optional release version
scripts\package-windows-exe.bat 1.2.3

The script can be called from any working directory and uses this repository's gradlew.bat. It creates:

app\build\jpackage\my-term-<version>.exe

Run the EXE to install my-term. The installer includes a bundled Java runtime, so users do not need to install Java separately. Windows EXE installers must be built on Windows and cannot be produced on macOS or Linux. Without a custom Windows icon, the installer uses the default icon provided by jpackage.

The optional version must have one to three numeric components and defaults to 1.0.0. Windows installer versions are normalized to three components and are limited to 255.255.65535.

On Windows, current-directory detection for running shells is best effort. If the native probe cannot determine a shell's current directory, workspace restoration falls back to the directory where that session was started.