YEN Terminal

Terminals have evolved dramatically over five decades. Each generation added capabilities — but also complexity, overhead, and distance from what makes a terminal great.

YEN doesn't reject progress — it rejects unnecessary complexity. Everything I add must make you faster without making you dependent on cloud services or AI subscriptions.

YEN starts with a native macOS terminal and layers IDE workflows around it. No Electron, no bundled Chromium runtime, and no second app to switch to.

Cmd + C and Cmd + V work the way you expect — everywhere. Including inside vim, nano, tmux, ssh, and any TUI app that normally swallows the keystroke. Read the full story on the blog: Why Cmd+V doesn't paste in your terminal — and how YEN fixed it.

No clipboard escape sequences, no opt-in flag, no config. This is the default and only behavior — it works in stock YEN out of the box.

YEN adds IDE workflows directly to the terminal. The yen ide commands cover workspace trust, search, debugging, local LSP, verification, adapters, and PR review without pushing you into a separate editor UI.

Quick start:

$ yen ide doctor
yen ide trust status
yen ide debug start src/app.py:12 --managed
yen ide lsp diagnostics
yen ide ast definition Widget
yen ide search verify
yen ide test run --failed
yen ide verify --quick --no-security
yen ide format run --dry-run --changed
yen ide workflow run --native package.json:test --dry-run
yen ide pr-review 123 --list-hunks
yen ide pr-review 123 --inline src/app.ts:42 --inline-body "Needs guard" --post
yen ide gate --dry-run -- git reset --hard
yen ide timeline --limit 20
yen agents timeline --tail 5
yen agents export --format json --output -

# Most subcommands accept --format json and --watch
# Most accept ssh://... and --devcontainer remote targets

On macOS, Cmd + Shift + P opens the command palette for actions and project search. It can jump straight to matching files and lines, and in trusted local repos it also launches dedicated PR review and merge-conflict workspaces.

YEN keeps these workflows local-first and explicit. Search, evidence, and review stay tied to the current workspace; remote ssh://... and --devcontainer targets stay clearly labeled; and local-only features such as --watch remain blocked instead of silently degrading.

Hold Option + Space in any app — YEN, Safari, VS Code, Notes, anything — speak, and release. Your words appear at the cursor. Audio never leaves your Mac. Read more on the blog.

Works on macOS 13+. On macOS 26+, YEN uses Apple's SpeechAnalyzer with DictationTranscriber, supports unlimited sessions, and can ask macOS to install missing language packs while Settings is frontmost.

In-app paste restores your previous clipboard shortly after paste; cross-app paste keeps the dictated text on the clipboard if delivery cannot be confirmed. Live Transcript Preview is available in the overlay. Translate-on-Dictate is opt-in, off by default, tied to the recognizer locale for that capture, and runs only when the selected language pair is already installed.

Pro tip: On older macOS, release and press again for longer content. Enable Launch at Login in Settings> Sounds > Speech Setup for dictation without a terminal window open.

Press Cmd + , to open Settings. The left sidebar stays on single-line rows for General, Sounds, Workspace, Themes, and Keyboard, while search, import, export, and reset live in the same window and most changes apply immediately across open tabs.

YEN includes 72 bundled themes with live previews and instant apply. Font, cursor, background image, opacity, and padding stay independent from theme selection. General also includes Window Border plus a background-image picker that imports PNG and JPEG assets into app-managed storage. The scope toggle below the import button sets whether the wallpaper renders per split (Each Split, the default) or as one shared backdrop behind the entire split tree (Whole Window). Workspace also exposes Tab Sidebar (Cmd + Shift + B) and Scratchpad (Cmd + Shift + J), plus Browser toggles for explicit terminal link capture and split targeting.

Sounds combines speech permissions, local speech readiness, Translate-on-Dictate controls, and per-stream notifications for General and Build. Each stream has its own sound, volume, and delivery mode (Off, Banner Only, Sound Only, Banner + Sound).

Keyboard lets you inspect conflicts and re-record editable shortcuts inline. Fixed shortcuts and duplicate-action rows stay read-only, and imported settings are validated before they apply.

Export and import include both config.yen and the Settings-managed preferences kept outside it, including workspace toggles, Browser link/split settings, theme-browser mode, Window Border, dictation preview/translation state, and notification routing. Portable exports intentionally exclude machine-local assets such as background images.

Machine-local state such as permission grants, Launch at Login, background images, and installed user themes stays on the current Mac.

In the command palette, search Settings: Themes, Settings: Sounds, Settings: Workspace, or Settings: Keyboard to open a specific tab.

