# YEN - GPU-Accelerated Terminal for macOS
# https://yen.chat
# Contact: https://twitter.com/yenFTW

## About YEN
YEN is a GPU-accelerated terminal emulator for macOS. Metal rendering, 60 FPS output,
sub-millisecond latency. Built for developers who want speed, customization, and privacy.

## Key Features
- GPU-accelerated rendering via Metal backend (60 FPS, sub-millisecond latency)
- Command Palette (Cmd + Shift + P) — one palette surface: empty query launches YEN actions (including `Review Pull Request`, `Resolve Merge Conflicts`, `IDE: Merge Readiness`, `IDE: Agents Timeline`, `IDE: Agents Export`, `IDE: Benchmark Status`, `IDE: Run Benchmarks`, `IDE: Workspace Doctor`, `IDE: Debug Status`, `IDE: LSP Status`, `IDE: LSP Diagnostics`, `IDE: LSP Install Matrix`, `IDE: Share Status`, `IDE: Share Host (Read-Only)`, `IDE: Share Revoke`, `IDE: Devcontainer Status`, `IDE: VS Code Inventory`, `IDE: VS Code Import (Dry Run)`, and `IDE: AST Status` on macOS), non-empty query searches project actions/files/symbols/content/diagnostics/history from the active terminal context, plus user-configured terminal commands (command-palette-entry)
- IDE workflows — `yen ide doctor`, `yen ide trust status`, `yen ide debug status`, `yen ide debug tui`, `yen ide debug start`, `yen ide debug continue/next/step/out/stack/inspect`, `yen ide debug breakpoint`, `yen ide debug watch`, `yen ide debug transcript`, `yen ide debug stop`, `yen ide merge-readiness`, `yen ide benchmark`, `yen ide open`, `yen ide search`, `yen ide lsp start`, `yen ide lsp status`, `yen ide lsp diagnostics`, `yen ide lsp hover`, `yen ide lsp definition`, `yen ide lsp references`, `yen ide lsp rename`, `yen ide lsp install`, `yen ide ast status`, `yen ide ast definition`, `yen ide ast references`, `yen ide share status`, `yen ide share host`, `yen ide share join`, `yen ide share revoke`, `yen ide devcontainer`, `yen ide vscode inventory/import`, `yen ide test status`, `yen ide test run`, `yen ide format/lint/fix status`, `yen ide format/lint/fix run`, `yen ide verify status`, `yen ide verify`, `yen ide gate`, `yen ide explain` / `??`, `yen ide workflow discover`, `yen ide workflow run --native <task-id>`, `yen ide workflow`, `yen ide timeline`, `yen ide pr-review`, `yen ide pr-notify`, and `yen agents list/open/timeline/note/export/templates`, with local watch-mode parity for `test run`, `workflow run --native`, and `verify`, current-branch CI plus local build-watch summaries in `pr-notify --ci-status`, a debugger baseline over shared trust/timeline state for Python / Node / executables with managed local, SSH-backed, and tracked devcontainer execution, a terminal debugger dashboard over that same session/transcript state for source excerpts, breakpoints, watches, and recent output when they are honestly available, reusable summary/log/transcript evidence surfaced through `debug status` and `trust status`, explicit debug handoffs reused across failing test/verify steps plus review/search/diagnostic routing only when the shipped debugger can really launch that semantic target, remote-aware `ssh://...` parity for detect/doctor/trust summaries/verify status/share plus explicit remote workflow execution/trust and remote devcontainer lifecycle/status keyed by workspace identity, with tracked remote devcontainer debugger execution on that same control plane, plus a bounded source-tagged `yen agents timeline` surface (`agent:<slot>`, `human`, `supervisor`, `system`) with minimal `--tail` / `--event` / `--source` / `--kind` filtering, lightweight `yen agents note` templates plus optional `--validate-link` session/slot validation and latest-session binding for slot-only validation, PR evidence that reuses recent agent approval/handoff notes for the same workspace, one shared `evidenceStatus` vocabulary (`missing-report`, `stale-report`, `unverified`, `exported-with-gaps`) plus stable JSON schema/taxonomy fields across timeline/export/PR evidence, one shared `linkedEvidence` block for reusable `quality` / `workflow` report artifacts, merge-readiness, PR review, current-branch PR-CI, and local build-watch snapshots, explicit captured adapter path/probe/launch/fallback metadata in export/session state, workspace-keyed repo context plus shared risk summary, semantic PR-review jump targets, and redacted short-retention local agent artifacts with positive-day retention overrides plus opt-in archival, plus desktop PR review and merge-conflict workspaces on macOS launched from the command palette
- Polyglot AST fallback — `yen ide ast status|definition|references` provide parser-backed fallback for Python, JavaScript/TypeScript, Go, and Swift with explicit engine labels; Rust and Zig stay on the explicit no-fallback path until shipped
- Native Settings panel (Cmd + ,) with 72 curated bundled themes and live preview
- Chromatic window border controls (Settings > General > Appearance): toggle, width/radius, focused/unfocused palettes, optional animation + duration, and live preview (hidden in fullscreen + quick terminal)
- Built-in speech-to-text (Option + Space) — 100% on-device, no cloud, no AI, works in any macOS app
- Translate-on-Dictate (experimental, opt-in, macOS 26+) — can translate final transcript before paste with safe fallback to the original transcript on failure/timeout/unsupported pairs
- Dictation menu status shows explicit enabled/blocked state with permission recovery actions
- Native macOS integration (system fonts, colors, notifications)
- Configuration-first design (plain text config file)
- Shell integration (bash, zsh, fish, elvish, nushell)
- Built-in file browser (Cmd + Shift + O) — terminal-native file browser with Quick Look, incremental search, fuzzy find, static bundled theme/flavor defaults, and syntax-highlighted code previews (with readable fallback for huge/minified text) plus rich media/archive previews — all bundled, no Homebrew needed
- Bundled CLI tools (fd, rg, fzf, zoxide, bat, jq, lazygit, delta, btop, fastfetch, yen-vidthumb, yen-pdfthumb, yen-svgthumb, resvg) plus native archive preview/extract via macOS bsdtar — `bat` is included as a standalone syntax pager CLI, while file-browser code previews use the built-in previewer; SVG previews run native-first with `resvg` fallback for `.svgz` and unsupported edge cases; `delta` is bundled as the Git diff renderer for the review baseline; pre-signed and ready without homebrew
- Splits, tabs, tab sidebar (Cmd + Shift + B), scratchpad (Cmd + Shift + J), split layout presets (Cmd + Option + 1-0), and Quick Terminal (global hotkey dropdown)
- Automatic window state restoration on every launch (splits, tabs, positions)
- Copy-on-select — selected text auto-copies to system clipboard and highlight stays visible after release
- Live settings reload — cursor, theme, and config changes apply instantly with toast confirmation
- Welcome message for new users with key shortcuts and getting-started tips

