OakTerm

A GPU-accelerated, extensible terminal emulator with a plugin-driven process dashboard and context-aware shell.

Status: Active Implementation — Phase 0 terminal foundation is implemented; the next roadmap focus is Phase 1 multiplexer work.

Philosophy

The terminal is the oldest developer tool that still works. It doesn't need to become an IDE, a chat app, or an agent dashboard. It needs to stay a terminal — but one that's aware of what you're doing and stays out of your way until you need it.

Core Principles

1. Performance is non-negotiable. The terminal must be the fastest thing on your screen. Sub-frame input latency. 5ms cold start. Plugins never block the render loop. If a feature makes typing feel slower, it doesn't ship.
2. Extensible by design. The core is a fast, minimal rendering and multiplexing engine. Everything else — the sidebar, agent management, smart autocomplete, even the browser — is a plugin. The core's job is to provide the right primitives so plugins can build anything.
3. Secure by default. Terminals handle passwords, API keys, and production access. Escape sequence injection is mitigated, plugin permissions are capability-based, clipboard reads are blocked by default, and the Lua config sandbox has no shell access. Security defaults are strict and relaxable, never the other way around.
4. Abstracted at every seam. The core defines traits/interfaces, not concrete implementations. GPU backend, WASM runtime, text shaper, platform layer — all behind abstractions. If something better comes along, swap it in without rewriting the terminal.
5. Accessible from day one. Zero modern GPU-rendered terminals have functional screen reader support. We ship with AccessKit integration, a full accessibility tree, high-contrast themes, and keyboard-only navigation. Accessibility is in the core, not a plugin.
6. Everything is a pane. Agents, dev servers, test watchers, web views, shells — they're all panes. The terminal just knows a little more about each one.
7. The plugin is the product. We don't ship features — we ship a platform and a set of bundled plugins. If a plugin can't do something, the answer is to improve the core API, not to hardcode the feature.
8. Debugging is built in. :debug gives you full diagnostics — input, escape sequences, plugin state, performance, per-pane info. oakterm doctor checks your environment. When something breaks, you shouldn't have to guess.

Principles

• Zero telemetry. No login. No account. No phoning home. Ever.
• AI features are opt-in, BYOK, and work with local models.
• Open protocols — Kitty graphics, standard escape sequences, WASM plugins.
• Platform-native — AppKit on macOS, GTK on Linux, WinUI on Windows. All three from day one. Not Electron.
• Replaces tmux, not complements it.
• Memory-conscious — tiered scroll buffer, per-pane budgets, no pre-allocation.
• MPL 2.0 licensed — core stays open source, plugins can be any license.

Documentation

ideas/          Exploration — brainstorming, research, design sketches
docs/adrs/      Decisions — resolve open questions from ideas
docs/specs/     Contracts — formal definitions that code must satisfy

Ideas explore possibilities. ADRs resolve questions that ideas surface. Specs formalize decided designs into implementation contracts.

Idea Docs

Core

Doc	Topic
Architecture	Layer stack, Rust, server/client model
Renderer	GPU (wgpu), fonts, fallbacks, ligatures, opacity, color, images
Multiplexer	Workspaces, splits, floating panes, SSH domains, session persistence
Command Palette	Unified fuzzy launcher with prefix filters
Configuration	First launch setup, settings palette, flat + Lua, dark/light themes
Abstraction Layer	Trait seams for swappable backends across all platforms
Shell Integration	Prompt markers, semantic zones, scroll-to-prompt, notifications
Smart Keybinds	Context-aware Ctrl+C/V, hints mode, input broadcast, env coloring
Health Check	Neovim-style :health with actionable diagnostics
Terminal Fundamentals	Cursor, bell, scrollbar, padding, text styles, env vars, links, process handling

Features (Bundled Plugins)

Doc	Topic
Sidebar	Collapsible process dashboard — agents, services, watchers, shells
Context Engine	Smart autocomplete, typed completions, ? NL commands
Agent Management	Worktree lifecycle, notifications, :merge / :diff
Harpoon	Pane bookmarks — Ctrl+1-6 direct jump, editable list

Cross-Cutting Concerns

Doc	Topic
Plugin System	WASM runtime, API primitives, capabilities, registry, manager
Performance	Targets, budgets, CI benchmarks
Memory Management	Tiered scroll buffer, per-pane budgets, memory attribution
Debugging	:debug commands, plugin profiling, blame chain
Security	Escape injection, plugin sandbox, secure input, clipboard controls
Accessibility	AccessKit, screen reader, color blindness, extensible a11y API
Theming	Deep customization, TOML format, inheritance, live preview
Internationalization	Unicode rendering, locale packs via plugins
Platform Support	macOS, Linux, Windows — all first-class
Updates	Every update path works, staged updates, rollback
Testing	Unit, integration, platform, perf, security, a11y, VT compliance
License	MPL 2.0 — core stays open, registry requires open source
Notifications	OS notifications, in-terminal banners, history, DND mode
Search	Regex search, cross-pane, per-command, persistent highlights
Conventions	Naming, config syntax, keybinds, file structure
Agent Control API	CLI for agents to interact with the terminal (oakterm ctl)

Remote & Headless

Doc	Topic
Remote Access & Headless Mode	Headless daemon on servers, native client connection, web client, tunnel-agnostic

Planning

Doc	Topic
Roadmap	Phased implementation: MVP → multiplexer → plugins → agents → networking
Brainstorm	Raw ideas: syntax highlighting, auto-tiling, status bar, multi-sidebar, error handling

Research

Doc	Topic
Pain Points	Community complaints that shaped the design
Inspiration	What we took (and left) from each terminal
Wishlist Features	Community-requested features, prioritized