{"id":50229269,"url":"https://github.com/milesxu/witty","last_synced_at":"2026-06-12T09:01:08.879Z","repository":{"id":346274841,"uuid":"1188095105","full_name":"milesxu/witty","owner":"milesxu","description":"AI-powered terminal emulator with Python, Qt6, and Rust","archived":false,"fork":false,"pushed_at":"2026-06-08T08:09:46.000Z","size":1046,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-08T10:09:16.176Z","etag":null,"topics":["ai","cross-platform","libghostty","python","qml","qt6","rust","terminal-emulator"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/milesxu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":null,"dco":null,"cla":null}},"created_at":"2026-03-21T16:01:03.000Z","updated_at":"2026-06-08T08:09:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/milesxu/witty","commit_stats":null,"previous_names":["milesxu/witty"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/milesxu/witty","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milesxu%2Fwitty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milesxu%2Fwitty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milesxu%2Fwitty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milesxu%2Fwitty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/milesxu","download_url":"https://codeload.github.com/milesxu/witty/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milesxu%2Fwitty/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34236552,"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-06-12T02:00:06.859Z","response_time":109,"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":["ai","cross-platform","libghostty","python","qml","qt6","rust","terminal-emulator"],"created_at":"2026-05-26T18:00:25.034Z","updated_at":"2026-06-12T09:01:08.859Z","avatar_url":"https://github.com/milesxu.png","language":"Rust","funding_links":[],"categories":["AI Tools \u0026 Agent Orchestration"],"sub_categories":[],"readme":"# Witty\n\nWitty is the Rust/wgpu mainline for a native-first terminal emulator. The\ncurrent daily path is a local Linux desktop window backed by `wgpu` and a local\nPTY; browser and gateway work remains in the tree as an active but secondary\npath.\n\nThe workspace is split into focused crates:\n\n- `witty-app`: product binary, CLI, native window, launcher composition\n- `witty-core`: terminal parser, state, snapshots, search, host actions\n- `witty-transport`: local PTY, OpenSSH profile conversion, profile store types\n- `witty-render-wgpu`: frame planning and `wgpu` renderer support\n- `witty-ui`: shared terminal UI state, command palette, search, plugins\n- `witty-plugin-api`: plugin manifests, permissions, and WIT ABI\n- `witty-plugin-wasm`: native Wasmtime host for Wasm Component Model plugins\n- `witty-gateway`, `witty-launcher`, `witty-web`: loopback browser path\n\n## Daily Native Path\n\nUse the OpenGL helper for local development on this Linux/M1000 machine:\n\n```text\nscripts/run-witty-native-opengl.sh\nscripts/run-witty-native-opengl.sh --print-command\ncargo run -p witty-app -- --window\n```\n\n`scripts/run-witty-native-opengl.sh` prefers `WITTY_NATIVE_BIN`, then\n`target/debug/witty`, then `cargo run -p witty-app --`. It forces\n`WGPU_BACKEND=gl` at the launcher boundary. Normal arguments are run as\n`witty --window ...`; helper modes such as `--font-list`,\n`--wittyrc-template`, `--wittyrc-check`, `--wittyrc-effective`,\n`--window-config-template`, `--window-config-check`,\n`--window-config-effective`, `--renderer-backend-info`, and\n`--renderer-no-surface-diagnostics` are forwarded without opening a window.\n\nLocal policy is OpenGL-only. Do not run Vulkan renderer experiments or\nPlaywright/Chromium WebGPU smoke tests on this host. The marker\n`.witty-local-opengl-only` makes the browser smoke scripts fail closed unless\n`WITTY_ALLOW_LOCAL_CHROMIUM_SMOKE=1` is set deliberately. The desktop entry\ntemplate at `packaging/linux/dev.witty.Witty.OpenGL.desktop` uses:\n\n```text\nExec=env WGPU_BACKEND=gl witty --window\n```\n\nNon-graphical policy checks:\n\n```text\ncargo run -p witty-app -- --renderer-backend-info\ncargo run -p witty-app -- --renderer-no-surface-diagnostics\nscripts/run-witty-native-opengl.sh --print-command --renderer-backend-info\n```\n\nFor an approved bounded native window probe, keep it OpenGL-only:\n\n```text\nscripts/run-witty-native-opengl.sh --window-startup-report --window-exit-after-ms 1500\n```\n\nThat probe reports the selected backend policy before renderer initialization\nand emits first-frame font/frame metadata if the redraw succeeds.\n\n## User-Local Linux Install\n\nInstall Witty for daily GNOME use under the user-local prefix `~/.local`:\n\n```text\nscripts/install-witty-local.sh --dry-run\nscripts/install-witty-local.sh\n```\n\nThe installer builds `witty-app` by default, installs the binary to\n`~/.local/bin/witty`, installs hicolor icons as `dev.witty.Witty`, and writes\n`~/.local/share/applications/dev.witty.Witty.desktop`. The installed launcher\nuses `Exec=/usr/bin/env WGPU_BACKEND=gl ~/.local/bin/witty --window`,\n`Icon=dev.witty.Witty`, `Terminal=false`, and\n`StartupWMClass=dev.witty.Witty`. It also writes an install marker at\n`$XDG_STATE_HOME/witty/install-state.v1.json`, or\n`~/.local/state/witty/install-state.v1.json` when `XDG_STATE_HOME` is unset.\nAlready running installed windows poll that marker and show an update notice\nwith a `Restart to update` button when a newer local install is detected.\n\nThe restart button writes a restart snapshot under the same Witty state\ndirectory and starts the newly installed binary as\n`witty --window --restore-state \u003csnapshot\u003e`. The snapshot stores window grid\nsize, tab metadata, launch program/args/cwd, safe environment metadata, and\nprofile-launched session metadata. It deliberately does not store terminal\ntext or claim ordinary local PTY child process continuity; shells and programs\nare relaunched from the saved metadata. Use a terminal multiplexer or a future\npersistent Witty daemon for lossless process continuity.\n\nTo validate without touching the real home directory:\n\n```text\nfake_home=\"$(mktemp -d)\"\nHOME=\"$fake_home\" scripts/install-witty-local.sh --dry-run\nHOME=\"$fake_home\" scripts/install-witty-local.sh --no-build\ndesktop-file-validate \"$fake_home/.local/share/applications/dev.witty.Witty.desktop\"\n```\n\nAfter a real install, launch Witty once from the desktop entry, then pin the\nrunning Witty window to the GNOME Shell dock. The desktop file id and native\nLinux app id/window class both use `dev.witty.Witty` so GNOME can group the\npinned launcher with Witty windows.\n\n## Local Shell And PTY\n\nNative `--window` starts a local shell through the PTY transport. Use\n`--program`, repeatable `--arg`, `--cwd`, and repeatable `--env KEY=VALUE` to\nshape a single launch:\n\n```text\ncargo run -p witty-app -- --window --program /bin/zsh --arg -l\ncargo run -p witty-app -- --window --cwd ~/src --program tmux --arg new-session\nscripts/run-witty-native-opengl.sh --cwd ~/src/witty --env WITTY_SESSION=dev\n```\n\n`Ctrl+Shift+T` opens a new local tab using the same launch defaults. Terminal\nOSC title updates replace the fallback title while the child process runs.\nRestart restore reuses these launch defaults and tab/profile metadata, but it\ndoes not preserve the live PTY process tree for ordinary local shells.\n\nThe browser launcher can also create a token-protected local gateway:\n\n```text\nscripts/build-witty-web-dist.sh\ncargo run -p witty-app -- --web\ncargo run -p witty-app -- --web --open-browser\n```\n\nOn this host those browser paths are buildable/documented, but browser smoke is\ndeferred to machines where Chromium/WebGPU is safe.\n\n## Fonts And Configuration\n\nWitty's preferred developer config is `$HOME/.wittyrc`. It uses TOML and ships\nwith a bundled template:\n\n```toml\nfont-family = \"Maple Mono NF CN\"\nwindow-last-active-close = \"close-window\"\n```\n\nCreate or inspect it without opening a window:\n\n```text\nscripts/run-witty-native-opengl.sh --wittyrc-template\nscripts/run-witty-native-opengl.sh --wittyrc-default-path\nscripts/run-witty-native-opengl.sh --wittyrc-init\nscripts/run-witty-native-opengl.sh --wittyrc-check\nscripts/run-witty-native-opengl.sh --wittyrc-effective\n```\n\nUse `--wittyrc \u003cpath\u003e` for an explicit TOML file and `--no-wittyrc` to bypass\nit. CLI flags and font environment variables take precedence over `.wittyrc`.\nThe legacy native-window JSON config still loads after `.wittyrc` and remains\nuseful for window size, title, launch command, cwd, env, scrollback, and other\nsettings.\n\nBy default, exiting the last local shell, for example with Ctrl-D, closes the\nWitty window/program. Set `window-last-active-close = \"block\"` in `.wittyrc`\nor `window_last_active_close = \"block\"` in `window.v1.json` to keep Witty open\nafter the last shell exits. In that non-closing mode, Witty replaces the\nexited terminal buffer with a compact empty-session screen that can start a\nnew local shell or open the command palette for profile/plugin launch actions.\n\nYou can still set fonts through CLI flags, environment defaults, or\n`window.v1.json`:\n\n```text\nscripts/run-witty-native-opengl.sh --font-list nerd\ncargo run -p witty-app -- --window \\\n  --font-family \"Maple Mono NF CN\" \\\n  --font-size 16 \\\n  --font-path /path/to/SymbolsNerdFontMono-Regular.ttf\nWITTY_FONT_FAMILY=\"Maple Mono NF CN\" witty --window\n```\n\n`--font-list` is non-graphical; add a filter before copying the exact family\nname into `--font-family`, `WITTY_FONT_FAMILY`, or config. `--font-path` is\nrepeatable and accepts `.ttf`, `.otf`, and `.ttc` files. `WITTY_FONT_PATHS`\nuses the platform path-list separator, `:` on Linux.\n\nThe compatible JSON config file is `window.v1.json` under the Witty config\ndirectory, normally `$XDG_CONFIG_HOME/witty/` or `~/.config/witty/` on Linux.\nUseful helpers:\n\n```text\nwitty --window-config-default-path\nwitty --window-config-template\nwitty --window-config-init\nwitty --window-config-check\nwitty --window-config-effective\n```\n\nUse `--window-config \u003cpath\u003e` or `WITTY_WINDOW_CONFIG` for an explicit file, and\n`--no-window-config` to bypass JSON config loading. Precedence is:\nCLI `--font-family` \u003e `WITTY_FONT_FAMILY` \u003e `.wittyrc` \u003e `window.v1.json` \u003e\nbuilt-in defaults.\n\n## Plugins\n\nWitty's plugin line is based on a manifest plus a Wasm Component Model ABI.\n`witty-plugin-api` owns manifests, permissions, and WIT definitions.\n`witty-plugin-wasm` is the native Wasmtime runtime. The host exposes narrow\nimports such as host info and redacted profile summaries; sensitive terminal\noutput, clipboard payloads, local paths, SSH argv, and raw profile-store data\nare not plugin-visible by default.\n\nNative app and smoke paths accept plugin inputs such as `--wasm-plugin` and\n`--plugin-dir`. Plugin actions that need host authority, including profile\npicker or profile launch requests, are queued for trusted Witty UI to review\nand resolve.\n\n## SSH And Profiles\n\nSSH support is modeled as profiles that Witty converts into OpenSSH-backed\n`LocalPtyConfig` values. The native launcher and profile store own local file\nI/O, profile selection, OpenSSH config import, and redacted summaries. Browser\nprofile picker flows receive only token-scoped, redacted data and never receive\nthe profile-store path, host secrets, raw OpenSSH argv, or private key data.\n\nImportant docs:\n\n- `docs/ssh-profile-transport-plan.md`\n- `docs/profile-store-file-plan.md`\n- `docs/launcher-profile-picker-plan.md`\n- `docs/profile-store-openssh-import-preview-plan.md`\n- `docs/profile-store-openssh-import-confirmed-write-plan.md`\n- `docs/plugin-runtime-selection.md`\n\n## Browser And Backend Work\n\n`witty-web`, `witty-gateway`, and `witty-launcher` remain active development\nareas for a loopback browser UI, WebSocket gateway, packaged web assets, and\nprofile picker flows. This work is deliberately deferred from the local\nacceptance path on the Linux/M1000 host because browser/WebGPU smoke can touch\nChromium and GPU driver paths. Keep local checks text-only or native OpenGL-only\nunless a later task explicitly authorizes browser or GUI smoke.\n\nWeb assets resolve in this order: `--web-root`, `WITTY_WEB_ROOT`, installed\n`share/witty/web` next to the executable, then `target/witty-web-dist`.\n\n## Useful Checks\n\n```text\ncargo fmt --all --check\ncargo check --workspace\ncargo test -p witty-core\ncargo test -p witty-transport\ncargo test -p witty-render-wgpu\ncargo test -p witty-ui\ncargo test -p witty-plugin-api\ncargo test -p witty-plugin-wasm\ncargo test -p witty-app app_options\n```\n\nDo not stage or commit migration changes until the supervisor flow reaches the\nverification and review tasks.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmilesxu%2Fwitty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmilesxu%2Fwitty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmilesxu%2Fwitty/lists"}