Integrated Terminal

Integrated Terminal

Tuim features a dedicated, persistent integrated terminal docked directly beneath your code editor. Unlike standard subshells that disappear when closed, Tuim's terminal session stays alive in the background while you focus on writing code.

---

1. Opening & Closing the Terminal

• Toggle Shortcut: Press Ctrl+T (or Alt+T in the Vim-safe preset).
• Focus Cycling: Press F6 or Shift+F6 to cycle focus directly into and out of the terminal.
• Persistent Sessions: Hiding the terminal panel with Ctrl+T or entering Zen mode (F11) does not terminate running processes. Long-running builds, servers, or CLI tools continue executing seamlessly.

Terminal Split Controls (When Terminal is Focused)

When your cursor is inside the terminal panel, Tuim provides native terminal split management shortcuts:

• Alt+V: Create vertical terminal split
• Alt+S: Create horizontal terminal split
• Alt+C: Close focused terminal split
• Alt+O: Cycle focus between open terminal splits
• Alt+H / Alt+J / Alt+K / Alt+L: Move directional focus between splits (or return to editor)

---

2. Navigating Scrollback with Keyboard

Tuim uses Neovim's terminal-normal mode to provide rich, keyboard-driven scrollback inspection:

1. Enter Scrollback Mode: While the terminal is focused, press:

   Ctrl+\, followed by Ctrl+N
   

2. Move Around with Vim Motions: Use standard navigation keys:
   • h, j, k, l for directional movement
   • Ctrl+U / Ctrl+D for half-page scrolling
   • gg / G to jump to the top / bottom of scrollback history
3. Select & Copy Text:
   • Press v to start character selection.
   • Press V for line selection, or Ctrl+V for block selection.
   • Expand your selection using motions.
   • Press y to yank (copy) the selected text. If a system clipboard provider is available (xclip, wl-copy, pbcopy), the text is copied directly to your host clipboard.
4. Resume Typing: Press i or a to exit scrollback mode and resume live shell input.

---

3. Mouse Interaction in the Terminal

• Scroll Wheel: Rotate the mouse wheel while hovering over the terminal panel to scroll through history.
• Click to Focus: Left-clicking anywhere in the active shell row immediately focuses the live prompt.
• Left-Click Drag Selection: Click and drag across terminal output to visually highlight text, identical to desktop terminal emulators.
• Mouse Event Forwarding: If a program running inside the terminal enables terminal mouse reporting (such as htop, tmux, or fzf), Tuim forwards mouse clicks and drags directly to that program. When you need to select text from such programs, use the keyboard route (Ctrl+\ Ctrl+N).

---

4. Terminal Architecture

Under the hood, Tuim starts a dedicated, lightweight Neovim process (src/nvim/terminal_init.lua) specifically to drive the terminal interface. This process does not load heavy editor plugins (Treesitter, LSP, Telescope), ensuring minimal memory overhead and zero latency impact on your primary code editor.

---

Next Steps

Learn how to review and commit changes in Git Integration.