runit

A full-screen, fuzzy-searchable project picker for your terminal. Finds your projects, shows a live directory preview, and launches a dev server plus your editor on selection.

Install

npm install -g @mouhinou/runit-cli

That's the entire install. It automatically:

• Detects your shell (bash, zsh, or fish, via $SHELL)
• Adds the required one-line shell hook to ~/.bashrc, ~/.zshrc, or your fish config
• Self-heals that hook on every future npm install -g @mouhinou/runit-cli@latest — if the hook logic ever changes, your existing config is automatically upgraded in place, with no manual editing

Open a new terminal and runit is ready to use.

If your shell can't be auto-detected, or you're installing in a non-interactive context (CI, a Dockerfile), nothing is written automatically. Add one of these yourself instead:

# bash/zsh
eval "$(command runit --init bash)"   # or: zsh

# fish
command runit --init fish | source

Set RUNIT_SKIP_HOOK=1 before installing to opt out of automatic shell setup entirely.

Why a shell hook is required

runit is a normal npm binary, which means it runs as a separate process from your shell. A separate process can open windows, spawn other programs, and print output — but it can never change your shell's working directory. That's not a limitation of this tool; no standalone program can cd the shell that launched it.

The hook works around this the same way zoxide and nvm do: runit does the real work and prints only the selected path to stdout; the shell function wraps it and does the actual cd.

Commands

| Command | Description | |---|---| | runit | Open the picker | | runit <query> | Open the picker, pre-filtered | | runit --refresh | Rebuild the project cache (auto-expires after 10 minutes) | | runit --add-dir <path> | Add a folder to scan | | runit --remove-dir <path> | Remove a folder from scanning (asks to confirm) | | runit --roots | List the folders currently being scanned | | runit --init <shell> | Print the shell hook for bash, zsh, or fish | | runit --version | Print the installed version | | runit --help | Print usage |

Inside the picker: type to filter, arrow keys to move (clamped at the top/bottom, no wraparound), enter to launch, esc to quit without doing anything.

What happens on launch

1. Dev server opens in a new terminal window. Auto-detects, in order: Alacritty, kitty, gnome-terminal, konsole, xterm, Windows Terminal, Terminal.app. If none are found, it runs in the background and logs to <project>/.runit-dev.log.
2. Editor opens in the terminal you're sitting in. If the configured editor command isn't on your PATH, you're asked before anything is installed — and only offered an automatic install when the correct command for your package manager is known for certain (e.g. VS Code isn't in Arch's official repos, so that case links to the manual download instead of guessing a command that would fail).
3. Your shell cds into the selected project.

Config

~/.config/runit/config.json, created on first run:

{
  "roots": ["~/Documents", "~/Work", "~/Projects"],
  "editor": "code",
  "devCommand": "pnpm dev"
}

~ is expanded automatically. Edit this file directly, or use --add-dir/--remove-dir, which also clear the cache so changes take effect on the very next run.

Scanning skips everything hidden (.git, .cache, .npm, etc.) plus node_modules, dist, and build — so a broad root like runit --add-dir ~ stays fast.

Requirements

• Node.js ≥ 18
• No other runtime dependencies — the picker, banner, and preview are all implemented natively in JS (no fzf/gum/figlet system binaries required)

Uninstall

npm uninstall -g @mouhinou/runit-cli

This attempts to remove the shell hook automatically, but npm's uninstall lifecycle hooks aren't reliably run for global packages across every npm version — don't rely on it. If the block is still in your rc file afterward, it's inert and harmless; delete everything between # >>> runit shell hook >>> and # <<< runit shell hook <<< to remove it by hand.

License

MIT