Quick start

This guide takes you from a new installation to your first review with the headless CLI. You can switch to the Terminal UI or desktop app afterward without changing your repository configuration.

1. Install Norn

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

brew tap delaudio/tap
brew install norn

Confirm that the CLI is available:

norn --version

2. Prepare your machine

Run the setup flow and check the local prerequisites:

norn setup --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.

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.
• Install the desktop app 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.