When you run nux with no arguments from a directory that is not tied to a project, nux can open an interactive fuzzy finder instead of printing help.

What the picker shows#

The picker combines three sources into a single sorted list:

• Configured projects (files in ~/.config/nux/projects/)
• Directories under each project_dirs entry (top-level only, hidden directories excluded)
• Running tmux sessions not covered by the above

Projects that have a config file are marked with a * suffix so you can tell at a glance which entries have custom configs and which use the default session template:

  api *
  blog *
  dotfiles
  notes
  scratch

Entries are deduplicated by normalized session name (the same rules as tmux session names: dots and spaces become underscores, and so on). If a config file is named my.project.yaml and a session is already running as my_project, you see one row.

Pick an entry to start or attach to it as usual.

Backends#

Set the backend in global config:

picker: fzf   # or gum

Enabling the picker#

The picker only activates when both conditions are met:

1. picker_on_bare: true is set in global config
2. You run bare nux (no subcommand, no project name) from outside a recognized project directory

picker_on_bare: true

If picker_on_bare is false (the default), running bare nux outside a project directory prints the help text instead.

Auto-detect behavior#

Before the picker activates, nux checks whether your current working directory is inside any configured project_dirs directory. If it is, nux auto-detects the project name from the directory and starts or attaches to that session directly - the picker is skipped entirely.

For example, if project_dirs includes ~/projects and you run nux from ~/projects/blog, nux starts the blog session without showing the picker.

When to use the picker#

The picker is most useful when you work across many repos and want muscle-memory nux from any directory. Combined with picker_on_bare: true, a bare nux invocation always gets you to a session quickly.