Tessera

Tessera is a lightweight, project-aware file explorer for the Zellij terminal multiplexer. It's designed to act as a permanent sidebar, allowing you to navigate your filesystem, search files with fzf, and manage project-specific bookmarks—all while keeping your favorite editor (Neovim, Vim, or Helix) in focus.

Features

• Zellij Integration: Automatically positions itself as a sidebar, and opens files in adjacent tiled panes.
• Fuzzy Search (s): Built-in fzf integration to jump instantly to any file in your project.
• Automatic Reloading: Real-time synchronization with your filesystem using watchdog.
• Project Bookmarks (b / B): Manage a flat list of important files/folders specific to each project.
• Dotfile Toggle (d): Quickly hide or show hidden files, with persistent preference.
• Custom Theming: Default "novadust" theme with truecolor support, plus all Textual built-in themes.
• Smart Root Label: Automatically displays your project's folder name (e.g., 📂 fwkos) at the top of the tree.
• Scroll Preservation: Tree reloads and navigations preserve your exact cursor and scroll position.

Installation

Prerequisites

• uv (Python package and tool manager)
• fzf (optional, but highly recommended for the search feature)
• Zellij 0.44.0+

Step-by-Step

1. Clone this repository and navigate into the root directory.
2. Run the install script:

   ./install.sh
   

   This will install the tes command to your system (typically ~/.local/bin).

Usage & Keybindings

Tessera is best used by binding it to a key in your Zellij config.kdl.

Default Bindings

Key	Action
Enter	Open file in adjacent pane or expand directory
s	Search current project with fzf
d	Toggle hidden files (dotfiles)
b	Toggle bookmark for the highlighted file/folder
B	Toggle visibility of the Bookmarks section
Tab	Switch focus between Bookmarks and File Explorer
q / Esc	Quit Tessera

Zellij Configuration (config.kdl)

We recommend running Tessera as a tiled pane on the far left:

bind "Ctrl t" {
    Run "tes" {
        close_on_exit true
    }
}

Customization

Configuration File

Tessera stores its configuration in ~/.config/tessera/config.json. It automatically tracks your theme, dotfile visibility, and project bookmarks.

{
    "theme": "novadust",
    "show_hidden": false,
    "show_bookmarks": true,
    "bookmarks": {
        "/home/user/my-project": ["/home/user/my-project/src/main.py"]
    }
}

CLI Overrides

You can override the theme or specify a custom CSS file:

tes --theme nord
tes --css ~/my_styles.css