Federico Del Gaudio
Norn docs Quick start Contents
Back to project
•
3 min read

Quick start

Table of Contents

This guide takes you from a new installation to your first review with the headless CLI. You can switch to the Terminal UI afterward without changing your repository configuration. The desktop app is currently available from source rather than the stable Homebrew channel.

1. Install Norn

On macOS, install the CLI and Terminal UI with Homebrew:

brew install delaudio/tap/norn

Confirm that the CLI is available:

norn --version

2. Prepare your machine

Store a provider credential in the OS keychain, then check local prerequisites:

norn auth login github
# Or: norn auth login bitbucket --username <username>
norn setup --allow-provider-diff --yes
norn doctor --machine-only

Norn can use Claude or Codex for AI-assisted reviews. Install and authenticate the provider CLI you want to use before continuing. Norn stores preferences locally and does not write provider credentials into your repository. --allow-provider-diff records your local choice to let automated reviews send their selected diff and review instructions to that provider. To approve each review separately, run setup without that option and add --allow-provider-diff only to the review command you authorize.

Install the version-matched review skill for your coding agents:

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

After a later brew upgrade norn, run norn skills install --agent all again. Homebrew updates the packaged skill assets; this command atomically refreshes the managed copies used by Codex and Claude Code.

3. Initialize a repository

Enter a Git repository and create its initial Norn configuration:

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

This creates .norn.yaml, where the repository can define review defaults, policies, profiles, and analyzers. Validate it with:

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

4. Run your first review

Make a local change, then review the working tree:

norn review --repo-path . --scope working-tree

To review committed branch changes against the destination branch instead:

norn review --repo-path . --scope branch

The result is printed as Markdown. Norn does not publish comments or modify your repository during a headless review.

5. Choose your next step

  • Open norn without a subcommand for the interactive Terminal UI.
  • Build the desktop app from source for a visual review workspace.
  • Use the headless CLI in scripts and CI.
  • Install the agent skill to add Norn to Codex or Claude Code workflows.
  • Read repository configuration to customize policies and review profiles.