A modern Kotlin Multiplatform (KMP) terminal emulator engine and Compose Multiplatform rendering library. This library provides a standalone, high-performance, GPU-accelerated terminal emulator designed for mobile, desktop, and web applications.

👉 🚀 Try Live Interactive WebAssembly Demo on GitHub Pages

The repository includes multiple demo implementations targeting different environments and runtimes:

kmp-terminal powers the terminal rendering canvas and ANSI state machine in production:

A secure, high-performance Android SSH & SFTP client with hardware-backed encryption, multi-session management, and custom quick key bars.

• Engine Core: Uses :terminal-core for ANSI/VT100 parsing, TrueColor support, and circular scrollback buffer management.
• Rendering Pipeline: Uses :terminal-ui for low-allocation Compose Multiplatform canvas rendering, touch gestures, and responsive IME soft-keyboard input capture.
• Product Website: ssh-client.nanzen.se
• Google Play: Download on Google Play

• Decoupled Tiered Architecture:
  • :terminal-core: Pure Kotlin multiplatform terminal state machine, screen buffer, ANSI/VT100 parser, and text selection models. Zero UI dependencies.
  • :terminal-ui: Hardware-accelerated Compose Multiplatform canvas renderer, gesture recognizers, platform-native input capture, selection overlays, and toolbar key bars.
• Type-Safe Configuration System:
  • TerminalConfig & terminalConfig { ... } DSL for core engine dimensions, scrollback capacity, OSC 52 security policies, tab stops, and bell behavior.
  • TerminalUiConfig & terminalUiConfig { ... } DSL for typography, cursor styles (BLOCK, UNDERLINE, BEAM), gesture controls, key bar layouts, and color themes.
  • Ambient Compose propagation via LocalTerminalUiConfig.
• Reactive State & Attention Events:
  • screenState StateFlow emitting immutable buffer snapshots on change.
  • Reactive event flows: attentionEvents (OSC 9 / OSC 777 desktop notifications), bellEvents / bellCount, clipboardEvents / clipboardWriteCount, and windowTitle.
• Text Selection & Clipboard Management:
  • Multi-line text selection overlay with visual start/end handle indicators.
  • Drag-selection gesture tracking, long-press activation, and auto-copy on release.
  • Plain-text extraction with ANSI sequence stripping and scrollback boundary support.
• ANSI & Modern Terminal Standards:
  • 16 standard/bright ANSI colors, 256 indexed colors, 24-bit TrueColor RGB.
  • Cursor movement, scrolling regions (DECSTBM), alternate screen buffer (altBuffer for vim/htop/less).
  • SGR Mouse Tracking (1006) and legacy xterm mouse tracking (press, release, drag, wheel).
  • OSC 52 clipboard integration with configurable security policies (ASK, ALWAYS_ALLOW, ALWAYS_DENY).
  • Independent deep state cloning (TerminalEmulator.copy()) for headless sessions and speculative execution (e.g. Mosh).
  • Soft-wrap row querying (ScreenBuffer.isRowWrapped(row)).
• Mobile & Desktop Responsive Features:
  • Soft keyboard modifier toggle integration (Ctrl, Alt, Shift states).
  • Monospace cell measurement with sub-pixel precision to eliminate column drift.
  • Low-allocation batching render loop with LRU cache.
  • Touch-scroll disambiguation (touchScrollSendsWheelOnly) to send mouse wheel events on mobile drag gestures in tmux and vim.
• Multiplatform Target Support:
  • WebAssembly (wasmJs)
  • Desktop (jvm)
  • Android (androidMain)
  • iOS (iosArm64, iosSimulatorArm64)

kmp-terminal/
├── terminal-core/       # Pure Kotlin Multiplatform emulation engine & screen buffer (Zero UI dependencies)
├── terminal-ui/         # Compose Multiplatform canvas renderer & UI components
├── demo-mobile/         # Android & iOS Compose Multiplatform mobile showcase
├── demo-web/            # WebAssembly (wasmJs) interactive demo & JS bridge (deployed to GitHub Pages)
├── demo-jvm/            # JVM Desktop Compose demo (macOS, Linux, Windows)
├── demo-vite/           # Vite + TypeScript web application integrating Wasm terminal
├── demo-html/           # Vanilla HTML/JS zero-framework integration demo
└── npm-package/         # NPM package bundle (@JohNan/kmp-terminal)

Add the dependencies to your multiplatform build.gradle.kts:

kotlin {
    sourceSets {
        commonMain.dependencies {
            // Core ANSI engine, scrollback buffer, and text selection (zero UI dependencies)
            implementation("io.github.johnan:terminal-core:0.3.11")

            // Optional: Compose Multiplatform canvas renderer & gestures
            implementation("io.github.johnan:terminal-ui:0.3.11")
        }
    }
}

