Terminai: transparent terminal wrapper for on-demand AI

Terminai is a terminal wrapper written in Rust that embeds an AI agent CLI into an overlay without displacing the user's ordinary shell. The user runs Terminai instead of the shell directly—either with no arguments (in which case Terminai resolves the configured shell) or with a custom command. Inside, Terminai spawns two PTYs: one running the wrapped shell (or command), and one running the agent CLI. The wrapped shell is rendered with VT100 emulation and remains the focal point; the host terminal's native scrollback and copy behavior are preserved. When the user presses Ctrl+Space, the agent overlay appears, overlaid, moved aside, or in fullscreen depending on configuration. Pressing Ctrl+Space or Esc returns focus to the shell.

The agent's interface is the agent's own CLI—Codex, Claude Code, OpenCode, or a custom command. Terminai does not implement or manage the model client; instead, the agent CLI is responsible for authentication, provider traffic, model selection, and conversation state. Terminai connects to the agent via an authenticated local MCP (Model Context Protocol) HTTP server. The MCP server exposes five tools: check_for_updates (poll for terminal context changes), read_terminal (return visible output and recent scrollback after privacy filtering), get_terminal_context (return shell, cwd, OS, dimensions, terminal mode), suggest_input (queue exact text for review), and get_suggestion_status (report the latest queued suggestion). Suggested input is never written to the wrapped shell without user approval; when an agent queues input, the user reviews it and presses y to approve or n to deny. Suggestions are classified as safe, caution, or dangerous to help the user decide.

Terminai supports macOS and Linux and is distributed via Homebrew (brew install emosenkis/tap/terminai), GitHub Releases, or source build. Configuration is stored in YAML at $XDG_CONFIG_HOME/terminai/terminai.yaml (or ~/.config/terminai/terminai.yaml if XDG_CONFIG_HOME is unset; on Windows, %APPDATA%\terminai\terminai.yaml). The default agent is Codex. Built-in presets for Codex, Claude, and OpenCode are compiled from config files and can be extended or customized via user presets. Custom agents can be configured to receive runtime values (cwd, context prompt, MCP URL) rendered into their command-line arguments using Minijinja templates. The bundled prompt template can be overridden by creating a default.jinja in the Terminai config directory.

Privacy filtering is configurable: by default, Terminai redacts credentials and strong personal identifiers but retains URLs, IP addresses, dates, postal codes, and technical diagnostics. The privacy.patterns setting accepts categories (credentials, financial, identity, medical, crypto, or gitleaks) or entity types (e.g., btc-address), and privacy.strategy supports replace, mask, hash, encrypt, and redact. However, filtering is explicitly described as best-effort and is not a guarantee that secrets or private information are removed. Layout, approval mode, and agent switching are configurable at runtime via F10 (Terminai Controls), F11 (fullscreen), and F9 (Layout Mode, which allows +/- to adjust AI height, p to toggle top/bottom position, g to cycle guest display mode, and f to toggle fullscreen). The developer notes that Terminai is in alpha and recommends keeping an ordinary shell profile available as a fallback. The project is open-source under the MIT License and is hosted at github.com/emosenkis/terminai; the developer welcomes contributions, bug reports, and documentation improvements.

Terminai addresses a usability gap in terminal-based AI workflows: existing agent CLIs (like Codex or Claude Code) run standalone, breaking the user's shell context and requiring context-switching between tools. By wrapping the shell in a PTY and rendering it with VT100 emulation, Terminai keeps the shell as the primary interface while the AI agent runs in a parallel overlay, accessible on demand. The separation is not merely cosmetic—it enforces a deliberate approval boundary. Every AI suggestion must pass through user review before it touches the actual shell PTY, which materially reduces the risk that a misaligned or misbehaving agent corrupts the user's environment.

The security model is intentionally narrow: Terminai itself is stateless and untrusted. It does not authenticate with any AI provider, does not manage credentials, and does not make model requests. Instead, it delegates authentication, model selection, and conversation state to the agent CLI—Codex, Claude Code, or a custom command—which owns those responsibilities. The bridge between the wrapper and the agent is a local MCP server that exposes a small, read-only surface: terminal reads (filtered for sensitive data), session context (cwd, shell type, OS), and an input suggestion queue. This design means Terminai's attack surface is confined to local PTY manipulation and filtering logic, not API or model behavior.

No comments yet. Be the first to share your thoughts!