How to Integrate Superfile with Zoxide for Smart Directory Navigation

Superfile ships with a built-in zoxide plugin that enables fuzzy directory jumping via a searchable modal when you enable the zoxide_support configuration flag and press the z key.

Superfile is a modern terminal file manager written in Go that supports plugin-based extensibility. You can integrate superfile with zoxide to replace manual directory traversal with intelligent, frequency-based directory jumping directly inside your file manager. This integration leverages the github.com/lazysegtree/go-zoxide library to query your zoxide database and render results in a native modal window.

Enable Zoxide Support in the Configuration

Before using the navigation features, you must activate the plugin in Superfile’s global configuration. The zoxide_support boolean flag lives in src/superfile_config/config.toml at line 170.

Set the value to true to initialize the zoxide client:

# src/superfile_config/config.toml

zoxide_support = true   # Requires the external `zoxide` binary installed on your system

When this flag is enabled, Superfile loads the zoxide UI component at runtime and creates a client instance that connects to your local zoxide database (typically located at ~/.local/share/zoxide).

Trigger the Navigation Modal

Once enabled, open the zoxide search interface using the default hotkey binding defined in src/superfile_config/hotkeys.toml (line 69):

• Press z in the Superfile UI to dispatch the open_zoxide command.

This opens a modal titled "Zoxide Navigation" where you can type partial directory names. The modal queries the database live and presents fuzzy-matched results. Use the arrow keys to select an entry and press Enter to execute a ChangeDir action, which instantly switches Superfile’s working directory to the selected path.

How the Integration Works Under the Hood

The integration follows a clean three-layer architecture that separates configuration, state management, and rendering.

The Model and Client Initialization

The core state container resides in src/internal/ui/zoxide/model.go (lines 10–22). This file defines a Model struct that holds a pointer to the *zoxidelib.Client, the current query string, and the result list:

// Conceptual structure from src/internal/ui/zoxide/model.go
type Model struct {
    client    *zoxidelib.Client
    query     string
    results   []Result
    // ... other UI state fields
}

The GenerateModel function initializes this structure with your terminal dimensions and a pre-configured zoxide client.

Input Handling and Database Queries

Keyboard events are processed in src/internal/ui/zoxide/navigation.go. This handler forwards your typed query to the Go zoxide library and updates the model’s result slice with matching directories and their frequency scores.

When you press Enter on a selection, the navigation layer returns a message that triggers the directory change in Superfile’s core model.

Rendering and Modal Validation

The visual output is drawn by src/internal/ui/zoxide/render.go. If the zoxide binary is missing or the database is inaccessible, lines 22–31 display a helpful error message instead of crashing. The modal respects Superfile’s global UI state; src/internal/validation.go (line 427) ensures the zoxide window only opens when no other modal (help menus, prompts, or dialogs) is currently active.

Customize the Hotkey Binding

If the default z key conflicts with your workflow, remap the trigger in src/superfile_config/hotkeys.toml:

# src/superfile_config/hotkeys.toml

open_zoxide = ['x', '']   # Now pressing `x` opens the zoxide modal

You can assign any single character or an empty string to disable the binding entirely.

Summary

• Enable the plugin by setting zoxide_support = true in src/superfile_config/config.toml.
• Trigger the modal with the z key (or your custom binding) mapped to open_zoxide in src/superfile_config/hotkeys.toml.
• Architecture relies on src/internal/ui/zoxide/model.go for state, navigation.go for input handling, and render.go for display.
• Safety checks in src/internal/validation.go prevent modal conflicts, while render.go handles missing zoxide binaries gracefully.
• Database access occurs through github.com/lazysegtree/go-zoxide querying ~/.local/share/zoxide.

Frequently Asked Questions

Do I need to install zoxide separately to use this integration?

Yes. The zoxide_support flag in Superfile requires the external zoxide binary to be installed on your system and available in your PATH. Superfile uses the github.com/lazysegtree/go-zoxide Go library to interface with the zoxide database, but it does not bundle the underlying zoxide tool itself.

Can I change the default hotkey for opening the zoxide modal?

Yes. Edit the open_zoxide entry in src/superfile_config/hotkeys.toml to assign any key you prefer. For example, setting open_zoxide = ['f', ''] binds the modal to the f key instead of the default z.

What happens if I press the zoxide hotkey but the feature is disabled?

If zoxide_support is set to false (the default), pressing the assigned hotkey will have no effect because the command dispatcher only registers the open_zoxide action when the configuration flag is true. If the flag is enabled but zoxide is not installed, src/internal/ui/zoxide/render.go displays a user-friendly error message indicating that the zoxide binary is missing.

How does Superfile handle concurrent modal states?

Superfile prevents the zoxide modal from opening if another modal is already active. According to the validation logic in src/internal/validation.go at line 427, the application checks the global UI state before dispatching the open_zoxide command, ensuring that help menus, confirmation prompts, or other overlays remain in focus until dismissed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}