💻 LyShell

🔌 Your terminal, now AI's terminal too. LyShell is a Windows terminal with a built-in MCP server — letting Claude Code and other AI clients drive your SSH / Telnet / serial / local PTY sessions directly. Plus a Ctrl+Shift+P command palette, AI Harness workspaces with git-worktree isolation (TUI + embedded Web UI), document tabs, in-app web tabs, AI Agent launcher, plugin system, and Python scripting.

English | 简体中文

✨ Highlights · ⌨️ Command Palette · 🐋 DeepSeek Harness · 🌐 Web Tabs · 🔗 MCP · 🤖 AI Agents · 🧩 Plugins · 🚀 Quick Start · ❓ FAQ

---

✨ Highlights

🔗 MCP Server — Expose your terminals to Claude Code and other AI clients, with per-session authorization and audit log	🤖 Agent Launcher — Run Claude Code, Aider, Copilot CLI, or any custom CLI in a clean transient terminal
⌨️ Command Palette — Ctrl+Shift+P fuzzy-search everything: sessions, agents, workspaces, panels, docs	📄 Document Tabs — Read-only markdown preview with outline rail, plus built-in manual & inventory docs
🧩 Plugin System — Extend with Python or Node.js plugins, each running under granular permissions	🐍 Python Engine — Script terminal automation through a built-in LyShell API
🐋 DeepSeek Harness — Manage workspaces with variable sets & model presets, launch TUI and embedded Web UI side by side	🔐 Embedded Web UI — Run dsh web in an in-app <webview> tab, loopback-locked and URL-validated
🌳 Worktree isolation — Launch each Harness workspace in its own git worktree, so multiple agents on one repo never stomp each other	🌐 Web tabs — Open any URL as an in-app tab, with recent-access history and autocomplete

---

---

📥 Install

Download the latest portable build from Releases — no installation needed, just download and run.

Platform	Format	Architecture	Requirements
🪟 Windows	Portable (.exe)	x64	Windows 10 / 11, 64-bit

🚧 Currently Windows only — macOS and Linux builds are not yet available.

---

⌨️ Command Palette & Document Tabs

Command palette

Ctrl+Shift+P opens a full-screen command palette — one place to reach everything. Fuzzy-search across saved and running sessions, agents, dsh / codex / claude workspaces, variable groups, plugins, web and settings tabs. Slash commands work here too:

• /new — new connection dialog · /local — instant local terminal
• /help — open the built-in user manual · /ls — open an inventory doc

ESC dismisses; the tab strip has a palette entry too.

Document tabs & built-in docs

Read-only document preview as regular tabs — open several, split them, drag them. Four ways in: double-click in the file tree, drop a file onto the window, Ctrl+Shift+O for the system file dialog, or Ctrl+click a path right in the terminal. Markdown renders through the full doc pipeline — outline rail, zoom, theme — and links resolve across panes (including relative paths over SSH).

• Built-in manual — /help (or /help chinese / /help english) opens the user manual as a document tab.
• Inventory docs — /ls snapshots sessions / agents / variable groups / harness workspaces / plugins into a document tab; lyshell-action:// links inside jump straight to each object, and /ls <section> (e.g. /ls env) scopes to one section. Re-run or hit the tab's refresh button to re-inventory.

---

🔗 MCP Integration

This is what makes LyShell different. It serves as an MCP server, letting external AI clients like Claude Code control terminals via the MCP protocol — listing sessions, sending commands, reading output, transferring files, and managing connections.

📖 Configuration — see MCP Configuration. In most cases you don't configure anything by hand: launch an agent from the Agent Launcher and ask it to configure LyShell as its MCP server itself. Registration configs are emitted in JSON / CLI / TOML to fit different clients.

Tools

Tool	Capability	Description
list_sessions	read	List sidebar sessions
send_input	interactiveWrite	Send text, autoNewline support
send_and_wait	interactiveWrite	Send and capture response, strips echo + ANSI
execute_command	execute / localExecute	Run via independent exec channel (SSH only)
run_on_sessions	execute / localExecute	Broadcast command, max 50 sessions, concurrency 10
read_output	read	Read N lines of terminal output
upload_file / download_file	fileWrite	SFTP file transfer
read_file / stat_file / list_files	read	Remote file inspection, recursive + glob
create_session	sessionControl	Create/reuse saved session, auto-dedup by target
reconnect_session	sessionControl	Reconnect dropped connection
close_session	sessionControl	Disconnect without deleting the saved session
open_connection_dialog	sessionControl	Open the new-connection dialog for user input
read_session_notes	read	Read session summary, notes, tags
write_session_notes	sessionMetadataWrite	Update summary, notes, tags
wait_for_prompt	read	Wait for shell prompt or regex
tail_until	read	Poll output until pattern matches

