diff --git a/99 Daily/2026-04-17.md b/99 Daily/2026-04-17.md index dd6c069..b0a5396 100644 --- a/99 Daily/2026-04-17.md +++ b/99 Daily/2026-04-17.md @@ -191,3 +191,6 @@ tags: [daily] - 12:54 | `memory-compiler` - **Asked:** Compile a new article about wezterm key bindings into the wiki knowledge base. - **Done:** Created structured wiki article on wezterm key bindings covering modifiers, key types, leader keys, and debugging. +- 12:55 (<1min) | `memory-compiler` + - **Asked:** Asked | Done | Log + - **Done:** --- | --- | --- diff --git a/raw/Key Tables - Wez's Terminal Emulator.md b/raw/_processed/Key Tables - Wez's Terminal Emulator.md similarity index 100% rename from raw/Key Tables - Wez's Terminal Emulator.md rename to raw/_processed/Key Tables - Wez's Terminal Emulator.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index cd69f87..0c2faee 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -28,7 +28,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/qa/_index\|qa/]] | Filed answers to queries (saved with `--file-back`) | 0 | | [[wiki/homelab/_index\|homelab/]] | Self-hosted infra: Proxmox install, IOMMU/PCI passthrough, hypervisor setup, budget builds | 2 | | [[wiki/web-agency/_index\|web-agency/]] | AI-assisted website building & selling: Claude Code, Nanobanana 2, Kling, LaunchPath MCP | 1 | -| [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 11 | +| [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 12 | | [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 14 | | [[wiki/llm-models/_index\|llm-models/]] | OpenAI model catalog — GPT-5.x, o-series reasoning, audio/realtime, embeddings, moderation | 1 | diff --git a/wiki/dotfiles/_index.md b/wiki/dotfiles/_index.md index c0e59cb..4a3011d 100644 --- a/wiki/dotfiles/_index.md +++ b/wiki/dotfiles/_index.md @@ -15,3 +15,4 @@ Linux terminal customization, shell configs, CLI tool setups, and ricing guides. | [[wiki/dotfiles/wezterm-fonts\|wezterm-fonts]] | Font selection, fallback chains, bundled fonts, key config options, ls-fonts debug CLI | wezterm.org/config/fonts.html | 2026-04-17 | | [[wiki/dotfiles/fish-shell-intro\|fish-shell-intro]] | Fish shell intro: features, setup, default shell, config files, PATH, shebang, exit handlers | fishshell.com/docs/current/index.html | 2026-04-17 | | [[wiki/dotfiles/wezterm-key-bindings\|wezterm-key-bindings]] | Key binding config: modifiers, phys/mapped/raw prefixes, Leader key, CapsLock-as-leader, debug | wezterm.org/config/keys.html | 2026-04-17 | +| [[wiki/dotfiles/wezterm-key-tables\|wezterm-key-tables]] | Modal keybinding layers via key_tables: ActivateKeyTable, activation stack, one_shot, timeout | wezterm.org/config/key-tables.html | 2026-04-17 | diff --git a/wiki/dotfiles/wezterm-key-tables.md b/wiki/dotfiles/wezterm-key-tables.md new file mode 100644 index 0000000..952dba2 --- /dev/null +++ b/wiki/dotfiles/wezterm-key-tables.md @@ -0,0 +1,141 @@ +--- +title: "WezTerm Key Tables (Modal Keybindings)" +aliases: [wezterm-modal-keys, key-table-activation, wezterm-leader-modes] +tags: [wezterm, keybindings, lua, terminal, modal] +sources: [raw/Key Tables - Wez's Terminal Emulator.md] +created: 2026-04-17 +updated: 2026-04-17 +--- + +## Overview + +Key tables let you define **named sets of keybindings** that activate on demand — enabling modal keybinding workflows similar to Vim modes. Available since WezTerm `20220408-101518-b908e2dd`. + +Defined via the `key_tables` config option; triggered via the `ActivateKeyTable` action. + +--- + +## How It Works + +1. Define named tables in `config.key_tables = { ... }` +2. Bind a trigger key (often prefixed with `LEADER`) to `act.ActivateKeyTable { name = '...' }` +3. WezTerm pushes that table onto its **activation stack** — keys in that table take effect +4. Exit the mode via `PopKeyTable`, timeout, or `one_shot = true` + +--- + +## Activation Stack + +Each WezTerm window maintains a **stack** of active key tables: + +| Action | Effect | +|--------|--------| +| `ActivateKeyTable` | Push a table onto the stack | +| `PopKeyTable` | Pop the top entry | +| `ClearKeyTableStack` | Clear entire stack | +| Config reload | Stack is also cleared automatically | + +Key resolution walks **top → bottom** of the stack until a match is found (layering behavior added in `20220624-141144-bd1b7c5d`). + +--- + +## `ActivateKeyTable` Options + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Name of the key table to activate | +| `one_shot` | bool | If `true`, table pops after one key press (default: `true`) | +| `timeout_milliseconds` | int | Auto-pop after N ms of inactivity | +| `replace_current` | bool | Implicitly pop current entry before pushing | + +--- + +## Example: Pane Resize & Activation Modes + +```lua +local wezterm = require 'wezterm' +local act = wezterm.action +local config = {} + +-- Show active key table in status bar +wezterm.on('update-right-status', function(window, pane) + local name = window:active_key_table() + if name then name = 'TABLE: ' .. name end + window:set_right_status(name or '') +end) + +config.leader = { key = 'Space', mods = 'CTRL|SHIFT' } +config.keys = { + -- LEADER + r → resize mode (persistent until Escape) + { key = 'r', mods = 'LEADER', + action = act.ActivateKeyTable { name = 'resize_pane', one_shot = false } }, + + -- LEADER + a → activate-pane mode (auto-exits after 1 second) + { key = 'a', mods = 'LEADER', + action = act.ActivateKeyTable { name = 'activate_pane', timeout_milliseconds = 1000 } }, +} + +config.key_tables = { + resize_pane = { + { key = 'LeftArrow', action = act.AdjustPaneSize { 'Left', 1 } }, + { key = 'h', action = act.AdjustPaneSize { 'Left', 1 } }, + { key = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } }, + { key = 'l', action = act.AdjustPaneSize { 'Right', 1 } }, + { key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } }, + { key = 'k', action = act.AdjustPaneSize { 'Up', 1 } }, + { key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } }, + { key = 'j', action = act.AdjustPaneSize { 'Down', 1 } }, + { key = 'Escape', action = 'PopKeyTable' }, + }, + activate_pane = { + { key = 'LeftArrow', action = act.ActivatePaneDirection 'Left' }, + { key = 'h', action = act.ActivatePaneDirection 'Left' }, + { key = 'RightArrow', action = act.ActivatePaneDirection 'Right' }, + { key = 'l', action = act.ActivatePaneDirection 'Right' }, + { key = 'UpArrow', action = act.ActivatePaneDirection 'Up' }, + { key = 'k', action = act.ActivatePaneDirection 'Up' }, + { key = 'DownArrow', action = act.ActivatePaneDirection 'Down' }, + { key = 'j', action = act.ActivatePaneDirection 'Down' }, + }, +} +return config +``` + +--- + +## Showing Active Mode in Status Bar + +```lua +wezterm.on('update-right-status', function(window, pane) + local name = window:active_key_table() + window:set_right_status(name and ('TABLE: ' .. name) or '') +end) +``` + +Useful for knowing which modal layer is active. + +--- + +## Key Takeaways + +- Key tables = modal keybinding layers, like Vim modes in a terminal +- `one_shot = false` keeps the mode active until `Escape` / `PopKeyTable` +- `timeout_milliseconds` auto-exits modes after inactivity — good for "quick prefix" modes +- Stack layering (v`20220624+`) means tables compose rather than replace +- Config reload clears the stack — useful escape hatch when you get stuck +- Always show active table in status bar (`window:active_key_table()`) while developing +- Pair with `config.leader` for a two-key prefix workflow without holding many modifiers + +--- + +## Related + +- [[wiki/dotfiles/wezterm-key-bindings|WezTerm Key Bindings]] — base key config, Leader key, modifiers +- [[wiki/dotfiles/wezterm-default-keybindings|WezTerm Default Keybindings]] — full default key table reference +- [[wiki/dotfiles/wezterm-config|WezTerm Config]] — config file structure and live reload + +--- + +## Sources + +- `raw/Key Tables - Wez's Terminal Emulator.md` (clipped from wezterm.org/config/key-tables.html)