Create a TerminalEmulator instance with default or DSL-configured parameters:

import com.johnan.terminal.core.BellBehavior
import com.johnan.terminal.core.Osc52Policy
import com.johnan.terminal.core.TerminalEmulator
import com.johnan.terminal.core.terminalConfig

// DSL configuration
val config = terminalConfig {
    initialRows = 24
    initialCols = 80
    maxScrollback = 2000
    osc52Policy = Osc52Policy.ALWAYS_ALLOW
    bellBehavior = BellBehavior.VISUAL
}

val emulator = TerminalEmulator(
    config = config,
    onTerminalResponse = { response ->
        // Send terminal response back to PTY / SSH stream (e.g. CPR, DA1, mouse events)
    }
)

// Process incoming ANSI byte streams
emulator.processOutput("Hello \u001B[32mGreen\u001B[0m World!\r\n")

Render the terminal screen state using TerminalRenderer:

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.sp
import com.johnan.terminal.core.TerminalColorScheme
import com.johnan.terminal.ui.TerminalCursorStyle
import com.johnan.terminal.ui.TerminalRenderer
import com.johnan.terminal.ui.terminalUiConfig

@Composable
fun TerminalScreen(emulator: TerminalEmulator) {
    val terminalState by emulator.screenState.collectAsState()

    val uiConfig = terminalUiConfig {
        typography {
            fontSize = 15.sp
            letterSpacing = 0.sp
        }
        cursor {
            style = TerminalCursorStyle.BEAM // BLOCK, UNDERLINE, or BEAM
            blink = true
            overrideColor = Color(0xFF00FFCC)
        }
        gestures {
            enableTouchToFocus = true
            enableSelection = true
            wheelScrollMultiplier = 1.5f
            touchScrollSendsWheelOnly = true // Opt-in wheel-only touch scrolling for tmux/vim
        }
    }

    TerminalRenderer(
        terminalState = terminalState,
        config = uiConfig,
        onInput = { input -> 
            // Forward user keyboard input to PTY / SSH channel
        },
        onArrowKey = { arrow, shift ->
            // Forward arrow navigation
        },
        onLog = { msg -> println("[TerminalLog] $msg") },
        modifier = Modifier.fillMaxSize()
    )
}

Text selection is managed through TerminalSelection and SelectionState:

import com.johnan.terminal.core.TerminalSelection

// Programmatically extract text from a selection
val selection = TerminalSelection(startRow = 0, startCol = 0, endRow = 2, endCol = 40)
val selectedText = selection.extractText(screenBuffer)

// Selection containment check
val isInside = selection.contains(row = 1, col = 10)

copy() returns a fully independent deep copy, including a partially parsed escape or UTF-8 sequence. This lets you keep one headless emulator per received state (for example Mosh) and apply a diff to a copy of the reference state. bellCount, clipboardWriteCount and lastClipboardWrite let you diff event-only state between snapshots, and ScreenBuffer.isRowWrapped(row) exposes the soft-wrap flag.

val reference = TerminalEmulator(TerminalConfig(initialRows = 24, initialCols = 80))
reference.processOutput("hello")

val next = reference.copy()           // callbacks are not inherited; pass them if needed
next.processOutput("\u001B[31m world") // diff applied to the copy only

val bellRang = next.bellCount > reference.bellCount
val clipboardChanged = next.clipboardWriteCount > reference.clipboardWriteCount
val firstRowWraps = next.getScreenBuffer().isRowWrapped(0)

This project uses mise for reproducible toolchain management (JDK 21, Android SDK, Gradle, Node 20).

# Compile WebAssembly target
mise run compile-wasm

# Run local WebAssembly browser demo
mise run run-demo

# Run native JVM Desktop demo
mise run run-jvm

# Assemble Android debug APK (demo-mobile)
mise run assemble-android

# Compile iOS simulator target (demo-mobile)
mise run compile-ios-demo

# Build all targets
mise run build

# Execute all multiplatform unit tests
mise exec -- ./gradlew allTests

# Run fast unit test suite
mise exec -- ./gradlew test

# Verify Kotlin code formatting and linting
mise exec -- ./gradlew ktlintCheck

Contributions are welcome! Please read through our community guides:

• Contributing Guidelines — Toolchain setup, testing, and architecture invariants.
• Code of Conduct — Contributor pledge and standards.
• Security Policy — Responsible vulnerability reporting.
• Migration Guide — Before/after recipes and upgrade paths.

Distributed under the Apache License, Version 2.0. Free for commercial and private use with attribution required and express patent grant.