Security

• 🔑 Per-session authorization — each terminal gets its own scoped permission
• 🚪 Capability gates — enforced server-side on every endpoint
• 🛡️ Destructive-command check — scans for rm -rf, dd if=, fork bombs
• 🔒 Shared PTY locking — MCP vs human input never collide
• 📊 Audit panel — calendar + filter + pagination, accessible from the title bar

⚠️ Full-screen TUI apps (vim, htop, less) are not supported over MCP — ANSI stripping garbles alternate-screen sequences. Use the LyShell UI native terminal instead.

---

🤖 AI Agents

Agent-agnostic terminal — no lock-in to any AI tool. Launch any CLI agent and it runs in a regular terminal with full scrollback, split panes, and IME support.

Agent	Command
🧠 Claude Code	claude
🛠️ OpenAI Codex	codex
🤝 Aider	aider
🐙 Copilot CLI	gh copilot

First-class Harness agents — dsh, codex, and claude are first-class in the Harness panel: each gets its own left-rail tab, a dedicated workspace list, dependency detection, and per-workspace model, environment, and permission tiers — codex workspaces pick :read-only / :workspace / :danger-full-access (passed as -c default_permissions=<tier>), claude workspaces pick default / acceptEdits / plan / bypassPermissions (the bypass tier launches with --dangerously-skip-permissions). Fully-open tiers dress the workspace card in a red danger skin (launch argument spelled out in red), so the blast radius is always visible before launch. Any workspace can also opt into worktree isolation — see DeepSeek Harness.

Custom agents: Any CLI tool can be registered — name, command, icon, working directory, env vars. Sessions are transient: close the tab, it's gone.

---

🐋 DeepSeek Harness

A first-class home for DeepSeek Harness workspaces. Manage every workspace in one dedicated panel, then launch each one as a terminal TUI or an embedded Web UI — inside LyShell, not a separate browser window. The two can even run side by side in split panes.

🗂️ Workspace panel — create, edit, delete	🔧 Variable groups — structured Base URL + API Key, one global switch
🎛️ Model presets — save & switch models per workspace	🖥️ TUI launch — dsh-tui in a native terminal tab
🌳 Worktree isolation — dedicated git worktree per workspace	🏷️ Brand badge — session tabs show which harness launched them

Permission tiers — danger you can see

Claude workspaces pick a launch permission mode — default / acceptEdits / plan / bypassPermissions (the bypass tier launches with --dangerously-skip-permissions); codex workspaces pick a -c default_permissions tier — :read-only / :workspace / :danger-full-access. Selecting a fully-open tier turns the form field red with a warning line — and the workspace card itself wears the danger skin (red tint + striped rail, launch argument spelled out in red), so a workspace that runs without approvals is identifiable at a glance in the list, before you ever click it.

Dependency detection & install

CLI dependencies — dsh + dsh-tui for DeepSeek Harness, codex / claude for the others — are detected by scanning PATH once at app startup (all three agents in parallel) and cached: opening a Harness tab reads the cached result instantly, no repeated scans. When something is missing, the panel shows which dependency is absent, its one-line install command, and the source-repo link — it never installs anything for you. A Re-detect button forces a fresh scan, and PATH is read live from the registry, so a freshly installed CLI is picked up without restarting LyShell.

Environment groups — one global bus

Variable groups live in the left-rail Environment panel, shared by dsh / codex / claude and the embedded dsh Web UI. At most one group is live at a time — the card itself is the switch: click it to power it on app-wide, click again to fall back to the system environment.

Credentials are structured as Base URL + API Key and injected per consumer (dsh → DEEPSEEK_*, codex → OPENAI_*, claude → ANTHROPIC_*); the rest of the group passes through as extra variables, and generic agents can bind a group explicitly (bound group → inline env → system environment). Each workspace picks a specific group or follows the enabled one — enter secrets once, switch environments without touching each workspace.

Secret-looking values (*_KEY, *_TOKEN, *_SECRET, *_PASSWORD, …) are masked as dots with an eye toggle to reveal. For codex workspaces, the group's OPENAI_BASE_URL is additionally written into $CODEX_HOME/config.toml ([model_providers.*].base_url) right before launch — the Rust codex CLI ignores the env var. That edit is line-surgical (comments, formatting and other providers preserved verbatim), idempotent, atomic, and the original file is backed up once as .bak.

