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

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

### Direct Reference

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

### Run Directly

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

## Usage

### Basic Usage

```bash
# 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:**
```fish
set -x PROJECT_FOLDERS ~/projects:~/code:~/work
```

**Bash/Zsh example:**
```bash
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

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

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

### Module Options

#### `cli.zellij-ps.enable`

Enable the zellij-ps module.

- Type: `boolean`
- Default: `false`

#### `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](https://github.com/ThePrimeagen/.dotfiles/blob/master/bin/.local/scripts/tmux-sessionizer)
- **Source**: [Gitea](https://code.m3ta.dev/m3tam3re/helper-scripts)

## 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:

```bash
# 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:

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

### Fish Not Found

Error: `fish: command not found`

**Solution**: Ensure Fish is installed:

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

### fzf Not Working

Ensure fzf is installed and configured:

```bash
# Check fzf
which fzf

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

## Related

- [zellij-ps Module](../modules/home-manager/cli/zellij-ps.md) - Home Manager module documentation
- [Using Modules](../guides/using-modules.md) - How to use modules
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
- [Quick Start](../QUICKSTART.md) - Getting started guide