A GPU-accelerated terminal for Windows that keeps your sessions alive — close the window, your claude conversation survives. 一款 GPU 加速的 Windows 终端：关闭窗口不杀会话，重新打开，你的 claude 对话原样回来。
---
## English
### ✨ About
Nebula is a terminal emulator for Windows, built in Rust on a
GPU-accelerated rendering core and designed around one idea: **your terminal
sessions are too valuable to die with a window**. It pairs a tmux-style
resident session model with a glass UI, an AI-CLI-aware sidebar, and a shell
experience that works without extra setup.
### 🚀 Features
**Sessions that survive**
- **Session residency** — closing the window *detaches* instead of killing:
every PTY (your running `claude`, builds, SSH sessions) keeps running in a
resident process. Launch Nebula again and the window re-attaches — same
processes, same scrollback, mid-conversation.
- **Cold session restore** — if the resident process is gone (reboot, crash),
the next launch still restores your tab layout and per-tab working
directories from a continuously autosaved snapshot, with a crash-loop
breaker.
- **Single instance** — a second launch hands over to the running instance
instead of piling up windows.
**Built for AI-CLI workflows**
- **Real brand marks in the sidebar** — a tab running `claude` shows the
actual Anthropic starburst; `codex` shows the OpenAI blossom, tinted to the
theme. Other programs get Nerd Font icons (`gemini`, `copilot`, `git`,
`vim`, `cargo`, …).
- **Live turn state, wired to the source** — Nebula installs Claude Code
hooks (and Codex notify) pointing at a bundled bridge
(`nebula-hook.exe`, dependency-free): prompt submitted → spinner; turn
finished → dot + toast; Claude needs your input → toast carrying the actual
message text. Delivered over a local named pipe, with no shell integration
required.
- **Click-to-focus notifications** — every toast knows which pane raised it:
click one and Nebula comes to the foreground, switches to that tab and
focuses that split.
- **Zero setup, self-healing** — the hook entries install on first boot and
re-install themselves if a config switcher rewrites the file (a watcher on
the config directory re-applies them). Scoped by environment: claude
running in any other terminal is untouched. `nebula setup-ai --remove`
undoes everything.
- **Plays nice with existing notifiers** — codex has a single notify slot;
Nebula wraps it (`--chain`) instead of stealing it, so a pre-existing
notifier keeps firing.
- **Fallback signals** — OSC 133 command tracking + BEL still cover every
other CLI: long builds toast on completion, with their duration.
- **Native SSH sessions** — saved hosts open directly through Nebula's Rust SSH
transport: no wrapper shell and no external console window. Host aliases,
usernames, ports and identity files are resolved from `~/.ssh/config`;
authentication supports standard private keys and certificates, encrypted-key
passphrases, Windows Credential Manager passwords, and keyboard-interactive/MFA.
Accepted host keys use the standard `known_hosts` store, and additional tabs
reuse an already authenticated
connection to the same `user@host:port` for a faster second shell.
- **Built-in SFTP transfers** — open a remote file drawer from any saved SSH
host and reuse its authenticated connection. Browse or type remote paths,
filter entries, upload and download files or folders, create and rename
folders, recursively delete, follow symlink targets, and cancel transfers
with visible progress and errors.
- **AI-aware over SSH** — remote Hook envelopes can return through a
per-channel, randomly authenticated private OSC bridge. Nebula validates the
channel token, replaces any remote pane identifier with the local pane, and
routes the event through the existing sidebar and Windows notification path.
The `nebula ssh` compatibility command remains available for forwarding,
query and explicit-command forms that need the system SSH client.
**Performance & correctness**
- **Instrumented startup** — the boot path is fully traceable
(`NEBULA_BOOT_TRACE=1`); no shell profile is loaded and history loads
lazily.
- **Modern ConPTY host** — ships the side-by-side ConPTY host for correct
resize behavior, with its startup handshake (DA1) pre-primed so a new tab
doesn't stall on that round-trip.
- **Coalesced resizing** — interactive drags resize the grid only; the PTY
learns its final size once, so full-screen TUIs don't smear redraws into
scrollback.
**Shell experience**
- **Inline ghost-text completions** — fish-style dim suggestions from command
history and filesystem paths; accept with `→` or `Tab`.
- **Persistent indexed history** — commands stored as JSONL under
`%APPDATA%\Nebula`, shared across sessions, with prefix hints.
- **Powerline prompt built in** — themed gradient prompt with git branch and
clock, for PowerShell and Git Bash, no plugins to install.
- **Quality-of-life fixes** — unquoted `cd D:/Program Files` just works, bare
`$env:KEY=value` assignments are auto-quoted, `ls` gets colors and
clickable OSC 8 hyperlinks.
**Markdown that renders like GitHub**
- **Markdown/GFM document tabs** — open Markdown, JSON, and plain-text files
directly from the file drawer with headings, lists, tables, code blocks,
links, quotes, word wrapping, and virtualized scrolling.
- **Images from anywhere** — remote `http(s)` URLs, `data:` URIs, absolute
paths, and paths relative to the document all resolve, so badge rows, logos,
and embedded screenshots land exactly where the file puts them. The
screenshot above is Nebula rendering its own README.
- **The HTML that real READMEs use** — `
` centres its
content, several `` badges in one paragraph stay on a single row instead
of breaking into separate blocks, ` ` breaks in document order, and
`` link badges survive as clickable images.
- **CJK-correct soft wraps** — CommonMark soft line breaks join as spaces, but
adjacent CJK characters join directly, so Chinese paragraphs don't pick up
the stray gaps other viewers insert.
**Documents & native mathematics**
- **Native TeX mathematics** — inline `$...$` and display `$$...$$` formulas
are parsed and laid out entirely in Rust, then drawn through cached Latin
Modern Math glyphs and GPU rule quads. Fractions, radicals, scripts, limits,
integrals, matrices, scalable delimiters, Greek letters, and common symbols
render without a WebView, JavaScript runtime, or external TeX process.
- **Bounded document rendering** — oversized formulas fit the reading column,
long prose and failed formulas wrap, and parser, layout, cache, atlas, and
per-frame work all have explicit limits. See the
[math rendering fixture](docs/math-rendering-test.md) for the screenshot and
regression set.
**Interface**
- **Glass chrome & seven themes** — Nebula plus three matched light/dark
pairs: Silver Light / Steel Dark, Limestone / Coal Dark, Linen Light /
Moss Dark. One skin system drives chrome, prompt and dialogs; every theme
persists across restarts.
- **Tabs & splits** — sidebar tabs with drag-to-reorder and drag-to-dock into
splits; unfocused panes dim instead of growing borders.
- **Files, Git and SFTP drawers** — browse local or remote files without
leaving the terminal. The Git drawer can stage, commit, pull fast-forward
updates, and push.
- **Quick terminal** — global Ctrl+` drops a Quake-style
terminal from the top edge.
- **Settings tab & command palette** — settings opens as a normal reusable tab,
with themes, language, background image/opacity, shell choice and completion
behavior; all persisted.
- **Inline images** — OSC 1337 image protocol support, lazily anchored to
scrollback rows.
### 📥 Install
> **⚠️ Install the bundled font first.** Nebula's powerline prompt, program
> icons and AI brand marks are drawn with **Maple Mono Normal NF CN** (a Nerd Font).
> Nebula embeds the same font as a runtime fallback so forgetting to install it
> no longer breaks the interface, but a normal system installation is still the
> intended setup. The font ships in the release zip under `fonts/` and the repo at
> `assets/fonts/MapleMonoNormal-NF-CN-Regular.ttf` — double-click
> it and press **Install**, then launch Nebula. Nebula checks the font on every
> launch; if the system font is missing, a dismissible reminder can open the
> bundled `fonts/` folder. Install the font and restart Nebula for the complete
> icon set. (Licensed under SIL OFL 1.1.)
**Release build (recommended)** — download
`NebulaTerminal-v0.6.0-windows-x64.zip` from
[Releases](https://github.com/Kuddev/nebula/releases), unzip
anywhere, install `fonts/MapleMonoNormal-NF-CN-Regular.ttf`, then run
`nebula.exe`. Keep the extracted folders in place: AI and ConPTY helpers live
under `runtime/`, while fonts, documentation, and notices live under `fonts/`,
`docs/`, and `licenses/`.
**From source**
```powershell
cargo build --release # artifacts land in target/release/
```
### Lua Configuration
Nebula ships a vendored Lua 5.4 runtime with `require 'nebula'` and
`nebula.config_builder()`. Generate an annotated template with
`nebula config init --language system|zh-CN|en-US`, then validate it without
opening the GUI using `nebula config check`. Module `require` paths participate
in live reload; invalid edits keep the last-known-good configuration active.
Existing TOML files remain supported. See the
[Lua configuration guide](docs/lua-configuration.md) for APIs, discovery order,
Windows/Linux paths, arrays, modules, and reload behavior.
### 🧩 Tech Stack
| Layer | Tech |
| --- | --- |
| Language | Rust (2024 edition) |
| Rendering | OpenGL / OpenGL ES 2.0+, custom glyph & UI quad renderers |
| Terminal core | GPU-resident grid + VTE escape-sequence parsing, on an Alacritty-derived foundation |
| Session model | Resident mux process, loopback attach protocol |
| Shell integration | PowerShell + PSReadLine, Git Bash; OSC 7/8/9/133/1337 |
| Document math | pulldown-cmark + pulldown-latex + OpenType MATH (Latin Modern Math) |
| Fonts | Maple Mono Normal NF CN (Nerd Font glyphs, CJK-aware) |
### 📦 Requirements
- At least OpenGL ES 2.0
- Windows 10 (1809+) / 11 with ConPTY support
### Contact
Questions and feedback: [fickleheartedkeys@163.com](mailto:fickleheartedkeys@163.com)
### 🙏 Acknowledgements
Nebula's terminal core — the grid, the VTE escape-sequence parsing, and the PTY
plumbing — is derived from
**[Alacritty](https://github.com/alacritty/alacritty)**, a masterpiece of
terminal engineering. Sincere thanks to its maintainers and contributors;
Nebula would not exist without their work.
Nebula's shell is built on **[GPUI](https://github.com/zed-industries/zed)** — the
GPU-accelerated UI framework developed by the [Zed](https://zed.dev) team — together with
**[gpui-component](https://github.com/longbridge/gpui-component)** from
[Longbridge](https://github.com/longbridge), which supplies the widget library. Both are
Apache-2.0 licensed and are used through lightly patched forks pinned in the workspace
manifest. Thank you for releasing this work as open source — Nebula's interface would not
look the way it does without it.
### 📜 License
Released under the [GNU General Public License v3.0](LICENSE).
Parts of Nebula are derived from upstream open-source projects; their original
license and copyright notices are preserved in
[THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES). The work as a whole is distributed
under GPL-3.0.
---
## 简体中文
### ✨ 简介
Nebula 是一款 Windows 上的终端模拟器，以 Rust 编写，构建在 GPU 加速渲染
内核之上，并围绕一个理念设计：**终端会话太宝贵，不该随窗口一起消失**。它
把 tmux 式的常驻会话模型、玻璃质感界面、AI CLI 感知侧边栏和无需额外配置
的 shell 体验组合在一起。
### 🚀 功能特性
**会话永生**
- **会话驻留** — 关闭窗口是*分离*而不是杀死：所有 PTY（正在跑的
`claude`、构建、SSH）继续在常驻进程里运行。再次启动 Nebula，窗口原样接回
—— 同样的进程、同样的回滚缓冲、对话进行到一半也不丢。
- **冷恢复** — 常驻进程不在了（重启、崩溃）也没关系：下次启动从持续自动保
存的快照恢复标签布局和每个标签的工作目录，并带崩溃循环保护。
- **单实例** — 重复启动会交棒给运行中的实例，不会堆一堆窗口。
**为 AI CLI 工作流而生**
