Guides on nux

Monorepo Setup

Mon, 01 Jan 0001 00:00:00 +0000

In a monorepo you often want each tmux window to start in a different subdirectory while still belonging to one nux project. Use per-window root values: they are paths relative to the project root, so one config can place windows under apps/frontend, apps/backend, packages/shared, and so on.

Example: project “acme-mono”#

Assume the repo on disk is ~/code/acme-mono with sub-apps under apps/ and shared code under packages/. A single project config can set the session root to the monorepo root and give each window its own subdirectory.

Lifecycle Hooks

Mon, 01 Jan 0001 00:00:00 +0000

Project configs can define four hooks that run shell commands at well-defined points in the session lifecycle.

Hook	When it runs	Mechanism
`on_start`	After the session and first window are created, before remaining windows	`SendKeys` to the first pane
`on_stop`	When the session ends	tmux hook (`session-closed`)
`on_ready`	Once, at the end of the full session build	`SendKeys` to the first pane
`on_detach`	Each time a client detaches from the session	tmux hook (`client-detached`)

`on_start`#

Runs once after the session and its first window are created. Commands are sent as keystrokes to the first pane of the first window. Use it for one-time setup like starting background services.

Pattern Matching

Mon, 01 Jan 0001 00:00:00 +0000

Many nux commands accept a project pattern instead of an exact name. The special character + means “zero or more characters” and can appear anywhere in the pattern.

Where `+` can appear#

Suffix: web+ matches names starting with web (e.g. web-app, web-admin)
Prefix: +wiki matches names ending with wiki (e.g. dev-wiki, team-wiki)
Infix: +api+ matches any name containing api (e.g. my-api-server)
Multiple: w+a+ matches names starting with w that also contain a

Internally, each + is translated to .* and the pattern is anchored as ^...$, so it must match the full project name.

Selective Windows

Mon, 01 Jan 0001 00:00:00 +0000

You can target individual windows with the :window suffix on the project name, optionally with multiple windows separated by commas. Window names match the name field under windows in your project config.

Syntax#

nux project:window
nux project:window1,window2,...
nux restart project:window
nux restart project:window1,window2,...

Starting a subset (root command)#

nux myapp:editor
nux myapp:editor,server

Creates the session with only the listed windows, in the order you list (not necessarily YAML order). Session-level options (env, on_start, on_ready, hooks) still apply; on_start and on_ready run against the first window in your list as the anchor.

Zoxide Integration

Mon, 01 Jan 0001 00:00:00 +0000

zoxide tracks directories you visit frequently. When zoxide integration is enabled, nux can resolve a project by name even when there is no matching config file, by running zoxide query <name> as a fallback.

Behavior#

If you have visited a directory before, nux my-obscure-project can succeed when that name resolves via zoxide - even without a config file at ~/.config/nux/projects/my-obscure-project.yaml.

When a project resolves through zoxide, no project config is loaded. The session is built using the default_session template (if configured) or as a bare session with a single window.

Interactive Picker

Mon, 01 Jan 0001 00:00:00 +0000

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:

Tool Sessions

Mon, 01 Jan 0001 00:00:00 +0000

Tool sessions are nux projects that exist mainly to launch a single utility (database TUI, log tailer, container dashboard, and so on). They are not special-cased in nux: they are normal project configs that often define one window and sometimes omit a meaningful repo layout.

Typical shape#

root can be omitted or set to any directory (home, a log path, a repo, or /tmp).
For a single command and one pane, use one window with a single panes entry.

Example configs#

Database client (single TUI)

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Common issues and how to resolve them.

“nux: unknown command” or “command not found”#

The nux binary is not on your PATH. Verify the install:

which nux
nux version

If you installed via go install, make sure $(go env GOPATH)/bin is in your PATH. If you installed via Homebrew, run brew link nux.

“cannot start session from inside tmux”#

nux refuses to start new sessions from inside an existing tmux session to prevent nested session confusion. Options:

GitHub repository setup

Mon, 01 Jan 0001 00:00:00 +0000

This page documents maintainer-facing GitHub settings for nux. Most files live in the repo (templates, Dependabot, workflows); a few settings are only in the GitHub UI or API.

Files in the repo#

Item	Location
Security policy	SECURITY.md
Code of Conduct	CODE_OF_CONDUCT.md
Support / where to ask	SUPPORT.md
Issue forms	.github/ISSUE_TEMPLATE/
PR template	.github/PULL_REQUEST_TEMPLATE.md
Dependabot	.github/dependabot.yml
Sponsor button	.github/FUNDING.yml
Stale issues (optional)	.github/workflows/stale.yml

Settings applied via GitHub API#

These can be configured with gh (see project history). To reproduce or audit:

Guides on nux

Monorepo Setup

Example: project “acme-mono”#

Lifecycle Hooks

on_start#

Pattern Matching

Where + can appear#

Selective Windows

Syntax#

Starting a subset (root command)#

Zoxide Integration

Behavior#

Interactive Picker

What the picker shows#

Tool Sessions

Typical shape#

Example configs#

Troubleshooting

“nux: unknown command” or “command not found”#

“cannot start session from inside tmux”#

GitHub repository setup

Files in the repo#

Settings applied via GitHub API#

`on_start`#

Where `+` can appear#