Skip to content
kta41Public

About

A robust terminal cockpit uniting WezTerm, Starship, and custom WSL scripts. Features non-blocking Kubernetes/ArgoCD integration, fuzzy action palettes, and zero-lag status monitoring.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

22 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

TermDeck 🚀

A high-performance terminal cockpit uniting WezTerm, Starship, and custom WSL automation.

Lua Shell License: OFL 1.1 Platform: Windows / WSL2


A live configuration repository: configs are consumed through symlinks, never copied.

Windows:  %USERPROFILE%\.config\wezterm\wezterm.lua  → wezterm/wezterm.lua
          %USERPROFILE%\.config\wezterm\fonts        → wezterm/fonts
          %USERPROFILE%\.config\wezterm\cockpit      → wezterm/cockpit
WSL:      ~/.config/starship.toml                     → starship/starship.toml
          ~/.local/bin/ck*                            → scripts/ck*

🏛️ Architecture

WezTerm (UI layer)                      Starship (prompt layer)
  LEADER+P  action palette               git branch/status + ☸ k8s context/ns
  right status bar (file read only)      (kubeconfig only: no API calls)
        │ SendString / InputSelector
        ▼
  scripts/ck*  (bash inside WSL, timeout-guarded and cached — also
               usable directly from any shell)
        ├── git        → git CLI
        ├── k8s        → kubectl (k3s)
        ├── ci         → gh / glab when installed; public API (curl) for
        │                public GitHub repos; detected from repo files
        ├── argocd     → argocd CLI with a session, or read-only kubectl
        └── status     → writes ~/.cache/terminal-cockpit/state
                            ▲
  scripts/shell-hook.sh (bash): OSC 7 (cwd) + per-prompt status refresh

Core Principles

  • The shell stays the shell: The palette types plain commands into the active pane (history included). Nothing is replaced by a heavy monolithic app.
  • Nothing hangs: Every kubectl/argocd/curl call is wrapped in timeout with asynchronous caching. The WezTerm status bar only reads a local file written by the shell—it never spawns synchronous processes, meaning a down cluster can never freeze your UI.
  • Context-aware gating: Palette sections are strictly gated on real environment detection: installed tools (ck doctor), current repository and its provider, CI configs (.github/workflows / .gitlab-ci.yml), and ArgoCD status.
  • Zero duplication: Git context lives cleanly in Starship; cluster health lives in the WezTerm status bar.

🎮 Usage

Shortcut Action
CTRL+P Cockpit fuzzy palette (handled by WezTerm before Zellij)
LEADER then P Cockpit fuzzy palette (Git / Repo / K8s / Argo / CI / PR)
F9 Same palette, no leader needed (alternative trigger)
CTRL+H Updated Cockpit help overlay with current palette actions
All other shortcuts Unchanged (tmux-style, LEADER + 1..9, etc.)

Leader timing: press Ctrl+A, release it, then press p within the 1-second leader timeout. Holding Ctrl while pressing p sends CTRL+P to the palette directly. If in doubt, use F9.

Launcher: the + button is always visible beside the tabs. Left-click creates a tab; right-click opens the WezTerm launcher menu, including the WSL, PowerShell and Zellij entries.

Tab titles: the shell hook publishes the current directory and the last command, so a tab appears as ~ > ls or project > git instead of wslhost.exe. Reload the shell hook after installing or updating it.

Palette Highlights

  • Split mode: long-running operations have (split) variants (pods → logs (-f, split), rollout status (split), Argo app sync/logs (split)) that run in an automatic side-by-side split pane (like CTRL+SHIFT+D); close it with CTRL+SHIFT+W.
  • Pull requests: on GitHub repos with gh installed: PR: list / create (title + body) / checks (current branch) / merge (editable flags).
  • ArgoCD health at a glance: the status bar shows ⎈ 9✓ in green, or ⎈ 8✓1✗ in red when an app is not Healthy/Synced. |
  • Desktop app overlay: the Cockpit palette can list visible Windows applications and attach one as a reversible overlay over the WezTerm window. Use Cockpit: attach desktop app (overlay) and release it with Cockpit: detach desktop app. Exact pane-level placement is not available in WezTerm 20240203 yet; the current implementation intentionally uses the full WezTerm window instead of guessing pane coordinates.
  • Help stays current: CTRL+H documents the current layout, focus mode, notification and desktop-overlay actions.

Direct CLI (Works standalone without WezTerm)

ck doctor                      # Check what is installed in WSL
ck status [--force]            # Refresh k8s/argo state (also feeds WezTerm)
ck git info | branches | url repo|pulls|ci
ck k8s contexts|namespaces|pods|deployments|services|events [--names] [ns]
ck ci detect|runs|failed|ids|view <id>|rerun <id>|page
ck argocd detect|apps|names|get|sync|refresh|history|logs <app>

⚙️ Installation & Replication

  1. Set up the symlinks shown above (Windows: New-Item -ItemType SymbolicLink; WSL: ln -s).
  2. Hook into your shell by adding this line at the end of ~/.bashrc (WSL Debian):
    source /mnt/c/dev/dotfiles/scripts/shell-hook.sh
  3. Ensure line endings (LF): Scripts must keep LF endings (.gitattributes enforces this; note that on /mnt/c, CRLF breaks bash scripts).
  4. Session layer (Zellij): download the zellij-x86_64-unknown-linux-musl release into ~/.local/bin/zellij and symlink ~/.config/zellij to this repo's zellij/ directory.

📂 Repository Structure

  • wezterm/wezterm.lua — Base configuration + guarded (pcall) cockpit loading.
  • wezterm/cockpit/ — Modular UI components: init (wiring), config (constants), wsl (WezTerm⇄WSL bridge), util (send/split/pickers), status, palette, and domain entries (git, k8s, argocd, ci, pr).
  • scripts/ — The ck command dispatcher + specialized scripts (ck-git, ck-k8s, ck-ci, ck-argocd, ck-status), shell-hook.sh, termdeck-windows.ps1, and lib/common.sh.
  • starship/starship.toml — Prompt layout with integrated kubernetes module.
  • zellij/ — Zellij session layer (config.kdl, deployed via symlink to ~/.config/zellij).
  • wezterm/fonts/ — JetBrainsMono Nerd Font, licensed under the SIL Open Font License 1.1 (see wezterm/fonts/OFL.txt).

💡 Verified Environment Notes

  • Tested on WezTerm 20240203, WSL2 Debian, using kubectl bound to the k3s binary.
  • Graceful Degradation: gh is installed (PR entries plus full CI read/write on GitHub repos); if glab or the argocd CLI are missing, those palette sections stay hidden until installed.
  • Zellij session layer: open or re-attach the cockpit session from the palette (Cockpit: zellij session) or the launcher; its bottom bar shows contextual shortcuts and sessions survive closing WezTerm.
  • Resilience: If the k3s API drops, the status bar safely displays ☸ ctx · ns with a red indicator, and K8s pickers report "no results" instead of locking up the terminal.

About

A robust terminal cockpit uniting WezTerm, Starship, and custom WSL scripts. Features non-blocking Kubernetes/ArgoCD integration, fuzzy action palettes, and zero-lag status monitoring.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages