{"id":50422232,"url":"https://github.com/xuzhougeng/wispterm","last_synced_at":"2026-06-08T01:07:26.277Z","repository":{"id":354940931,"uuid":"1225551985","full_name":"xuzhougeng/wispterm","owner":"xuzhougeng","description":"A cross-platform terminal workspace for remote development and AI agents, powered by libghostty-vt.","archived":false,"fork":false,"pushed_at":"2026-05-29T06:38:47.000Z","size":8168,"stargazers_count":95,"open_issues_count":4,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T08:27:35.517Z","etag":null,"topics":["ghostty","macos","terminal","windows"],"latest_commit_sha":null,"homepage":"https://phantty.cc-remote.app/","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"arya-s/phantty","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xuzhougeng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-30T11:53:26.000Z","updated_at":"2026-05-29T07:19:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xuzhougeng/wispterm","commit_stats":null,"previous_names":["xuzhougeng/phantty","xuzhougeng/wispterm"],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/xuzhougeng/wispterm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuzhougeng%2Fwispterm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuzhougeng%2Fwispterm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuzhougeng%2Fwispterm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuzhougeng%2Fwispterm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xuzhougeng","download_url":"https://codeload.github.com/xuzhougeng/wispterm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xuzhougeng%2Fwispterm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33725060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"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":["ghostty","macos","terminal","windows"],"created_at":"2026-05-31T09:00:28.446Z","updated_at":"2026-06-08T01:07:26.270Z","avatar_url":"https://github.com/xuzhougeng.png","language":"Zig","funding_links":[],"categories":["Terminal Apps \u0026 Clients"],"sub_categories":[],"readme":"English | [简体中文](README.zh-CN.md)\n\n# WispTerm\n\n**WispTerm**, formerly Phantty, is a cross-platform terminal workspace for remote development and AI agent workflows. It is written in Zig and powered by [libghostty-vt](https://github.com/ghostty-org/ghostty) for terminal emulation.\n\n\u003e [!NOTE]\n\u003e WispTerm ships for **Windows** and **macOS** (Apple Silicon and Intel). The\n\u003e **Linux** port is still in progress (see [TODO.md](TODO.md)).\n\n## Features\n\n- **Ghostty's terminal emulation** - uses libghostty-vt for VT parsing and terminal state\n- **DirectWrite font discovery** - find system fonts by name, with per-glyph fallback for missing characters\n- **FreeType rendering** - high-quality glyph rasterization with Ghostty-style font metrics\n- **Sprite rendering** - box drawing, block elements, braille patterns, powerline symbols\n- **Theme support** - Ghostty-compatible theme files, 450+ themes built in (default: Poimandres)\n- **Background image and shaders** - wallpaper blending plus Ghostty-compatible GLSL post-processing\n- **Splits and tabs** - vertical/horizontal splits, tab strip, focus-follows-mouse, equalize sizes\n- **File Explorer and previews** - browse local, WSL, and SSH files; preview Markdown/text/tables/images without leaving the terminal\n- **Embedded browser panel** - open web URLs in a side WebView2 panel or the default browser, with persistent SSH loopback port forwarding for profile sessions\n- **AI Agent sessions** - launch OpenAI-compatible Agent tabs, configure profiles, restore history, export Markdown transcripts, and distill reusable local skills\n- **AI history browser** - browse local, WSL, and SSH Codex / Claude Code / Reasonix history and resume sessions from their original project directories\n- **Kitty Graphics protocol** - display inline images and PDFs from remote shells via `imgcat.py` / `pdfcat.py`\n- **Opt-in remote access** - share a session key over a Cloudflare-hosted relay (disabled by default)\n\n## Documentation\n\n- [Configuration](docs/configuration.md)\n- [File Explorer and previews](docs/file-explorer.md)\n- [AI Agent sessions](docs/ai-agent.md)\n- [Media, background images, and inline remote images](docs/media.md)\n- [Development, architecture, packaging, and releases](docs/development.md)\n- [FAQ](docs/faq.md)\n\n## Building\n\nWindows (PowerShell):\n\n```powershell\nzig build                         # Debug build for development\nzig build -Doptimize=ReleaseFast  # ReleaseFast build for distribution\nRemove-Item -Recurse -Force .\\zig-out, .\\.zig-cache -ErrorAction SilentlyContinue\n```\n\nmacOS (requires macOS 13+ and Zig 0.15.2):\n\n```bash\nzig build macos-app -Dtarget=aarch64-macos   # Apple Silicon .app bundle (use x86_64-macos on Intel)\nopen zig-out/bin/WispTerm.app                  # launch the built app\n```\n\nThe `Makefile` may still exist as a convenience wrapper, but normal Windows\ndevelopment should use PowerShell and direct `zig` commands.\n\nFor architecture, packaging, and release details, see [Development, architecture, packaging, and releases](docs/development.md).\n\n## Usage\n\nOn Windows run `wispterm.exe`; on macOS run `WispTerm.app/Contents/MacOS/wispterm` (or launch `WispTerm.app` directly — passing CLI flags requires the binary path).\n\n```bash\nwispterm [options]\n\nOptions:\n  --font, -f \u003cname\u003e            Set font (default: embedded fallback)\n  --font-style \u003cstyle\u003e         Font weight (default: regular)\n                                Options: thin, extra-light, light, regular,\n                                         medium, semi-bold, bold, extra-bold, black\n  --cursor-style \u003cstyle\u003e       Cursor shape (default: block)\n                                Options: block, bar, underline, block_hollow\n  --cursor-style-blink \u003cbool\u003e  Enable cursor blinking (default: true)\n  --theme \u003cpath\u003e               Load a Ghostty theme file\n  --background-image \u003cpath\u003e    Image file to render behind the terminal\n  --background-opacity \u003c0..1\u003e  Opacity of theme/cell backgrounds (default: 1.0)\n  --background-image-mode \u003cm\u003e  fill | fit | center | tile (default: fill)\n  --window-height \u003crows\u003e       Initial window height in cells (default: 0=auto, min: 4)\n  --window-width \u003ccols\u003e        Initial window width in cells (default: 0=auto, min: 10)\n  --quake-mode \u003cbool\u003e          Enable Quake-style drop-down mode (default: true)\n  --keybind \u003cbinding\u003e          Configure a shortcut, e.g. global:ctrl+backquote=toggle_quake\n  --config \u003cpath\u003e              Use this file as the main config\n  --config-path \u003cpath\u003e         Alias for --config\n  --config-file \u003cpath\u003e         Include another config file (prefix ? for optional)\n  --version, -v                Print the WispTerm version and exit\n  --show-config-path           Print the resolved main config path\n  --list-fonts                 List available system fonts\n  --list-themes                List available themes\n  --test-font-discovery        Test DirectWrite font discovery\n  --help, -h                   Show help\n```\n\nConfiguration file details are in [Configuration](docs/configuration.md).\n\n## Keyboard shortcuts\n\nDefault app-level chords are defined in [`src/keybind.zig`](src/keybind.zig) and can be remapped with repeated `keybind = ...` lines in the config file. Some modal/editor-local keys are still handled by the focused overlay first (command center navigation, session launcher editing, AI Chat input, and similar).\n\nExample remaps:\n\n```text\nkeybind = alt+f10=toggle_command_palette\nkeybind = global:ctrl+backquote=toggle_quake\n```\n\nUse `keybind = clear` before custom bindings if you want to remove all defaults and rebuild the table from scratch. To confirm the running desktop version, open the command center (`Ctrl+Shift+P` on Windows, `Cmd+Shift+P` on macOS), type `version`, and press Enter.\n\n\u003e **macOS modifier mapping:** most shortcuts use **Cmd** in place of Ctrl and **Opt** in place of Alt. Two exceptions keep Ctrl to avoid colliding with system shortcuts: **Ctrl+`** (Quake — `Cmd+`` is the system window cycler) and **Ctrl+Tab** / **Ctrl+Shift+Tab** (tab switching — `Cmd+Tab` is the system app switcher).\n\n| Action | Windows / Linux | macOS |\n| ------ | --------------- | ----- |\n| Show/hide Quake drop-down | **Ctrl+`** | **Ctrl+`** |\n| Open command center | **Ctrl+Shift+P** | **Cmd+Shift+P** |\n| New session (session launcher) | **Ctrl+Shift+T** | **Cmd+Shift+T** |\n| New window | **Ctrl+Shift+N** | **Cmd+Shift+N** |\n| Toggle tab sidebar | **Ctrl+Shift+B** | **Cmd+Shift+B** |\n| Split to the right | **Ctrl+Shift+O** | **Cmd+Shift+O** |\n| Toggle file explorer sidebar | **Ctrl+Shift+Alt+E** | **Cmd+Shift+Opt+E** |\n| Toggle AI Copilot sidebar (current terminal) | **Ctrl+Shift+A** | **Cmd+Shift+A** |\n| Preview files (Ctrl/Cmd-click in terminal, or double-click in File Explorer) | Ctrl-click | Cmd-click |\n| Download SSH remote file | Ctrl+Shift-click path in SSH output | Cmd+Shift-click path in SSH output |\n| Close focused panel, tab, or window | **Ctrl+Shift+W** | **Cmd+Shift+W** |\n| Maximize or restore window | **Alt+Enter** | **Opt+Enter** |\n| Increase / decrease font size | **Ctrl++** / **Ctrl+-** | **Cmd++** / **Cmd+-** |\n| Copy terminal selection or AI Chat selection/transcript | **Ctrl+Shift+C** | **Cmd+Shift+C** |\n| Select from the last terminal click anchor | Shift-click terminal text | Shift-click terminal text |\n| Select part of an AI answer | Drag AI answer text | Drag AI answer text |\n| Select and copy part of an AI answer | Shift-drag AI answer text | Shift-drag AI answer text |\n| Select AI Chat input; select transcript when input is empty | **Ctrl+A** in AI Chat | **Cmd+A** in AI Chat |\n| Copy AI Chat selection or full transcript | **Ctrl+C** in AI Chat | **Cmd+C** in AI Chat |\n| Delete the selected saved Agent session | **D** / **Delete** in Agent History | **D** / **Delete** in Agent History |\n| Edit AI History filter | Type / Backspace in AI History | Type / Backspace in AI History |\n| Move selected AI History session | Up / Down in AI History | Up / Down in AI History |\n| Resume selected AI History session | Enter in AI History | Enter in AI History |\n| Preview selected AI History transcript | Space in AI History | Space in AI History |\n| Refresh local AI History scan | **R** in local AI History | **R** in local AI History |\n| Edit AI Chat input cursor | Left/Right/Home/End/Delete/Backspace | Left/Right/Home/End/Delete/Backspace |\n| Stop in-flight AI Chat or Agent request | **Esc** in AI Chat while working | **Esc** in AI Chat while working |\n| Copy selection (right-click) | Right-click a selection | Right-click a selection |\n| Paste text | **Ctrl+V** | **Cmd+V** |\n| Paste clipboard image | **Ctrl+Shift+V** | **Cmd+Shift+V** |\n| Move focus to adjacent panel | **Alt** + arrow keys | **Opt** + arrow keys |\n| Focus panel 1–9 by number | **Ctrl+1**–**9** | **Cmd+1**–**9** |\n| Focus previous panel (cycle) | **Ctrl+Shift+[** | **Cmd+Shift+[** |\n| Focus next panel (cycle) | **Ctrl+Shift+]** | **Cmd+Shift+]** |\n| Equalize split sizes | **Ctrl+Shift+Z** | **Cmd+Shift+Z** |\n| Next tab | **Ctrl+Tab** | **Ctrl+Tab** |\n| Previous tab | **Ctrl+Shift+Tab** | **Ctrl+Shift+Tab** |\n| Switch to tab 1–9 | **Alt+1**–**9** | **Opt+1**–**9** |\n| Open config file | **Ctrl+,** | **Cmd+,** |\n\n## AI Chat Markdown export\n\nIn an active AI Chat or Agent tab, open the command center with `Ctrl+Shift+P`\nand run:\n\n- `Export AI Chat Markdown` to save the full transcript, including thinking,\n  tool details, and usage metadata.\n- `Export AI Chat Markdown Clean` to save a publishing-friendly Markdown file\n  with only the user inputs and the final AI answer.\n\nWispTerm opens a save dialog with a `.md` filename. After saving, the\nsaved path is copied to the clipboard.\n\n## SSH current directory for downloads and uploads\n\nWispTerm can download a relative file path from an SSH terminal output, and upload\ndragged files into the interactive SSH shell's current directory, only when the\nremote shell reports its current directory with OSC 7. This is the same terminal\nconvention used by Ghostty shell integration.\n\nIf OSC 7 is missing, helper `ssh.exe` / `scp.exe` commands start a fresh SSH\nsession and usually see the login directory, not the directory you `cd`'d to in\nthe interactive shell. In that case WispTerm shows `SSH cwd unknown; click for\nsetup` instead of guessing `~/file`.\n\nAdd one of these snippets to the remote shell startup file, then start a new\nWispTerm SSH session.\n\nFor Bash, add this to `~/.bashrc`:\n\n```bash\n__wispterm_report_cwd() {\n  printf '\\033]7;file://%s%s\\a' \"${HOSTNAME:-localhost}\" \"$PWD\"\n}\nPROMPT_COMMAND=\"__wispterm_report_cwd${PROMPT_COMMAND:+;$PROMPT_COMMAND}\"\n```\n\nFor Zsh, add this to `~/.zshrc`:\n\n```zsh\n__wispterm_report_cwd() {\n  printf '\\033]7;file://%s%s\\a' \"${HOST:-localhost}\" \"$PWD\"\n}\nautoload -Uz add-zsh-hook\nadd-zsh-hook chpwd __wispterm_report_cwd\nadd-zsh-hook precmd __wispterm_report_cwd\n```\n\nFor Fish, add this to `~/.config/fish/config.fish`:\n\n```fish\nfunction __wispterm_report_cwd --on-variable PWD\n    printf '\\e]7;file://%s%s\\a' (hostname) (string escape --style=url $PWD)\nend\n__wispterm_report_cwd\n```\n\n## Credits\n\n- Original project: [arya-s/phantty](https://github.com/arya-s/phantty) - the\nZig + libghostty-vt foundation and the Windows terminal core. WispTerm builds on\nthat base and layers additional features on top: an embedded WebView2 browser\npanel, a file explorer with Markdown/text/table/image preview, AI Agent sessions\nwith Markdown export, an opt-in remote-access client, Kitty Graphics image\nprotocol support, and a configurable background image.\n- Terminal emulation: [ghostty-org/ghostty](https://github.com/ghostty-org/ghostty)\nvia `libghostty-vt`.\n- Image decoding: [stb_image](https://github.com/nothings/stb) (vendored\nthrough the ghostty dependency).\n\n## License\n\nMIT\n\n## Star History\n\n\u003ca href=\"https://star-history.com/#xuzhougeng/wispterm\u0026Date\"\u003e\n  \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=xuzhougeng/wispterm\u0026type=Date\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxuzhougeng%2Fwispterm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxuzhougeng%2Fwispterm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxuzhougeng%2Fwispterm/lists"}