Terminal

Create and manage terminal sessions

Extensions can create, manage, and interact with terminal sessions. The terminal system runs on Klyx’s internal PRoot-based Linux environment, giving plugins access to a full shell ecosystem.

TerminalManager

private val terminalManager: TerminalManager by plugin()

The TerminalManager exposes two subsystems plus helpers for opening the terminal:

Property	Type	Description
sessionManager	TerminalSessionManager	Create and manage terminal sessions
sessionBinder	TerminalSessionBinder	Bind and unbind the terminal service
runInTerminal(...)	suspend	Open the terminal and run a command in a fresh session
openTerminal()		Open the terminal screen with an interactive login shell

Running a command

Use runInTerminal to open the terminal and execute a command directly. The command runs in a fresh session — no login shell, prompt, or MOTD, only the command’s stdout/stderr and stdin. The session’s stdin is wired to the terminal, so interactive prompts are answerable by the user:

private val terminalManager: TerminalManager by plugin()

pluginScope.launch {
    terminalManager.runInTerminal(
        command = "rustup component add rust-analyzer",
        sessionName = "Install rust-analyzer"
    )
}

If the terminal environment isn’t installed yet, the terminal screen opens so the user can complete the setup first.

Opening an interactive shell

Use openTerminal to open the terminal screen. When no session is active, an interactive login shell is created automatically so the user can type commands directly:

terminalManager.openTerminal()

For a guaranteed fresh shell even when other sessions exist, pass an interactive command to runInTerminal:

pluginScope.launch { terminalManager.runInTerminal("bash") }

TerminalSessionManager

Manages the lifecycle of terminal sessions. All state is exposed via StateFlow.

val sessionManager = terminalManager.sessionManager

Session state

// All active sessions (ordered list)
val sessions: ImmutableList<TerminalSessionEntry> = sessionManager.sessions.value

// Currently active session ID
val currentId: Uuid? = sessionManager.currentSessionId.value

// Currently active session entry
val current: TerminalSessionEntry? = sessionManager.currentSession.value

Creating sessions

val session = sessionManager.newSession(
    client = terminalClient,
    id = Uuid.generateV7(),                      // Optional: auto-generated
    transcriptRows = TerminalEmulator.DEFAULT_TERMINAL_TRANSCRIPT_ROWS,  // Scrollback size
    showMotd = true                               // Show message of the day
)

Getting or creating a session

// Returns existing session or creates a new one
val session = sessionManager.getOrCreateSession(id, terminalClient)

// Returns current session or creates a new one
val session = sessionManager.currentSessionOrNewSession(terminalClient)

Switching and terminating

sessionManager.switchTo(sessionId)            // Switch to a specific session
sessionManager.terminate(sessionId)           // Terminate a specific session
sessionManager.terminateCurrentSession()      // Terminate the active session
sessionManager.terminateAll()                 // Terminate all sessions

TerminalSessionEntry

@Immutable
data class TerminalSessionEntry(
    val id: Uuid,
    val session: TerminalSession
)

TerminalSessionClient

When creating a session, you provide a TerminalSessionClient callback interface. This class is defined in the terminal module (com.klyx.terminal.emulator.TerminalSessionClient), not in the klyx-api module. It receives notifications about text changes, title changes, session completion, bell events, color changes, and more.

The TerminalSessionClient interface exposes the following callbacks:

Callback	Description
onTextChanged(session)	The session’s text content changed
onTitleChanged(session)	The terminal title changed
onSessionFinished(session)	The session process has exited
onCopyTextToClipboard(session, text)	User requested to copy text to clipboard
onPasteTextFromClipboard(session)	User requested to paste text from clipboard
onBell(session)	Terminal bell (BEL) received
onColorsChanged(session)	Terminal color palette changed
onTerminalCursorStateChange(state)	Cursor visibility changed (true = visible)
setTerminalShellPid(session, pid)	Shell process started with PID
logError(tag, message)	Log an error
logWarn(tag, message)	Log a warning
logInfo(tag, message)	Log info
logDebug(tag, message)	Log debug
logVerbose(tag, message)	Log verbose
logStackTraceWithMessage(tag, message, e)	Log stack trace with message
logStackTrace(tag, e)	Log stack trace

Additionally, the terminalCursorStyle property can be set to control the cursor appearance.

TerminalSessionBinder

Manages the binding lifecycle between the app and the background terminal service.

val sessionBinder = terminalManager.sessionBinder

// Check if bound
val isBound: Boolean = sessionBinder.isServiceBound.value

// Bind the terminal service (required before creating sessions)
sessionBinder.bind(context)

// Unbind when done
sessionBinder.unbind(context)

Terminal environment utilities

These functions are available in the com.klyx.api.terminal package:

// Base environment variables for a terminal session
val env: Map<String, String> = terminalEnv()

// PRoot-specific environment variables
val processEnv: Map<String, String> = processEnv()

// Terminal launch arguments (PRoot-based)
val args: List<String> = terminalArgs(showMotd = true)

terminalEnv() sets TERM, TERM_PROGRAM, COLORTERM, HOSTNAME, TMPDIR, LANG, and LC_ALL. processEnv() configures PROOT_LOADER, PROOT_TMP_DIR, HOME, ROOTFS, PATH, and passes through relevant Android system environment variables.

Terminal paths

Terminal-specific paths are available as extensions on Paths:

Paths.rootFs        // dataDir/rootfs -- the root filesystem for PRoot
Paths.home          // filesDir/home -- user home directory
Paths.projects      // home/projects -- projects directory
Paths.versionFile   // rootFs/.bootstrap-version -- bootstrap version file

Native PRoot library paths:

prootFile()         // Native PRoot executable
prootLoaderFile()   // Native PRoot loader library

CursorStyle

The terminal cursor style enum (used in settings and client callback):

Style	Description
CursorStyle.Block	Block cursor (default)
CursorStyle.Underline	Underline cursor
CursorStyle.Bar	Bar cursor

Example

Create a terminal session with a custom client:

override suspend fun onLoad() {
    val client = object : TerminalSessionClient {
        override fun onTextChanged(session: TerminalSession) { /* ... */ }
        override fun onTitleChanged(session: TerminalSession) { /* ... */ }
        override fun onSessionFinished(session: TerminalSession) { /* ... */ }
        // ... implement other callbacks as needed
    }

    sessionManager.newSession(client, showMotd = true)
}