nixpkgs/docs/packages/rofi-project-opener.md

rofi-project-opener

A Rofi-based project directory launcher for quickly opening projects in your terminal with custom commands.

Description

rofi-project-opener scans configured base directories for project subdirectories and presents them in a Rofi menu. When a project is selected, it opens a terminal, navigates to the project directory, and runs a configurable command (defaults to opencode).

Key features:

• JSON-based configuration for project directories
• Per-directory custom arguments (e.g., --agent chiron for AI coding assistants)
• Placeholder support (%s for path, %a for args) in custom commands
• Works with any terminal emulator

Installation

Via Overlay

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    rofi-project-opener
  ];
}

Direct Reference

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

Run Directly

nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#rofi-project-opener

Usage

Basic Usage

# Launch rofi project selector
rofi-project-opener

This will:

1. Read project directories from ~/.config/rofi-project-opener/projects.json
2. Scan each directory for subdirectories (non-hidden)
3. Display projects in Rofi for fuzzy selection
4. Open terminal, cd to project, and run the configured command

Configuration Files

The script uses two configuration files in ~/.config/rofi-project-opener/:

projects.json - Project directories with optional args:

{
  "nixpkgs": {"path": "~/p/NIX", "args": ""},
  "chat": {"path": "~/p/CHAT", "args": "--agent chiron"},
  "dev": {"path": "~/dev", "args": ""}
}

config - Terminal and Rofi settings:

TERMINAL="/path/to/kitty"
TERMINAL_CMD="opencode %a"
ROFI_PROMPT="Select project"
ROFI_ARGS="-dmenu -i"

Placeholders

When using terminalCommand, these placeholders are available:

Placeholder	Description
%s	Full path to selected project
%a	Args from projectDirs config

Examples:

terminalCommand = "opencode %a";           # opencode with project args
terminalCommand = "nvim";                  # just nvim, no args
terminalCommand = "code %s";               # vscode with explicit path
terminalCommand = "myapp --dir %s %a";     # custom app with both

Home Manager Module

Enable Module

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

  cli.rofi-project-opener = {
    enable = true;
    projectDirs = {
      nixpkgs = { path = "~/p/NIX"; };
      chat = { path = "~/p/CHAT"; args = "--agent chiron"; };
      dev = { path = "~/dev"; };
    };
    terminal = pkgs.kitty;
    terminalCommand = "opencode %a";
  };
}

Module Options

cli.rofi-project-opener.enable

Enable the rofi-project-opener module.

• Type: boolean
• Default: false

cli.rofi-project-opener.projectDirs

Attribute set of base directories to scan for projects.

• Type: attrsOf (submodule { path, args })
• Default: { dev = { path = "~/dev"; }; projects = { path = "~/projects"; }; }

Each entry supports:

• path (required): Base directory path
• args (optional): Arguments to pass to the command

cli.rofi-project-opener.terminal

Terminal emulator to use.

• Type: either str package
• Default: "kitty"

cli.rofi-project-opener.terminalCommand

Command to run in the terminal. Supports %s (path) and %a (args) placeholders.

• Type: str
• Default: "" (runs opencode %a)

cli.rofi-project-opener.rofiPrompt

Prompt text displayed in Rofi.

• Type: str
• Default: "Select project"

cli.rofi-project-opener.rofiArgs

Arguments to pass to Rofi.

• Type: listOf str
• Default: ["-dmenu" "-i"]

Requirements

System Requirements

• Linux with Rofi installed
• A terminal emulator (kitty, alacritty, etc.)
• jq (included as dependency)

Runtime Dependencies

These are automatically included:

• rofi
• jq
• coreutils
• gnugrep
• gnused
• libnotify

Platform Support

• Linux (primary)
• macOS (not tested)
• Windows (not supported)

Build Information

• Type: Bash script
• License: MIT

Troubleshooting

No Projects Found

Check that your project directories exist and contain subdirectories:

cat ~/.config/rofi-project-opener/projects.json
ls ~/p/NIX  # Should show subdirectories

Args Not Being Passed

Make sure you're using %a placeholder in your terminalCommand:

# Wrong - args not passed
terminalCommand = "opencode";

# Correct - args passed via placeholder
terminalCommand = "opencode %a";

# Also correct - empty uses default behavior with args
terminalCommand = "";

Rofi Not Showing

Ensure Rofi is installed and working:

echo -e "item1\nitem2" | rofi -dmenu

Terminal Not Opening

Check terminal configuration:

# Using package
terminal = pkgs.kitty;

# Using string (must be in PATH)
terminal = "kitty";

Related

• rofi-project-opener Module - Home Manager module documentation
• zellij-ps - Similar project switcher for Zellij
• Using Modules - How to use modules