{"id":50596137,"url":"https://github.com/abilian/terminux","last_synced_at":"2026-06-05T14:03:40.299Z","repository":{"id":360913837,"uuid":"1243570910","full_name":"abilian/terminux","owner":"abilian","description":"A fast, reliable, cross-platform terminal — organized the way you actually work.","archived":false,"fork":false,"pushed_at":"2026-05-28T10:54:12.000Z","size":2293,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T12:24:12.626Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abilian.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-05-19T13:14:09.000Z","updated_at":"2026-05-28T10:54:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/abilian/terminux","commit_stats":null,"previous_names":["abilian/terminux"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/abilian/terminux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fterminux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fterminux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fterminux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fterminux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abilian","download_url":"https://codeload.github.com/abilian/terminux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abilian%2Fterminux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33944688,"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-05T02:00:06.157Z","response_time":120,"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":[],"created_at":"2026-06-05T14:03:39.282Z","updated_at":"2026-06-05T14:03:40.291Z","avatar_url":"https://github.com/abilian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# terminux\n\n### A fast, reliable, cross-platform terminal — organized the way you actually work.\n\n**Workspaces on the left. Tabbed terminals in the middle. Everything where you left it.**\n\n[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-lightgrey.svg)](#-install--package)\n[![Status](https://img.shields.io/badge/status-v1%20preview-orange.svg)](#-status--v1-preview)\n[![License](https://img.shields.io/badge/license-see%20repo-green.svg)](https://github.com/abilian/terminux)\n\n\u003cbr/\u003e\n\n\u003cimg src=\"docs/images/main-window.png\" alt=\"terminux — workspaces sidebar and a tabbed terminal running a test suite\" width=\"800\"/\u003e\n\n\u003c/div\u003e\n\n---\n\n## Why terminux?\n\nYou don't have one project. You have *six*. Each one is a different directory, a\ndifferent mental context, a different set of running shells. terminux gives each\nof them a home — a **workspace** — and keeps them alive and arranged exactly how\nyou left them, even across restarts.\n\nIt's the workspace UX of [cmux](https://github.com/) on a clean, auditable\ntwo-process architecture inspired by terax — rebuilt in **Python** for\n**reliability over features**. No accounts. No telemetry. No AI. Just a terminal\nthat respects your flow.\n\n```sh\nuv sync \u0026\u0026 make frontend\nuv run terminux\n```\n\nThat's it. You're in.\n\n## ✨ What you get\n\n- **Workspaces sidebar** — a persistent list of named workspaces. Names track\n  the first tab's working directory automatically (until you pin one).\n- **Tabbed terminals** — every workspace has its own tabs, each a real PTY\n  shell. Switch freely; background tabs keep streaming, no jank.\n- **Survives restarts** — workspaces, tabs, window geometry, font size, each\n  shell's working directory, and *the visible scrollback of every tab* all\n  come back. Fresh shells, same layout, same view you left.\n- **Keyboard-first** — sidebar shows a keycap on each of the first nine\n  workspaces; jump straight there with `Ctrl+Shift+1..9` on Linux\n  (`Cmd+1..9` on macOS). Plus a fuzzy quick-switcher, find-in-terminal,\n  font zoom, and more.\n- **Platform-respecting shortcuts** — Linux uses `Ctrl+Shift+\u003ckey\u003e` for app\n  shortcuts (matching GNOME Terminal, Konsole, Alacritty, Ghostty, kitty),\n  so raw `Ctrl+P` / `Ctrl+B` / `Ctrl+F` flow straight to your shell. macOS\n  uses `Cmd` for the same job; raw `Ctrl` is left alone.\n- **Clickable URLs \u0026 iTerm2-style copy** — modifier-click opens links;\n  optional auto-copy on selection, persisted, off by default.\n- **Working vs ready** — two-color sidebar dot: **amber** while a\n  foreground task is actively producing output (idle TUIs and parked\n  prompts don't count); **green** once that task has finished — driven\n  by `BEL` / `OSC 9` / `OSC 133;D` (opt-in [shell integration](docs/shell-integration.md))\n  or a kernel-level busy→idle transition. Plain output by itself\n  never falsely promotes to green. Reads at a glance like a CI traffic\n  light.\n- **Drag \u0026 drop** — reorder workspaces and tabs with live drop feedback\n  (works even in WKWebView, where HTML5 DnD doesn't). Drop a file to paste its\n  shell-quoted path.\n- **Local-first \u0026 hardened** — loopback-only by default, per-session auth\n  token, CSP and security headers, atomic versioned persistence.\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/images/quick-switcher.png\" alt=\"The fuzzy quick switcher (Ctrl+Shift+P / Cmd+P) jumping between workspaces and tabs\" width=\"800\"/\u003e\n\n\u003csub\u003eThe fuzzy quick switcher (\u003ccode\u003eCtrl+Shift+P\u003c/code\u003e on Linux, \u003ccode\u003eCmd+P\u003c/code\u003e on macOS) — jump to any workspace or tab.\u003c/sub\u003e\n\n\u003c/div\u003e\n\n## Run\n\n```sh\nuv sync\nmake frontend                # build the web UI (needs Node; first run only)\nuv run terminux              # desktop window (pywebview)\nuv run terminux --no-window  # server only — open the printed URL in a browser\n```\n\n`--no-window` is the dev/test path and a preview of the future **web mode**.\n\n## Install / package\n\nterminux ships as a self-contained desktop app — no Python or Node required to\nrun the bundle.\n\n```sh\nmake linux        # Linux bundle (built in Docker) → dist/linux/terminux/terminux\nmake docker-run   # run headless web mode on :8000\nmake app          # macOS .app → dist/terminux.app\n```\n\nFull platform notes (signing, Gatekeeper, X11, architectures) live in the\n[**documentation**](#-documentation).\n\n## Documentation\n\nDocs are built with [Zensical](https://zensical.org/) and live in `docs/`.\n\n```sh\nuv run zensical serve    # live preview at http://127.0.0.1:8000\nuv run zensical build    # static site → site/\n```\n\nStart with [`docs/index.md`](docs/index.md). The original vision, functional\nspec, and technical spec are in [`notes/`](notes/).\n\n## Develop\n\n```sh\nmake frontend        # build TS/Vite UI → src/terminux/web/static\nmake frontend-test   # vitest unit tests (pure TS logic)\nmake test            # pytest: unit, integration, e2e (Playwright)\nmake lint            # ruff + ty + pyrefly + mypy\nmake format\n```\n\nThe e2e tier drives the served UI with a real browser (no pywebview); install\nit once with `uv run playwright install chromium`.\n\n## Status — 0.5 preview\n\n**Works today:** workspaces sidebar (create / rename / reorder / close, auto\nstatus dot), tabs with multiple live terminals, real PTY shells over a\nper-terminal WebSocket, background streaming, structure persisted to disk\n(fresh shells on restart), per-session loopback token, macOS \u0026 Linux bundles.\n\n**Not yet:** split panes, client/server detach, Windows PTY.\n\n## Architecture in one breath\n\nA Vite/TypeScript xterm.js web UI runs in a sandboxed pywebview window and talks\nto a loopback Starlette/uvicorn backend that owns the PTYs and streams raw bytes\nover per-terminal WebSockets. The frontend build output is committed to\n`src/terminux/web/static/`, so the Python package runs with no Node toolchain.\n\n\u003cdiv align=\"center\"\u003e\n\u003csub\u003eBuilt for people who keep too many terminals open. — \u003ca href=\"https://github.com/abilian/terminux\"\u003eabilian/terminux\u003c/a\u003e\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabilian%2Fterminux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabilian%2Fterminux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabilian%2Fterminux/lists"}