How to Enable and Configure Image Preview Using Sixel in Superfile

Sixel image preview is referenced in the Superfile codebase but is not yet implemented; to view images today, enable show_image_preview in config.toml and Superfile will automatically select the Kitty protocol or fall back to ANSI block rendering.

Superfile is a terminal-based file manager designed to render image previews directly inside the console. While the repository contains hooks for Sixel—the legacy DEC graphics standard—the feature remains incomplete in current builds. Understanding how to enable and configure image preview using Sixel in superfile requires examining the protocol detection logic, the configuration struct, and the actual rendering pipeline implemented in the Go source.

Current Sixel Implementation Status

The Superfile codebase acknowledges Sixel as a potential rendering target, but the actual graphics pipeline is missing. In src/config/icon/icon.go, you will find a sixel entry mapped to the generic "image" icon type, indicating the protocol is cataloged for future support.

However, inspection of src/pkg/file_preview/image_preview.go reveals that the ImagePreviewer struct only implements two rendering paths:

1. Kitty graphics protocol – Full-pixel, transparent rendering for compatible terminals
2. ANSI fallback – Coarse representation using colored Unicode blocks

There is no renderSixel() function or Sixel-specific encoding logic in the current source, meaning terminals advertising Sixel capability via $TERM or $TERM_PROGRAM will not trigger a Sixel render.

Enabling Image Previews via Configuration

Despite the incomplete Sixel support, you can activate the image preview feature to utilize the working protocols. The toggle is controlled by the ShowImagePreview boolean field defined in src/internal/common/config_type.go.

To enable previews, modify your configuration file:

# src/superfile_config/config.toml

# Enable image preview for any supported protocol (Kitty, ANSI, future Sixel)

show_image_preview = true

The configuration struct binds this value as follows:

// src/internal/common/config_type.go
type Config struct {
    ShowImagePreview bool `toml:"show_image_preview" comment:"\nWhether to show image preview."`
}

When this flag is set to true, Superfile enters the preview pipeline on file selection. When future versions implement the Sixel renderer, this same configuration flag will activate it automatically on compatible terminals without requiring changes to your configuration file.

Protocol Selection and Terminal Detection

Superfile determines which rendering engine to use by inspecting environment variables and terminal capabilities. The selection hierarchy implemented in src/pkg/file_preview/image_preview.go follows this logic:

• Kitty detection – Checks for Kitty-specific environment variables and terminal responses
• Sixel detection – Recognizes the capability string but currently skips to fallback (see the isSixelSupported() placeholder logic)
• ANSI fallback – Default pathway when no graphics protocol is available

The simplified rendering dispatch looks like this:

// src/pkg/file_preview/image_preview.go (simplified)
func (p *ImagePreviewer) Render(ctx Context) error {
    if p.isKittySupported() {
        return p.renderKitty(ctx)   // Full‑color preview
    }
    // No Kitty → fall back to ANSI blocks (Sixel not yet available)
    return p.renderANSI(ctx)
}

Superfile reads $TERM and $TERM_PROGRAM during initialization to populate these capability checks.

Testing the ANSI Fallback

If you want to observe how Superfile behaves when neither Kitty nor Sixel is available—effectively previewing the current fallback behavior—you can force the ANSI renderer by launching Superfile in a generic terminal environment:

# Example: run Superfile in a plain xterm that lacks Kitty protocol

export TERM=xterm
superfile

This is useful for testing the configuration activation (show_image_preview = true) on systems where you cannot install a Kitty-compatible terminal emulator.

Summary

• Sixel is recognized but unimplemented: The sixel string exists in src/config/icon/icon.go, but src/pkg/file_preview/image_preview.go lacks a corresponding renderer.
• Enable previews with one flag: Set show_image_preview = true in src/superfile_config/config.toml to activate the preview pipeline.
• Automatic protocol selection: Superfile prioritizes the Kitty graphics protocol and degrades gracefully to ANSI Unicode blocks when necessary.
• Future-proof configuration: When Sixel support ships, it will activate automatically under the existing ShowImagePreview configuration on terminals advertising the capability.

Frequently Asked Questions

Is Sixel image preview currently working in Superfile?

No. While the codebase contains a sixel entry in the icon map at src/config/icon/icon.go and recognizes the capability string during terminal detection, the actual rendering implementation in src/pkg/file_preview/image_preview.go has not been written. Superfile currently only renders images using the Kitty graphics protocol or ANSI Unicode blocks.

How do I enable image previews in Superfile right now?

Edit your src/superfile_config/config.toml file and set show_image_preview = true. This boolean field, defined in src/internal/common/config_type.go, activates the preview pipeline. Superfile will then automatically negotiate with your terminal to use the best available rendering method.

What happens if my terminal doesn't support the Kitty protocol?

Superfile detects terminal capabilities via environment variables such as $TERM and $TERM_PROGRAM. If Kitty graphics are unavailable, it automatically falls back to an ANSI-based preview that uses colored Unicode blocks to approximate the image content, as implemented in the renderANSI method.

Will the same configuration work when Sixel support is added?

Yes. According to the Config struct definition in src/internal/common/config_type.go, the ShowImagePreview flag is protocol-agnostic. When Sixel rendering is eventually implemented, it will activate automatically on terminals advertising Sixel capability when this flag is set to true, without requiring additional configuration changes.

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