Koder Term — `products/dev/kterm/app`

Cross-platform tiling terminal emulator with persistent sessions, SSH multiplexing, image clipboard, and AI-CLI integration.

Role in the stack

Primary couplings

Status

v1.32.4 (2026-05-29) — in development. Desktop (LinuxmacOSWindows) and web (browser via Go server bridge); mobile: Android signed-release pipeline live (own vault key, v1.32.6); iOS scaffold exists, pending a macOS runner (#026).

Architecture

Desktop App (Flutter)
  └── PTY → Local shell
  └── SSH → ControlMaster → kterm-bridge (process stats, clipboard, file xfer)

Web Browser (xterm.js)
  └── WebSocket → Go Server → PTY → Shell
                    ├── Session persistence (~/.koder-kterm/sessions/)
                    ├── Koder ID OIDC auth
                    ├── Bastion (SSH vault + targets)
                    └── QR session sharing (#046)
                          └── /ws/share (token-auth WebSocket)
                          └── /api/share/qr (QR PNG via go-qrcode)

Mobile App (Flutter — scan QR)
  └── kterm:// URI → WebSocket → Go Server (shared session)

Three surfaces, one product: the Flutter desktop app talks directly to a local PTY (or SSH via ControlMaster); the web browser talks WebSocket to a Go server (server/) that owns the PTY and persists session state; mobile scans a QR code to join a shared session on the Go server. SSH tiles get remote process stats via the kterm-bridge daemon.

Repository layout

products/dev/kterm/
├── app/                   ← Flutter (mobile/desktop/web)
│   ├── lib/
│   │   ├── main.dart, app.dart
│   │   ├── screens/       ← preferences, profile_editor, terminal
│   │   ├── widgets/       ← tiling, terminal, ssh, paste, session
│   │   ├── services/      ← pty, ssh, ssh_multiplexer, clipboard,
│   │   │                    notification, storage, search, trigger,
│   │   │                    ai_integration, image_protocol, dbus,
│   │   │                    quake, profile_switch, process_stats,
│   │   │                    share (#046)
│   │   ├── providers/, models/, theme/, l10n/, core/
│   │   ├── android/, ios/, linux/, macos/, windows/
│   │   ├── server/        ← Go web server bridge
│   │   ├── landing/       ← kterm.koder.dev product landing
│   │   └── docs/, assets/
│   └── backlog/           ← pending/in-progress/done tickets
└── bridge/
    └── cmd/kterm-bridge/  ← Go bridge binary
    └── install/

Releases

• Hub depot: currently linuxx86_64 only; macOSWindows/web pending

  (#014).

• Server bundle: Go binary built from server/, deployed via

  server/deploy/install.sh (systemd unit). Behind Koder Jet at kterm.koder.dev.

• Tag pattern: products/dev/kterm/v* (per policies/releases.kmd).
• Binary name: kterm (per specs/binaries-and-cli/naming.kmd,

  aliases[0] from registries/component-names.md). Piloted in #040.

• CHANGELOG: app/CHANGELOG.md.

Operational notes

• claude-tiles integration — kterm is the canonical host for the

  8-tile persistent Claude Code session runbook (infrastructure/claude-tiles.md).

• Image clipboard convention — images saved to ~/temp/ per

  CLAUDE.md directory rule (avoid /tmp/ tmpfs limit). Cleanup/ rotation pending #012.

• AI env vars — kterm exports KODER_TERM=1, KODER_TERM_VERSION,

  KODER_TERM_IMAGES=1, TERM_PROGRAM=kterm to all PTYs for AI tools to detect kterm-specific capabilities (Sixel/Kitty image protocol).

• Credential vault operator commands (#034) — the server binary

  doubles as an offline vault tool: koder-kterm-server rotate-master-key re-seals every stored credential under a fresh master key (crash-safe via a master.key.old retired-key archive); vault-backup -file X.tar.gz / vault-restore -file X.tar.gz [-force] snapshot/restore the vault dir. KODER_KTERM_VAULT_BACKEND selects the master-key source (file default; kms/keyring blocked on a Koder Vault service — fail loudly). Run vault commands with the server stopped.

• Web client keybindings (#027) — the vanilla-JS web client ships

  rebindable shortcuts (toolbar ⌨ drawer; overrides in localStorage["kterm-keybindings"]), at parity with the desktop set.

• Bastion MFA step-up (#033) — before opening an outbound SSH session,

  the server requires a fresh MFA assertion via Koder ID GET /v1/auth/step-up/check (id engine#189). The window is account-wide in vault metadata (mfa_window_seconds, default 300) via /api/bastion/stepup (GET status / PUT window). Connect rejects step_up_required with a re-auth URL (prompt=login&max_age=0) when stale/absent; fails closed when Koder ID is unreachable. Gate is disabled for self-host without OIDC. The web bastion drawer shows a "Recent MFA: Nm ago" / "Step-up required" banner + "Step up now".

• Silent shell integration (#052) — the OSC 133 command-finished hooks

  (#051) install via the shell's own init files (bash --rcfile, zsh ZDOTDIR, fish --init-command) instead of being echoed to the PTY, so nothing lands in the visible buffer or shell history. Unknown shells / remote SSH legs fall back to the visible stdin injection.

• Tile process stats (#041#042) — the per-tile CPU%RAM chip is fed by

  a pluggable ProcessStatsBackend: /proc on Linux, libproc FFI on macOS, ToolHelp+psapi FFI on Windows. CPU is normalized to cumulative µs so the rate math is platform-uniform. (mac/win runtime validation gated on those hosts.)

• Hub-driven auto-update (#020) — UpdateService drives the SDK

  KoderUpdater (koder_kit#072): 6h periodic re-check → KoderUpdate banner, in-app download → fail-closed SHA-256 verify → per-platform apply, and resume of a postponed staged update on next launch. Surfaced by KtermUpdateBanner at the top of the terminal screen.

• Settings on canonical KoderSettingsPage (#024 Phase 3) — PreferencesScreen

  was rebuilt from a bespoke master-detail nav-rail to a single canonical-ordered scroll of KoderSettingsGroup/KoderSettingsTile (9 groups). Full-width visual editors are dedicated sub-pages reached by button tiles (#053 D3): Fonts (FontEditorScreen), Colors (ColorSchemeScreen), Scrollback (ScrollbackScreen), Profiles (ProfilesScreen), Keybindings (KeybindingsScreen). Theme picker = canonical dropdown; ColorSchemePreset lives in models/. The dialog chrome + snapshot-cancel/restore lifecycle are preserved. Net −1102 LoC.

• Debug-soak perf instrumentation (#005) — a --debug-soak / KTERM_DEBUG_SOAK=1

  mode (services/soak_probe.dart, OFF by default, ships in the release binary) records performance signals only, never terminal content (observability-first R8.1 / instrumentation-contract C5): VT parse latency per coalesced write (the

  003 floor, timed in PtyService.flush — stopwatch only starts when enabled),

  flood byte-rate episodes, and Flutter FrameTiming buildrasterjank (the #004 paint cost, via SchedulerBinding.addTimingsCallback — no xterm fork). Rolls up to ~/temp/kterm-soak/digest.json (µs histograms, p50p99p999) and mirrors the byte counter into KoderTelemetry (koder_kterm_pty_bytes_total). Purpose: an AI-driven evidence-soak loop — the owner daily-drives kterm, a fires_on alert (kterm-soak-collect.md) tells the AI to read the digest and settle the

  003 S3 / #004 evidence-soak gates with real numbers instead of a manual

  report. Proves the loop on kterm first; graduation to the SDK + a Stack-wide pattern is gated on it settling a gate.