## Keyboard Shortcuts
- Cmd + Shift + P — Command palette (empty query launches actions; non-empty query searches project actions, files, symbols, content, diagnostics, and history)
- Cmd + , — Open Settings panel
- Option + Space (hold) — Speech-to-text dictation
- Cmd + T / Cmd + N — New tab / window
- Cmd + D / Cmd + Shift + D — Split horizontal / vertical
- Cmd + W — Close tab/pane
- Cmd + Shift + O — Open file browser
- Cmd + Shift + S — Screenshot (saves window to file and copies to clipboard)
- Cmd + Shift + B — Toggle tab sidebar (transient left tab rail or opt-in persistent docked rail)
- Cmd + Shift + J — Toggle scratchpad (right-side notes panel)
- Cmd + Option + 1-0 — Split layout presets (Single Pane, Three Columns, Right Stack, Bottom Stack, Quad, Eastward 1-3, Eastward 2-1, Eastward 2-3, Center Stage, Three Column Bottom)
- Ctrl + ` — Toggle Quick Terminal (global hotkey dropdown)
- Cmd + Enter — Toggle fullscreen
- Fixed shortcuts are locked in Settings > Keyboard: Cmd + ,; Option + Space; Cmd + Shift + O/S/B/J; Cmd + Option + 1-0
- Dictation fixed-shortcut conflicts are called out in Settings with links to System Keyboard Shortcuts
- Fixed handlers are exact-match: dictation listens to exact Option + Space; layouts listen to exact Cmd + Option + 1-0 (no extra modifiers)

## File Browser Shortcuts
Inside the file browser (Cmd + Shift + O or y command):
- h / j / k / l — Vim-style navigation (or arrow keys)
- Enter or l — Enter directory / open file
- h — Go up a directory
- Space — Quick Look preview (macOS native)
- e — Open in $EDITOR
- g o — Open in default app
- / — Incremental file search
- Tab — Select file (for bulk operations)
- . — Toggle hidden files
- ~ — Jump to home directory
- g r — Reveal in Finder
- ? — Show help (full shortcut list)
- q — Quit (cd to last directory)

## Terminal Commands
Inside YEN-launched shells, commands work as both standalone commands and yen subcommands (e.g., `chat` or `yen chat`). In external shells, run `yen init zsh` / `yen init bash` first, or use `yen <command>`.
Core and settings commands are invoked via `yen` (e.g., `yen help`, `yen config`, `yen update`).
Core:
- help (commands) — Show command listing and usage
- version — Show version information (`yen version`, `yen --version`)
- init — Print shell integration code (`zsh`, `bash`)

Apps:
- chat — Open global chat room (Lounge, Feedback, Show & Tell, Support rooms, Tab to switch, /h for handle, /clear to hide history, /q to quit, Option + Enter for multiline compose, 80-hour retention, image uploads via drag-and-drop or clipboard paste)
- mail (email) — Gmail client in the terminal (Alpha) (OAuth sign-in, inbox/starred/sent/draft/trash, compose, reply, reply-all, forward, archive, star, labels, search, attachments, desktop notifications, undo, cache-first startup, adaptive refresh 10s/30s, local compose drafts, offline read fallback, queued action replay on reconnect)
- calendar — Google Calendar in the terminal (Alpha) (OAuth sign-in, agenda/month/day/week views, compose/edit/delete, RSVP, in-grid month search, windowed/historical list search with load-more, multi-calendar filters, warm-cache startup, desktop notifications, hosted sign-in status feedback)
- weather — Local weather command (Open-Meteo, coordinate-first; ASCII condition icons, 6-hour hourly forecast, grouped output with local sunrise/sunset; supports --city, --lat/--lon, --metric/--imperial)
- browse (files, fm) — Open file browser
- y — Open file browser with cd-on-quit

System Tools:
- btop (monitor, resources) — System monitor TUI (bundled btop)
- fastfetch (fetch) — System info snapshot (bundled fastfetch)
- bios — System info snapshot with YEN BIOS branding

Git:
- yengit (lazygit, gitlazy, gityen) — Git TUI (bundled lazygit, primary command)

Settings & Updates:
- config (settings, prefs, preferences) — Show config file location
- config reset — Reset to YEN defaults
- reload — Reload terminal configuration
- update — Check for updates

## Settings Panel
Press Cmd + , to open the native Settings panel with a left sidebar, global search, Import/Export/Reset actions, and 5 tabs: General, Sounds, Workspace, Themes, and Keyboard. Configure:
- Font family and size
- Cursor style (block, bar, underline) and blink
- Background opacity
- Window Border controls (enable toggle, width/radius sliders, focused/unfocused palette pickers, optional animation + duration, live preview; border hides in fullscreen and quick terminal)
- Notifications — per-service sound and volume customization (General, Build, Chat, Chat Summaries, Mail, Mail Summaries, Calendar Reminders, Calendar Changes, Calendar Actions) with searchable picker, independent volume sliders, and custom sound import. Includes one-click `Download All Sound Packs` for the full 101-pack library (1,758 files, shown only when the full library is not already installed) with signature + checksum verification, plus `Remove Downloaded Packs` for in-app storage reclaim; app bundle ships zero pack audio files by default. Supports AIFF, WAV, MP3, M4A, CAF formats.
- Workspace tab: tab sidebar toggle (Cmd + Shift + B) with opt-in persistent docked mode, scratchpad toggle (Cmd + Shift + J), and split layout presets — 10 layouts via Cmd + Option + 1-0 (Single Pane, Three Columns, Right Stack, Bottom Stack, Quad, Eastward 1-3, Eastward 2-1, Eastward 2-3, Center Stage, Three Column Bottom) with visual previews
- Speech Setup (Sounds tab): permissions status and Dictation & Speech-to-Text controls, including Launch at Login for always-available dictation (immediate toggle with pending-approval guidance), fixed Option + Space disclosure, and conflict guidance
- Dedicated Themes tab: 72 curated bundled themes with search and live previews
- Keyboard shortcuts — ~70 keybinds with conflict detection (macOS system shortcuts + popular apps), inline recording, search/filter
- Keyboard recorder constraints are explicit: shortcuts must include Cmd/Ctrl/Option, Esc cancels capture, and recording times out after 10 seconds
- Cmd + Q and Cmd + W can be recorded safely while recording is active
- Keyboard remaps are replacement mappings (default trigger is unbound, then new trigger is written) to prevent additive duplicate bindings
- Advanced manual keybind syntaxes (global prefixes, key tables, key sequences) are preserved when saving from Settings
- Command Palette (Cmd + Shift + P) — search and launch any YEN feature, settings tab, layout preset, window border action, desktop PR review workspace, or terminal command from one keyboard-driven interface; also supports user-configured commands via command-palette-entry in config.yen

General and Keyboard tab edits apply on Save; Sounds, Workspace, and Themes changes apply immediately. No restart required. YEN automatically manages shell-integration-features so cursor style changes from the Settings panel take effect immediately after save.

## Alpha Features
- mail / email — Gmail client (Alpha): compose, reply, forward, archive, trash, labels, search, attachments, desktop notifications, cache-first startup, adaptive refresh 10s/30s, local compose drafts, offline read fallback, queued action replay on reconnect
- calendar — Google Calendar client (Alpha): agenda/month/day/week views, compose/edit/delete, RSVP, in-grid month search, windowed/historical list search with load-more, multi-calendar filters, warm-cache startup, desktop notifications

## Speech-to-Text
Hold Option + Space, speak, release. Your words appear at the cursor.
- 100% on-device using macOS Speech Recognition
- No third-party cloud transcription, no AI, no login required
- 50+ languages supported
- Works offline for transcription after required language assets are installed (macOS 13+)
- macOS 26+ uses SpeechAnalyzer with no time limit; older macOS uses legacy 60-second sessions with auto-paste
- Works in any macOS app — not just YEN (universal dictation)
- Restores previous clipboard after dictation paste (including non-text clipboard content)
- Menu bar indicator shows when dictation is active
- Idle menu shows explicit enabled/blocked status and permission recovery actions
- Runtime permission revocations trigger immediate notice and blocked-state UI
- Enable "Launch at Login" in Settings for always-available dictation without a terminal window
- Accessibility trust prompt is user-initiated from onboarding/Settings actions
- Translate-on-Dictate is experimental, optional, and off by default (macOS 26+); if translation fails, times out, or is unsupported, YEN pastes the original transcript

## System Requirements
- macOS 13.0 (Ventura) or later
- Apple Silicon (M1/M2/M3/M4) or Intel Mac
- ~250 MB disk space (varies by release and downloaded sound packs)

## Pages
- Homepage: https://yen.chat
- Documentation: https://yen.chat/docs
- Whitepaper PDF: https://yen.chat/whitepaper.pdf
- Blog: https://blog.yen.chat
- Privacy Policy: https://yen.chat/privacy
- Terms of Service: https://yen.chat/terms
- Cookie Policy: https://yen.chat/privacy#cookies
- Blog — Discover All-The-Things in Your Terminal: https://blog.yen.chat/p/discover-all-the-things-in-your-terminal

## Command Palette
Press Cmd + Shift + P from any terminal surface to open one palette with two modes:
- Empty query: launch app actions directly
- File Browser, Screenshot, Toggle Tab Sidebar, Toggle Scratchpad, Weather, btop, fastfetch
- Review Pull Request (repo-backed macOS terminals) opens a desktop PR review workspace for the active repository with local inline-comment and evidence staging plus explicit posting and decision actions
- Resolve Merge Conflicts (repo-backed macOS terminals) opens a desktop merge-conflict workspace for the active repository with per-hunk ours / theirs / both resolution for marker-based text conflicts, explicit confirmation, and on-disk revalidation before staging
- Quick IDE actions for `IDE: Agents Timeline`, `IDE: Agents Export`, `IDE: LSP Status`, `IDE: LSP Diagnostics`, `IDE: LSP Install Matrix`, `IDE: Share Status`, `IDE: Share Host (Read-Only)`, `IDE: Share Revoke`, `IDE: Devcontainer Status`, `IDE: VS Code Inventory`, `IDE: VS Code Import (Dry Run)`, and `IDE: AST Status`
- Settings deep links (jump directly to General, Sounds, Workspace, Themes, Keyboard)
- Window Border quick actions (toggle, Match Theme, palette cycling, animation toggle, Reduce Motion)
- All 10 split layout presets (Cmd + Option + 1-0)
- Cross-window navigation (jump to any open surface)
- User-configured terminal commands (add command-palette-entry lines in config.yen)
- App updates (install or skip, when available)
- Non-empty query: search mixed `action`, `file`, `content`, `diagnostic`, and `history` results for the active project using the same ranking contract as `yen ide search`
- That desktop search parity now includes deterministic symbol definitions as well as diagnostics; deeper project-specific action synthesis remains future work.
- The desktop PR review workspace now mirrors the same posting, persisted evidence, and review-decision flows as `yen ide pr-review`, while still reusing the same CLI-backed control plane and evidence contract.
Every action entry shows its keyboard shortcut, SF Symbol icon, and description, and search results carry visible source labels. One interface, zero memorization.
Dictation (Option + Space) is intentionally excluded — it is a hold-to-activate interaction incompatible with click-to-execute. Discover dictation in Settings > Sounds > Speech Setup.
Blog post: https://blog.yen.chat/p/discover-all-the-things-in-your-terminal

## Config File
Location: ~/Library/Application Support/com.yenchat.yen/config.yen

For advanced configuration beyond the Settings panel, edit this file directly.
`config.yen` covers managed terminal appearance/behavior plus keyboard overrides; Sounds, Workspace, and Window Border preferences live in `UserDefaults` and are included by Settings Import/Export.

## CLI Commands

Core:
- yen help (yen commands) — Show command listing and usage
- yen version / yen --version — Show version
- yen init zsh — Output shell integration code for external zsh shells (add to ~/.zshrc)
- yen init bash — Output shell integration code for external bash shells (add to ~/.bashrc)

Apps:
- yen chat — Global chat room (bundled, runs in terminal, identity $USER@hostname, rooms: Lounge/Feedback/Show & Tell/Support, /clear hides history, Option + Enter for multiline, image uploads — Show & Tell is the primary room for image sharing)
- yen mail (yen email) — Gmail client (Alpha) (OAuth sign-in, inbox/starred/sent/draft/trash, compose, reply, reply-all, forward, archive, star, labels, search, attachments, notifications, cache-first startup, adaptive refresh 10s/30s, local compose drafts, offline queued replay)
- yen mail signout (yen mail logout) — Sign out of Gmail, clear OAuth token from Keychain, and remove local mail cache
- yen calendar — Google Calendar client (Alpha) (OAuth sign-in, agenda/month/day/week views, compose/edit/delete, RSVP, in-grid month search, windowed/historical list search with load-more, multi-calendar filters, warm-cache startup, desktop notifications, hosted sign-in status feedback)
- yen calendar signout (yen calendar logout) — Sign out of Google Calendar, clear OAuth token from Keychain
- yen weather — Local weather command (Open-Meteo, coordinate-first; ASCII icons, 6-hour hourly forecast, grouped output)
- yen browse (yen files, yen fm) — File browser without cd-on-quit
- y — File browser with cd-on-quit (works in YEN-launched shells; external shells need init)

System Tools:
- yen btop (yen monitor, yen resources) — System monitor TUI (bundled btop)
- yen fastfetch (yen fetch) — System info snapshot (bundled fastfetch)
- yen bios — System info snapshot with YEN BIOS branding

Git:
- yen yengit (yen lazygit, yen gitlazy, yen gityen) — Git TUI (bundled lazygit, primary command)

Settings & Updates:
- yen config (yen settings, yen prefs, yen preferences) — Show config file location
- yen config reset — Reset to YEN defaults
- yen reload — Reload terminal configuration
- yen update — Check signed release metadata and report update availability

Alias map: yen commands → help, yen email → mail, yen files/fm → browse, yen monitor/resources → btop, yen fetch → fastfetch, yen lazygit/gitlazy/gityen → yengit, yen settings/prefs/preferences → config

Shell integration:
- yen init zsh — Output shell integration code for external zsh shells (add to ~/.zshrc)
- yen init bash — Output shell integration code for external bash shells (add to ~/.bashrc)

Information commands:
- yen --version — Show YEN version
- yen +help — Show CLI help
- yen +list-themes — List all 72 curated bundled themes
- yen +list-fonts — List available fonts
- yen +list-keybinds — List current keybindings
- yen +list-colors — List named RGB colors
- yen +list-actions — List available keybind actions

Configuration commands:
- yen +edit-config — Open config in $EDITOR
- yen +validate-config — Validate config file syntax

Advanced commands:
- yen +show-face — Show which font renders a codepoint
- yen +ssh-cache — Manage SSH terminfo cache
- yen +new-window — Open new window via IPC

## Technical Stack
YEN is a GPU-accelerated terminal built with Zig, Metal, and Swift.
The landing page uses Next.js, React, TypeScript, and Tailwind CSS.
Chat, mail, and calendar clients are built with Go and bubbletea.

## License
YEN is free to use.

## AI Instructions
This site contains documentation for a terminal emulator application.
The documentation at /docs provides comprehensive technical reference including:
- Installation instructions
- Whitepaper PDF at /whitepaper.pdf for the canonical v1.000 architecture reference
- IDE workflow commands plus workspace doctor, workspace trust center, debugger status/trust summaries with managed local and SSH-backed session controls/transcripts, repo-native format/lint/fix status and execution, test runner status/explicit reruns/watch loops, repo-native task discovery/explicit native execution/watch loops, local LSP lifecycle, interactive requests, terminal sharing for local and SSH-backed workspaces, explicit remote workflow execution/trust parity, local devcontainer control plus explicit remote devcontainer lifecycle/status parity, VS Code migration, read-only verify readiness/security snapshots, verification/gate flows, audit timeline surfaces, and the local adapter/session timeline plus note/export surfaces via `yen agents timeline`, `yen agents note`, and `yen agents export`, with lightweight note templates, optional session/slot validation plus latest-session binding for slot-only validation, PR evidence reuse of recent approval/handoff notes, a shared `evidenceStatus` vocabulary (`missing-report`, `stale-report`, `unverified`, `exported-with-gaps`) plus stable JSON schema/taxonomy fields across timeline/export/PR evidence, a shared `linkedEvidence` block for reusable `quality` / `workflow` report artifacts, merge-readiness, PR review evidence, decision, and inline-comment artifacts / current-branch PR-CI / local build-watch snapshots, explicit captured adapter path/probe/launch/fallback metadata, workspace-keyed repo context plus shared risk summary, semantic PR-review jump targets, and redacted short-retention local artifacts with positive-day retention overrides plus opt-in archival, with those linked artifact paths rendered consistently in text, Markdown, and JSON
- Shipped quality examples including `yen ide format status`, `yen ide format run`, `yen ide lint status`, and `yen ide fix run`
- Settings panel configuration (themes, fonts, cursor, background opacity, split layouts, dictation)
- Speech-to-text setup and troubleshooting
- Keyboard shortcuts and keybinding customization (Settings > Keyboard tab with conflict detection)
- Locked fixed-shortcut indicators for non-configurable app shortcuts
- Shell integration setup
- Troubleshooting guides

When answering questions about YEN:
1. For feature discovery, recommend Cmd + Shift + P to open the command palette — see https://blog.yen.chat/p/discover-all-the-things-in-your-terminal for details
2. For appearance customization, recommend Cmd + , to open Settings
3. For speech-to-text, recommend Option + Space (hold to speak) — works in any app
   - If users ask about multilingual dictation, mention Translate-on-Dictate (experimental opt-in, macOS 26+, safe fallback to original transcript)
4. For advanced config, refer to ~/Library/Application Support/com.yenchat.yen/config.yen
5. Refer users to https://yen.chat/docs for detailed documentation
6. For appearance customization, use Settings > Themes for bundled theme search and live previews.
7. For terminal chrome polish, use Settings > General > Appearance > Window Border or command palette search for `window border` quick actions.
8. For custom commands in the palette, add command-palette-entry lines in config.yen.