nixpkgs/docs/packages/zellij-ps.md

zellij-ps

A Zellij project switcher for quickly navigating and opening project workspaces.

Description

zellij-ps is a Fish script inspired by ThePrimeagen's tmux-sessionizer. It provides a fast, interactive way to switch between project folders in Zellij. Using fd for fast directory discovery and fzf for fuzzy selection, it helps you quickly jump into your work.

The script searches through your configured project folders ($PROJECT_FOLDERS) and either creates a new Zellij session for the selected project or attaches to an existing one.

Installation

Via Overlay

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    zellij-ps
  ];
}

Direct Reference

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.zellij-ps
  ];
}

Run Directly

nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps

Usage

Basic Usage

# Run from outside Zellij to start a project session
zellij-ps

# Or pass a project path directly
zellij-ps ~/projects/my-project

This will:

1. Search through your $PROJECT_FOLDERS for directories
2. Open fzf for fuzzy project selection (if no argument provided)
3. Create a new Zellij session or attach to existing one for the selected project

Configuration

Set your project folders in your shell configuration:

Fish example:

set -x PROJECT_FOLDERS ~/projects:~/code:~/work

Bash/Zsh example:

export PROJECT_FOLDERS="$HOME/projects:$HOME/code:$HOME/work"

Folders should be delimited by : and can include ~ for home directory.

Home Manager Module

Enable Module

{config, ...}: {
  imports = [m3ta-nixpkgs.homeManagerModules.default];

  m3ta.cli.zellij-ps = {
    enable = true;
  };
}

Module Options

m3ta.cli.zellij-ps.enable

Enable the zellij-ps module.

• Type: boolean
• Default: false

m3ta.cli.zellij-ps.package

Custom package to use.

• Type: package
• Default: pkgs.zellij-ps

Requirements

System Requirements

• Linux or Unix-like system
• Configured $PROJECT_FOLDERS environment variable

Platform Support

• Linux (primary)
• macOS (may work)
• Windows (not supported)

Build Information

• Version: 0.1.0
• Type: Fish script
• License: MIT
• Inspired by: ThePrimeagen's tmux-sessionizer
• Source: Gitea

Source Code

The script is available at:

https://code.m3ta.dev/m3tam3re/helper-scripts/src/branch/main/zellij-ps.fish

Troubleshooting

No Projects Found

If fzf shows no results, check your $PROJECT_FOLDERS variable:

# In fish
echo $PROJECT_FOLDERS

# In bash/zsh
echo $PROJECT_FOLDERS

Ensure the folders exist and contain subdirectories.

Already in Zellij Session

If you're already inside a Zellij session, you'll see:

You are in a Zellij Session!
Please use the session manager to switch sessions.

Use Zellij's built-in session manager (Ctrl+p → s) to switch sessions instead.

fd Not Found

Error: fd: command not found

Solution: Ensure fd is installed:

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    fd
  ];
}

Fish Not Found

Error: fish: command not found

Solution: Ensure Fish is installed:

{pkgs, ...}: {
  programs.fish = {
    enable = true;
  };
}

fzf Not Working

Ensure fzf is installed and configured:

# Check fzf
which fzf

# Test fzf
echo -e "item1\nitem2\nitem3" | fzf

Related

• zellij-ps Module - Home Manager module documentation
• Using Modules - How to use modules
• Adding Packages - How to add new packages
• Quick Start - Getting started guide