Worktree isolation

Point multiple agents at the same repository without them stomping each other. Flip a workspace to worktree isolation and it launches inside a dedicated git worktree at <repo>/.lyshell-worktrees/<key> on branch lyshell/<key> — created on first launch, reused ever after, so uncommitted changes survive restarts. Deleting the workspace never deletes its worktree.

• Private (default) — a readable key is auto-generated (claude-myapp-20260708-160745, the trailing stamp is the creation time, second-precise); each workspace gets its own checkout.
• Shared — set the key explicitly, and every workspace that fills in the same key shares one checkout and one branch, even across dsh / codex / claude — they see each other's edits live.
• The form previews the exact worktree path before you save; invalid keys (path separators, ref-hostile characters) are rejected up front.

Launch: TUI or Web UI

Every workspace opens two ways:

• Terminal TUI — dsh-tui runs as a standard terminal tab with full scrollback, split panes, and IME support.
• Embedded Web UI — spawned as dsh web --port 0; LyShell parses the real port from stdout and renders the app in an in-app <webview> tab. No browser, no manual port juggling.

TUI + Web UI, side by side

Drag the Web UI tab to a pane edge to split it into its own pane — the TUI and the embedded Web UI run in the same frame, side by side. Drag it back onto a pane's center to remount it as a regular tab.

Web UI acts like a terminal tab

• ✕ close — only ✕ tears the tab down and terminates the subprocess.
• Switch away — switching to another tab hides the Web UI but keeps the page state and the dsh web subprocess alive; switching back resumes instantly.

Security

• 🔒 Loopback-locked — navigation and popups are pinned to the workspace's loopback origin.
• ✅ Validated URL — the echoed URL is checked (loopback + explicit port, no embedded credentials) before the <webview> ever loads it.

---

🌐 Web Tabs