Advanced configuration:

~/Library/Application\ Support/com.yenchat.yen/config.yen

Press Cmd + Shift + B to open the Tab Sidebar. In transient mode it appears as a floating left rail for the active terminal window. Use the header pin button, command palette, or Settings > Workspace to switch it into the persistent docked rail.

When YEN cannot trust the focused split's local path context (terminal multiplexers, remote sessions, detached commands, or empty project state), the sidebar omits cwd and git summaries instead of showing guessed metadata.

Each split pane can have a custom label displayed as a themed pill at the bottom-left corner. Open the command palette (Cmd + Shift + P) and search Rename Split Label to set or clear a label. Labels persist across window restores, tab switches, and session restarts.

Press Cmd + Shift + O to open the file browser in the active terminal. It does not open as a floating window or global sidebar, and it will not steal focus from another window. Browse directories, preview files, and manage the project without leaving the terminal.

Open the command palette with Cmd + Shift + P, search Browser, web preview, localhost, or dev server, and press Enter. Search terminal browser for Browser Split. YEN opens a native WebKit window or explicit split for docs, HTTPS pages, and localhost/loopback development servers.

YEN ships a branded AppleScript dictionary for local macOS automation. It is enabled by default and can be disabled in config.yen with macos-applescript = false. Target YEN by absolute bundle path when scripting a specific build.

AppleScript can create windows, tabs, and splits with an initial working directory and input. YEN-native overlays such as layout presets, scratchpad, tab sidebar, and PR review workspaces remain command-palette or config-driven instead of being cloned into a second scripting model.

on yenNewWindow(appPath, surfaceConfig)
	tell application appPath
		return «event GhstNWin» given «class GNwS»:surfaceConfig
	end tell
end yenNewWindow

set appPath to "/Applications/YEN.app"
set projectRoot to "/absolute/path/to/project"
set windowRef to yenNewWindow(appPath, {initial working directory:projectRoot, initial input:"git status" & linefeed})

tell application appPath
	get tty of terminal 1 of windowRef
end tell

Keyboard shortcuts:

CLI commands:

Commands run immediately inside YEN because bundled shell integration is already active there. In external shells, run yen init zsh or yen init bash once, then restart that shell so wrappers like y, weather, btop, and fastfetch route to YEN.

Need the complete command + alias reference? Run yen help. For full file browser shortcuts, press ? inside the file browser.

Custom keybindings:

Shortcut editing lives in Settings > Keyboard. For advanced changes, edit the config file directly.

• App won't open: Right-click YEN.app → Open, or allow in System Settings → Privacy & Security.
• Commands not found: YEN commands only work inside YEN terminal, not Terminal.app.
• Speech-to-text not working: Grant Accessibility, Microphone, and Speech Recognition permissions in System Settings → Privacy & Security. Dictation listens to exact Option + Space only (no Cmd/Ctrl/Shift). Check the menu bar dropdown for blocked-state recovery actions.
• Option + Space conflicts:Check for conflicts with input source, Spotlight, Alfred, or Raycast shortcuts. Use Settings > Keyboard for fixed-shortcut conflict guidance.
• Layout shortcut not firing: Use exact Cmd + Option + 1-0 with no extra modifiers and click a terminal window first. Layout presets are intentionally ignored while Settings or another utility window is key.
• Cursor style / blink not previewing: Changes are applied, but preview appears after you refocus a terminal window (unfocused terminals show a hollow block cursor).
• Opacity slider looks unchanged: Background opacity applies after app restart. Use Window Border for an immediate focus cue.
• Dictation menu shows blocked: Open Settings > Sounds > Speech Setup and click Re-check to verify local speech service status.
• File browser not opening: Verify the terminal window is focused, not the Settings panel or another window.
• Browser preview blocks a URL: Use HTTPS for remote pages or localhost / loopback HTTP for local development servers. File, data, JavaScript, blob, unknown-scheme, and non-local HTTP URLs are intentionally blocked.
• "command not found: y":Shell integration isn't active in this shell. In external shells, run yen init zsh (or bash) and restart that shell. In YEN, this points to disabled or stale bundled integration; use browse as a fallback and fix the app build rather than editing dotfiles.
• weather / btop / fastfetch runs a system command: In external shells, re-run yen init zsh (or bash), then restart that shell. In YEN, this points to missing or stale bundled integration rather than a dotfile problem.

Reset config to defaults:

$ rm ~/Library/Application\ Support/com.yenchat.yen/config.yen