{"id":51723158,"url":"https://github.com/emosenkis/terminai","last_synced_at":"2026-08-05T22:00:35.995Z","repository":{"id":369548871,"uuid":"1081678603","full_name":"emosenkis/terminai","owner":"emosenkis","description":"Make your coding AI available in your shell","archived":false,"fork":false,"pushed_at":"2026-07-27T06:22:22.000Z","size":56407,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-27T08:09:10.813Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://terminai.app","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emosenkis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T06:10:17.000Z","updated_at":"2026-07-27T06:23:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/emosenkis/terminai","commit_stats":null,"previous_names":["emosenkis/terminai"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/emosenkis/terminai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosenkis%2Fterminai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosenkis%2Fterminai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosenkis%2Fterminai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosenkis%2Fterminai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emosenkis","download_url":"https://codeload.github.com/emosenkis/terminai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emosenkis%2Fterminai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36322586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-05T02:00:06.619Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-17T15:00:32.875Z","updated_at":"2026-08-05T22:00:35.980Z","avatar_url":"https://github.com/emosenkis.png","language":"Rust","funding_links":[],"categories":["Harnesses \u0026 orchestration"],"sub_categories":["Agent infrastructure"],"readme":"# Terminai\n\nTerminai is a transparent terminal wrapper that puts a real AI CLI in an on-demand overlay. Use your shell normally, then press `Ctrl+Space` to open Codex, Claude Code, OpenCode, or a custom agent with live terminal context and approval-gated access to suggested shell input.\n\n**Website:** [terminai.app](https://terminai.app)\n\n[![Terminai demo](https://asciinema.org/a/cGPNcuBwIpYDSUY4.svg)](https://asciinema.org/a/cGPNcuBwIpYDSUY4)\n\n\u003e Terminai is in alpha. I use it as my daily driver, but you should always keep an ordinary shell profile available as a fallback.\n\n## What Terminai does\n\nTerminai starts one shell (or a command you provide) inside a PTY and renders it with VT100 emulation while preserving the host terminal's native scrollback and copy behavior. The wrapped terminal remains the primary interface; Terminai stays out of the way until the overlay is activated.\n\nThe overlay is another PTY-backed terminal running the agent's actual CLI. Terminai does not implement a model client, choose a provider, or hold model API keys. Authentication, model selection, conversation state, and network access remain the responsibility of the selected agent CLI.\n\nTerminai gives compatible agents controlled access to the shell through a local MCP server:\n\n- Read the visible terminal and recent scrollback, after configurable pattern-based privacy filtering.\n- Inspect session context such as the working directory, shell, OS, dimensions, mouse mode, and bracketed-paste state.\n- Receive context updates as the wrapped session changes.\n- Queue exact shell input for the user to review and approve or deny.\n- Check the state of the most recent suggestion.\n\nSuggested input is never written to the wrapped shell without user approval.\n\n## Installation\n\nTerminai supports macOS and Linux and has been minimally shown to work on Windows.\n\n### Homebrew\n\n```sh\nbrew install emosenkis/tap/terminai\n```\n\nThe formula installs a prebuilt release binary, so Rust is not required.\n\n### GitHub release\n\nDownload the archive for your platform from [GitHub Releases](https://github.com/emosenkis/terminai/releases), unpack it, and place `terminai` somewhere on your `PATH`.\n\n### Build from source\n\nThe repository uses Git submodules for its patched Ratatui and rat-salsa dependencies.\n\n```sh\ngit clone --recurse-submodules https://github.com/emosenkis/terminai.git\ncd terminai\ncargo install --path src\n```\n\n## Quick start\n\nFirst install and authenticate at least one supported agent CLI, for example:\n\n```sh\ncodex login\n# or authenticate with Claude Code using its CLI\n```\n\nThen launch Terminai:\n\n```sh\nterminai\n```\n\nWith no command, Terminai resolves the configured shell (or the invoking shell\non Windows). To wrap a specific command and its arguments instead:\n\n```sh\nterminai -- zsh -l\n```\n\nUse the terminal normally and press `Ctrl+Space` when you want the agent. Press `Ctrl+Space` or `Esc` to return to the shell. When an agent queues input, review it and press `y` to approve or `n` to deny; these bindings are configurable.\n\nWhile the agent overlay is open, press `F10` for Terminai Controls, `F11` to\ntoggle fullscreen, or `F9` for Layout Mode. In Layout Mode, `+`/`-` changes\nAI height, `p` toggles top/bottom, `g` cycles the guest display, and `f`\ntoggles fullscreen. Approval mode, agent switching, history clearing, and all\nlayout settings are also available through the menus.\n\nFor a terminal-emulator workflow, create a separate profile whose command is `terminai` and keep the emulator's normal shell profile as a fallback.\n\n## Configuration\n\nTerminai loads YAML from `$XDG_CONFIG_HOME/terminai/terminai.yaml`, or\n`~/.config/terminai/terminai.yaml` when `XDG_CONFIG_HOME` is unset. On Windows\nit uses `%APPDATA%\\\\terminai\\\\terminai.yaml` (with logs/cache in\n`%LOCALAPPDATA%\\\\terminai`). Generate the default configuration and prompt\ntemplate with:\n\n```sh\nterminai init-config\n```\n\nOn Windows, use a current Windows Terminal with `pwsh.exe`, `powershell.exe`,\nor `cmd.exe`; see [Windows support](docs/windows-support.md) for the qualified\nenvironment and shell-selection precedence.\n\nThe default agent is Codex. A minimal explicit configuration is:\n\n```yaml\ninterface:\n  terminal-sync: true\n  chat-position: bottom\n  chat-height-percent: 50\n  guest-display: resize\n  key_bindings:\n    activate-overlay: Ctrl-Space\n    deactivate-overlay: Ctrl-Space\n    approve: y\n    deny: n\n    layout-mode: F9\n    control-panel: F10\n    toggle-fullscreen: F11\n\napproval-mode: always-ask\nagent:\n  preset: codex\n```\n\n`approval-mode` can be `always-ask` or `auto-approval`. Auto-approval sends\nevery agent suggestion directly to the shell without consulting the command\nrisk classifier. Terminai marks this mode with `⚠ AUTO-APPROVE`; enabling it\nin-app requires confirmation. In-app mode and agent changes last for the\ncurrent session only.\n\n`terminal-sync` defaults to `true` and brackets each frame with synchronized\nterminal updates to reduce tearing and flicker when the host reports support\nfor DEC mode 2026. Set it to `false` to disable the capability.\n`chat-position` accepts `top`, `bottom`, or `fullscreen`.\n`chat-height-percent` controls split layouts and is clamped to 20–80%.\n`guest-display` accepts `resize` (reflow the guest into the remaining space),\n`overlay` (draw AI over the unchanged guest), or `move` (shift/crop the\nunchanged guest away from AI). Runtime layout changes last for the session.\n\nThe same session settings can override `terminai.yaml` at startup:\n\n```sh\nterminai --approval-mode always-ask --agent claude \\\n  --chat-position top --chat-height-percent 60 --guest-display move\n```\n\nSwitch to another bundled preset by changing `agent.preset`:\n\n```yaml\nagent:\n  preset: claude # codex, claude, or opencode\n```\n\nThe Codex and Claude presets enable Terminai's local MCP server and inject the rendered context prompt automatically. OpenCode receives the context prompt; custom agent support can opt into MCP, the tool CLI, or both.\n\n### Presets and custom agents\n\nBuilt-in presets are compiled from [`config/codex.yaml`](config/codex.yaml), [`config/claude.yaml`](config/claude.yaml), and [`config/opencode.yaml`](config/opencode.yaml). User presets can extend a built-in preset and append arguments:\n\n```yaml\nagent:\n  preset: codex-fast\n\nagent-presets:\n  codex-fast:\n    extends: codex\n    show-in-switcher: true\n    extra-args:\n      - --model\n      - gpt-5\n```\n\nA fully custom agent configuration can render runtime values into its command-line arguments:\n\n```yaml\nagent:\n  kind: custom\n  command: my-agent\n  uses-mcp: true\n  uses-tool-cli: false\n  args:\n    - --mcp-url\n    - \"{{ mcp_url }}\"\n    - --context\n    - \"{{ context_prompt }}\"\n    - expr: '[\"--cwd\", cwd] if cwd else []'\n```\n\nString arguments are rendered as Minijinja templates. An `expr` entry must evaluate to an array of strings and can therefore emit zero, one, or multiple CLI arguments. Available values include `cwd`, `context_prompt`, `uses_mcp`, `uses_tool_cli`, `mcp_url`, `mcp_command`, `mcp_port`, and `tool_command`; the `json` and `toml` filters provide safe serialization for nested CLI configuration. The MCP bearer token is passed to the agent process in `TERMINAI_MCP_AUTH_TOKEN` rather than embedded in arguments.\n\n### Prompt customization\n\nThe bundled prompt is [`config/default.jinja`](config/default.jinja). A `default.jinja` in the Terminai config directory shadows it. You can also set `agent.prompt-template` to another template in that directory.\n\nCustom templates can extend the bundled prompt and override individual blocks:\n\n```jinja\n{% extends \"builtin/default.jinja\" %}\n{% block introduction %}Your customized introduction.{% endblock %}\n```\n\nThe generated [configuration reference](https://terminai.app/config.html) documents every field, and versioned JSON Schemas are published at `https://terminai.app/schema-v\u003cversion\u003e.json`.\n\nThe agent picker includes bundled presets and user presets unless a user\npreset sets `show-in-switcher: false`. Switching terminates the current agent\nsession after confirmation and launches a fresh one. “Clear AI-readable\nhistory” removes only Terminai's internal shell scrollback: the current screen\nand terminal emulator's native scrollback remain intact.\n\n## MCP interface and safety boundary\n\nTerminai serves an authenticated, local Streamable HTTP MCP endpoint to agent presets that enable it. The endpoint exposes:\n\n| Tool | Purpose |\n| --- | --- |\n| `check_for_updates` | Return pending context changes before the agent handles a new request. |\n| `read_terminal` | Return visible output and recent scrollback after configurable pattern-based privacy filtering. |\n| `get_terminal_context` | Return shell, cwd, OS, dimensions, and terminal mode state. |\n| `suggest_input` | Queue exact text for approval; it does not execute the text. |\n| `get_suggestion_status` | Report the latest queued suggestion and its disposition. |\n\nThe security boundary is deliberately narrow:\n\n- The selected agent CLI owns credentials, provider traffic, and model behavior.\n- Terminai itself does not upload terminal data or make model requests.\n- Terminal contents returned through MCP pass through configurable, pattern-based filtering; it is not a guarantee that secrets or private information are removed. By default it redacts credentials and strong personal identifiers but retains URLs, IP addresses, dates, postal codes, and technical diagnostics. Configure `privacy.patterns` with `default`, a category (`credentials`, `financial`, `identity`, `medical`, `crypto`, or `gitleaks`), or an entity type such as `btc-address`; prefix an entry with `-` to remove it, for example `[default, -btc-address]`. `privacy.strategy` supports `replace`, `mask`, `hash`, `encrypt`, and `redact`.\n- Agent-suggested input enters an approval flow before reaching the shell PTY.\n- Suggestions are classified as safe, caution, or dangerous to help the user review them; classification does not replace explicit approval.\n\nZero-install MCP setup depends on the agent supporting MCP configuration through CLI flags or environment variables.\n\n## Architecture\n\n```text\nhost terminal\n└── Terminai process\n    ├── wrapped shell/command PTY\n    │   └── VT100 state, native scrollback, input forwarding\n    ├── authenticated local MCP server\n    │   ├── terminal/context reads → privacy filter\n    │   └── input suggestions → classification → approval queue\n    └── agent CLI PTY\n        └── Codex, Claude Code, OpenCode, or custom command\n```\n\nImportant implementation areas:\n\n- `src/bin/terminai.rs`: application entry point, event loop, rendering, and overlay coordination.\n- `src/agent_launcher.rs`: preset resolution, Minijinja rendering, and agent launch plans.\n- `src/agent_terminal.rs`: PTY lifecycle and rendering for the agent CLI.\n- `src/mcp_host/`: authenticated MCP server built with `rmcp` and Streamable HTTP transport.\n- `src/agent_tools.rs`: suggestion state passed from MCP into the UI approval flow.\n- `src/command/`: parsing and safety classification for suggested shell input.\n- `src/privacy/`: minimal, best-effort filtering of sensitive terminal content.\n- `src/vt100/`, `src/proc/`, and `src/term/`: terminal emulation and PTY foundations initially derived from [mprocs](https://github.com/pvolok/mprocs).\n\nSee [the architecture note](https://terminai.app/llm_architecture.html) for a compact runtime diagram.\n\n## Development\n\nUse a recent stable Rust toolchain and initialize the submodules before building.\n\n```sh\ngit submodule update --init --recursive\ncargo build -p termin\ncargo test -p termin\ncargo fmt --all -- --check\n```\n\nThe workspace patches crates.io dependencies to the local `ratatui`, `rat-salsa`, and Crossterm facade directories. Ratatui and rat-salsa contain changes required to preserve native terminal scrolling and copy behavior, so a source checkout without its submodules is incomplete.\n\nContributions, bug reports, and documentation improvements are welcome. Read [CLAUDE.md](CLAUDE.md) for repository guidance used by coding agents.\n\n## Acknowledgements\n\nTerminai uses terminal-emulation, host/guest terminal, and PTY-management code from [mprocs](https://github.com/pvolok/mprocs). It also uses project-specific forks of [Ratatui](https://ratatui.rs/) and [rat-salsa](https://github.com/thscharler/rat-salsa) for native scrolling and copy support.\n\n## License\n\nTerminai is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femosenkis%2Fterminai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femosenkis%2Fterminai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femosenkis%2Fterminai/lists"}