The left-rail Web panel gives LyShell a light built-in browser for dashboards and docs. Type a URL (no scheme → https:// is prepended), press Enter, and it opens as a regular tab in the active split pane — same drag-to-split and tab semantics as the embedded dsh web UI, so a dashboard can sit right next to the terminal that feeds it.

• Open-tabs list — click to jump to the hosting pane and activate the tab, ✕ to close.
• Recent history — successfully loaded URLs are remembered (30 most recent, deduplicated, persisted locally) and offered as native autocomplete in the input; click to reopen, ✕ to delete a single entry, or clear all.
• Safety — only http/https URLs pass validation; webview navigation and popups route through a dedicated partition in the main process.

---

🧩 Plugin System & Python Scripting

Plugins

Permission-gated host for Python (one-shot / persistent) and Node.js (persistent) plugins. Install from local directory, ZIP, or remote URL. Each plugin runs with its own scoped authorization — granular permissions (read / write / execute / file / session control) with path safety, destructive-command confirmation, and shared-PTY locking.

⚠️ Plugins activate on startup (onStartup) today. Event-based activation and declarative UI contributions are not wired up yet.

📦 Ready-to-run examples in examples/.

Python Engine

Embedded Python with LyShell API for terminal automation:

session = LyShell.get_current_session()
LyShell.execute("ls -la")
LyShell.send("hello\n")
LyShell.wait_for("prompt$")

Environment variables: LYSHELL_SESSION_ID · LYSHELL_SESSION_TYPE · LYSHELL_HOST · LYSHELL_PORT.

Python path auto-detected from system PATH, configurable in settings.

💡 For long-running or scheduled tasks, consider Node.js plugins via the Plugin System — they're a better fit.

---

🚀 Quick Start

First Connection

1. Click + at the top of the session list → SSH
2. Fill in host, port, username, password/private key
3. Click Connect — tab turns 🟢 green

💡 For network devices needing shell → enable, add those in Shell Enter Commands — LyShell sends them sequentially.

Quick Connect

Ctrl+Alt+F from any app → search → Enter to connect.

Multi-Server Monitoring

Click a session → Ctrl+Shift+V to split vertically → click another session. Layout auto-saves.

File Transfer

• Upload — drag from desktop to File Panel
• Download — double-click remote file or right-click → Download
• Progress — real-time speed + ETA, auto MD5 on completion
• History — file, size, path, MD5 recorded; supports re-download
• Security — independent SSH connection (never blocks terminal), SFTP or TCP-over-SSH tunnel; no plaintext fallback even when AllowTcpForwarding is disabled
• Download directory — default ~/Downloads/LyShell/, optional auto-create server subdirectory for archiving

Quick Commands

Quick commands live at the bottom of the session panel — right-click → Edit Group → add commands like tail -f /var/log/syslog. Ctrl+F1–F12 fires them from anywhere, even with the sidebar collapsed. Up to 12 commands × 5 groups.

Session Management

• 📌 Pin — hover card → click 📌
• 📋 Clone session — double-click tab left half
• ⚡ Clone channel (no re-auth) — double-click tab right half (SSH only)
• 🔍 Search — type name/host/tag in search box

Terminal Tips

• Select text → auto-copy · Right-click → paste · Middle-click → search bar
• Ctrl+F → in-terminal search (regex, case-sensitive, cross-tab)
• Ctrl+click in the terminal — URLs open in a web tab, paths open in document preview
• Encoding — click the encoding readout in the sidebar LIVE row to switch UTF-8 / GBK / GB2312 at runtime (kept across reconnects; close-and-reopen falls back to the saved value; local terminals stay UTF-8)
• Edge-style shrinking tab bar with hover detail cards sits on the first row; the sidebar collapses when you need full width
• In the sidebar LIVE row, click cols × rows → clear screen; click the buffer count → scroll to bottom, double-click → clear scrollback

---

🔌 Connection Types & Terminal

Type	Key params	Notes
🖥️ SSH	password or private key; port 22	Post-login commands, keepalive; dual-click clone
📟 Telnet	host + port 23	Full IAC negotiation
🔌 Serial	COM port, baud 115200 (9600–921600), 8N1	Auto-detects ports
💻 Local PTY	cmd.exe / PowerShell	Configurable working directory + env

Terminal: GPU-accelerated rendering, full ANSI + 256 colors. Scrollback up to 100,000 lines. Split panes (horizontal/vertical), drag-to-split. Edge-style shrinking tab bar (hover detail cards) on the first row, collapsible sidebar. Runtime encoding switching from the sidebar (UTF-8 / GBK / GB2312). Global quick commands Ctrl+F1–F12. Tab status: 🟢 Connected · 🔴 Error · ⚪ Disconnected · 🔵 New output — plus a harness brand mark (🐋 dsh · 🛠️ codex · 🧠 claude) on tabs launched from a Harness workspace.

---

🎨 Themes

6 presets + custom. Instant switch, no restart.

Theme	Style	Mode
Graphite	Deep graphite + tungsten amber (default)	Dark
Slate	Blue-tinted slate, amber accent	Dark
Carbon	Neutral charcoal, no blue cast	Dark
Ember	Warm walnut brown + warm amber	Dark
Paper	Natural warm paper, graphite ink	Light
Lark	Feishu-style light: cool-gray chrome + white canvas + brand blue	Light

Custom: pick a background and accent color, LyShell auto-builds a complete harmonious theme.

---

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl + Shift + P	Command palette
Ctrl + Alt + F	Toggle float window
Ctrl + F	Terminal search
Ctrl + Shift + O	Open document (system file dialog)
Ctrl + F1 ~ F12	Quick command 1–12
Ctrl + Shift + H	Horizontal split
Ctrl + Shift + V	Vertical split
Right-click	Paste
Middle-click	Search bar

---

⚙️ Configuration

JSON files in %APPDATA%\lyshell\:

sessions.json · preferences.json · quickCommands.json · agents.json · env-profiles.json · dsh-workspaces.json · codex-workspaces.json · claude-workspaces.json · download-history.json · download-config.json · mcp-server.json · mcp-audit.json

AES-256-CBC encrypted export/import for sessions and quick commands.

---

❓ FAQ

SSH garbled Chinese characters?

Click the encoding readout in the sidebar LIVE row and switch UTF-8 / GBK / GB2312 at runtime — no need to edit the session.

Serial port no output?

Verify port + baud rate → check no other program uses it → some devices need Enter to activate.

File manager not showing?

SSH sessions only. Ensure the active tab is an SSH connection.

How to reset all configuration?

Delete all JSON files in `%APPDATA%\lyshell\` and restart.

Ctrl+Alt+F not working?

May be taken by another app. Reconfigure in LyShell settings.

Where are downloaded files?

Default `~/Downloads/LyShell/`. Change in settings.

---

📄 License

LyShell is open-source software released under the MIT License. You are free to use, modify, and redistribute it, provided the original copyright and license notices are preserved.

© 2026 liangyou

---

GitHub · Issues · Releases · Changelog · Contributing