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

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

### Direct Reference

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

### Run Directly

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

## Usage

### Basic Usage

```bash
# 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:
```json
{
  "nixpkgs": {"path": "~/p/NIX", "args": ""},
  "chat": {"path": "~/p/CHAT", "args": "--agent chiron"},
  "dev": {"path": "~/dev", "args": ""}
}
```

**config** - Terminal and Rofi settings:
```bash
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:**
```nix
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

```nix
{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:

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

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

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

### Terminal Not Opening

Check terminal configuration:

```nix
# Using package
terminal = pkgs.kitty;

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

## Related

- [rofi-project-opener Module](../modules/home-manager/cli/rofi-project-opener.md) - Home Manager module documentation
- [zellij-ps](./zellij-ps.md) - Similar project switcher for Zellij
- [Using Modules](../guides/using-modules.md) - How to use modules