Home

Tuim - Text Editor Wiki

Welcome to the official Tuim Wiki! Tuim is a modern terminal workspace written in Zig with an embedded, isolated Neovim editing engine. It combines an Explorer, Git sidebar, persistent integrated shell, native settings panel, and coding assistant launchers into one keyboard- and mouse-accessible interface.

Whether you are a newcomer looking to get started, an experienced user configuring plugins and themes, a developer contributing code, or someone diagnosing an issue, this wiki covers everything you need to know.

---

Quick Navigation

Tuim Wiki
├── 🚀 Getting Started
│   ├── Installation (Script, Bundles, AppImage, Source)
│   ├── Quick Start & First Run
│   └── Updating & Uninstalling
├── 📖 User Guide
│   ├── Workspace Overview & Layout
│   ├── Three Editing Modes (Normal, IDE, Zen)
│   ├── Keybindings & Customization
│   ├── File & Buffer Management
│   ├── Integrated Terminal & Scrollback
│   ├── Git Integration
│   ├── Extensions & Plugin Management
│   ├── Language Tools, Treesitter & LSP
│   └── AI Coding Assistants
├── ⚙️ Configuration
│   ├── Configuration Directories (XDG)
│   ├── Native Settings UI
│   ├── Themes & Desktop Styling (Omarchy)
│   └── Custom Plugin Configuration (Lua Specs)
├── 🛠️ Troubleshooting & Bug Reporting
│   ├── Recovery Mode (TUIM_DISABLE_PLUGINS=1)
│   ├── Common Issues & Platform Quirks
│   ├── Logs & Diagnostics
│   ├── In-App Bug Reporter
│   └── Cloudflare Bug Report Gateway
├── 💻 Architecture & Development
│   ├── System Architecture & Process Model
│   ├── Building from Source (Zig 0.16.0)
│   ├── Testing Suite & Verification
│   ├── Performance Profiling
│   ├── Packaging & Release Engineering
│   └── Contributing Guidelines
└── 📚 Compatibility & Reference
    ├── Complete Keybindings Cheat Sheet
    ├── Terminal Compatibility Matrix
    └── Plugin Compatibility Guide

---

Wiki Highlights by Category

🚀 Getting Started

• Installation Guide: Install using the one-line curl script, download pre-built native bundles (Linux & macOS), run the portable AppImage, or compile from source.
• Quick Start: Step-by-step walkthrough of your first session, using the onboarding wizard, basic navigation, and saving your first file.
• Updating & Uninstalling: How in-place updates preserve your settings and how to perform clean or selective uninstalls.

📖 User Guide

• Workspace Overview: Understand the unified sidebar, region cycling (F6/Shift+F6), panel resizing, and mouse controls.
• Editing Modes: Deep dive into Normal (modal Vim motions), IDE (modeless editing with standard shortcuts), and Zen (distraction-free focus).
• Keybindings & Shortcuts: TUI controls, editor mappings, the interactive key recorder, and built-in Vim-safe/IDE presets.
• File & Buffer Management: Explorer file navigation, buffer switching without plugins, and Telescope project search (Ctrl+P, Alt+G).
• Integrated Terminal: Persistent shell panel (Ctrl+T), scrollback navigation with Vim motions and mouse selection, and clipboard forwarding.
• Git Integration: Inspecting working tree diffs, staging/unstaging changes (Space), and committing (c) right from the terminal UI.
• Extensions & Plugins: Managing plugins via the Extensions panel, browsing the Discover marketplace, and editing configuration overrides.
• Language Tools & LSP: Eager Treesitter highlighting with 19 precompiled parsers, Mason integration, and automatic project marker detection.
• AI Coding Assistants: Launching CLI assistants (Antigravity, Claude Code, Codex, Gemini, OpenCode, Copilot) with editor context sharing (Send selection, Send file, Review changes).

⚙️ Configuration

• Configuration Directories: Isolated XDG storage paths (~/.config/tuim, ~/.local/share/tuim, etc.) ensuring zero conflict with your system Neovim.
• Settings UI: Customizing Appearance, Editor settings (column rulers, indentation), and Keyboard Shortcuts.
• Themes & Styling: Default VS Code Dark Modern theme, following the desktop palette via the Omarchy System theme, and Nerd Fonts vs portable symbols.
• Custom Plugin Configuration: Writing lazy.nvim spec overrides with opts and config in Lua.

🛠️ Troubleshooting & Bug Reporting

• Recovery Mode: Launching with TUIM_DISABLE_PLUGINS=1 tuim to recover from broken plugin configurations.
• Common Issues & Fixes: Resolving broken font icons, missing clipboard providers, modifier key reporting quirks, and tmux/SSH behavior.
• Logs & Diagnostics: Accessing Tuim log files, Neovim error messages, and system diagnostic snapshots.
• In-App Bug Reporting: Built-in bug reporting status and GitHub Issues workflow (Work in Progress).
• Bug Report Gateway: Cloudflare Worker reporting proxy placeholder and status (Work in Progress).

💻 Architecture & Development

• Architecture Overview: Dual Neovim architecture, Zig event reactor (src/reactor.zig), MessagePack-RPC protocol, and differential row-run renderer.
• Building from Source: Compiling with Zig 0.16.0, build options, and running local developer builds.
• Testing & Verification: Running unit tests (zig build test), PTY integration tests, UI automation, and Shellcheck.
• Performance Profiling: Measuring cold startup latency, resize storms, large Unicode files, and 5,000 file directories.
• Packaging & Releases: Generating cross-platform native bundles, building AppImages, and GitHub Actions release workflows.
• Contributing Guidelines: Development workflow, coding style conventions for Zig/Lua/Python, and pull request checklist.

📚 Compatibility & Reference

• Keybindings Cheat Sheet: Quick-reference table of every shortcut in Tuim organized by mode and context.
• Terminal Compatibility Matrix: Verified behavior across Alacritty, Kitty, Ghostty, WezTerm, GNOME Terminal, Konsole, macOS Terminal, iTerm2, tmux, and OpenSSH.
• Plugin Compatibility Guide: Detailed analysis of what makes plugins compatible with Tuim's multigrid architecture.

---

Tip

Use the sidebar on the left to jump directly to any topic, or press F1 inside Tuim to explore the interactive command menu!