getting-started.md

Getting started

Install

Install from the official source repository:

cargo install --git https://github.com/code0xff/nightcrow --locked

After the first install, the no-argument updater uses the latest binary from the official GitHub Release. This keeps routine updates independent of the mutable development branches.

For a checkout you are developing locally:

cargo install --path . --locked

Rust 1.89 or newer is required. --locked uses the repository's committed Cargo.lock. The browser bundle is committed and embedded in the binary, so these commands do not require Node.js.

Create a commented configuration starter when needed:

nightcrow init

An existing ~/.nightcrow/config.toml is preserved; use nightcrow init --force only when you intend to replace it. See Configuration for the fields and defaults.

Run a session

# Start in the background if needed, then attach the TUI.
nightcrow attach

# Start in the foreground (Ctrl-C stops it).
nightcrow

# Start in the background and return to the shell.
nightcrow -d

There is one session per running daemon. nightcrow attach reuses an existing session and starts one in the background when none is available. The daemon owns the open repositories and terminal programs; clients only attach to it. Startup prints the browser URL and the attach-socket path. A background daemon writes its output to ~/.nightcrow/daemon.out.

Use --exec COMMAND once per startup pane when starting a daemon. Configured [[startup_command]] entries run first, followed by these CLI commands. The combined startup list is limited to 8 panes per project; each project gets its own list. With no startup commands, a project starts with no terminal process; press <prefix> t to open the first shell, or set [terminal] auto_open = true to open one automatically. All terminal panes in a project share an 8-pane limit; later panes are opened with <prefix> t until that limit is reached.

The browser and TUI share repositories, terminals, project order, active project, and accent. The TUI's leader is Ctrl+F by default; see Keyboard and mouse for all controls.

Detach and stop

<prefix> q leaves the TUI while the session and its panes continue running. Reattach with nightcrow attach. Stop the daemon and its terminal programs with:

nightcrow stop

If a client loses its connection, reattach after confirming that the daemon is still running; there is no automatic reconnect. nightcrow stop --socket PATH targets a non-default daemon socket.

Update

nightcrow update
nightcrow update --version 0.1.1

By default this downloads and verifies the latest binary from the official GitHub Release. Use --version VER to roll back to a published patch. Use --path DIR for a local checkout or --git URL for another source repository; those explicit development modes require Rust and run a locked, forced cargo install. Restart the session after updating so the daemon and its panes use the new binary. On Windows, update moves the installed executable aside before replacing it.

Building and testing

The Rust verification gates are:

cargo fmt --all --check
cargo build
cargo test
cargo clippy --all-targets --all-features -- -D warnings

Enable this checkout's hooks once with git config core.hooksPath .githooks. The pre-commit hook runs the format check; pre-push runs the CI-equivalent gates for the changes in the push range. See commit rules for commit-specific policy.

The viewer source requires Node.js 26 and installed dependencies:

npm --prefix viewer-ui ci
npm --prefix viewer-ui test
npm --prefix viewer-ui run build

The bundle in viewer-ui/dist/ is committed. A viewer change is complete only when the build succeeds and the generated dist diff is included when it changes. On Windows, run the Unix verification gate with:

docker compose run --rm unix-gate

The Docker PTY test can be timing-sensitive under load; rerun the failing test outside the container before treating that failure as a code regression.