docs: update documentation for latest changes
- Add stt-ptt language support documentation - Add rofi-project-opener module documentation - Add rofi-project-opener package documentation - Update zellij-ps documentation - Update guides and reference patterns - Update AGENTS.md with latest commands
This commit is contained in:
m3tm3re
245
docs/packages/rofi-project-opener.md
Normal file
245
docs/packages/rofi-project-opener.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# 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
|
||||
@@ -78,7 +78,7 @@ Folders should be delimited by `:` and can include `~` for home directory.
|
||||
{config, ...}: {
|
||||
imports = [m3ta-nixpkgs.homeManagerModules.default];
|
||||
|
||||
m3ta.cli.zellij-ps = {
|
||||
cli.zellij-ps = {
|
||||
enable = true;
|
||||
};
|
||||
}
|
||||
@@ -86,14 +86,14 @@ Folders should be delimited by `:` and can include `~` for home directory.
|
||||
|
||||
### Module Options
|
||||
|
||||
#### `m3ta.cli.zellij-ps.enable`
|
||||
#### `cli.zellij-ps.enable`
|
||||
|
||||
Enable the zellij-ps module.
|
||||
|
||||
- Type: `boolean`
|
||||
- Default: `false`
|
||||
|
||||
#### `m3ta.cli.zellij-ps.package`
|
||||
#### `cli.zellij-ps.package`
|
||||
|
||||
Custom package to use.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user