Installation

Headless CLI and Terminal UI

Install the command-line tools with Homebrew on macOS:

brew install delaudio/tap/norn

The formula installs the norn CLI, the norn-tui terminal interface, and version-matched norn-review skill assets for Codex and Claude Code. It supports both Apple Silicon and Intel Macs without requiring Node.js, Rust, or a source checkout.

The CLI provides headless commands such as norn review; running norn without a subcommand opens the Terminal UI.

Machine setup

Inspect the proposed machine-level setup without changing anything:

norn setup --dry-run

Run the setup flow and then verify machine prerequisites:

norn setup --allow-provider-diff --yes
norn doctor --machine-only

Setup detects the installed Claude and Codex CLIs and available credential sources. The command above also persists consent for automated headless reviews to send only their selected diff and review instructions to the configured AI provider. Use norn setup --deny-provider-diff --yes if you prefer to authorize each explicit review with --allow-provider-diff instead. Setup stores only non-secret local preferences.

Configure provider credentials in the OS keychain from the terminal:

norn auth login github
norn auth login bitbucket --username <username>
norn auth status

Install the managed review skill for one or both supported coding agents:

norn skills install --agent all
norn skills status --agent all

Upgrade

Upgrade through the same Homebrew channel, then refresh managed skills so their content matches the installed Norn release:

brew update
brew upgrade norn
norn --version
norn skills status --agent all
norn skills install --agent all
norn skills status --agent all

brew upgrade updates the versioned skill assets packaged with Norn. It does not rewrite the copies in the personal Codex and Claude Code skill directories. Running norn skills install --agent all performs that managed, atomic upgrade. If status reports unmanaged, inspect the existing directory or symlink before using --force once to move it under Norn management.

Desktop app

The current stable release does not publish a desktop artifact or Homebrew cask. The desktop app provides the full visual workspace and can be run from source:

git clone https://github.com/delaudio/norn.git
cd norn
pnpm install
pnpm tauri dev

A locally installed source build can also be launched with norn-app.

Repository setup

Enter a Git repository and start the quick onboarding flow:

cd /path/to/repo
norn init --quick --repo-path . --yes

Norn stores review policies and settings in .norn.yaml. Check that the environment and configuration are ready:

norn doctor --repo-path .
norn config validate --repo-path .

First review

To review uncommitted changes:

norn review --repo-path . --scope working-tree --allow-provider-diff

To review the current branch against its destination branch:

norn review --repo-path . --scope branch --allow-provider-diff

The flag grants consent for one run. Omit it only after persisting consent with norn setup --allow-provider-diff --yes.

Terminal interface

Run norn without a subcommand to open the TUI in the current repository. You can also launch it explicitly:

norn-tui

Use workspace mode to choose a repository when you are not inside a supported checkout:

norn-tui --workspace