Norn

Norn is an open-source, local-first workspace for reviewing Pull Requests on Bitbucket Cloud and GitHub. It keeps sensitive credentials out of the webview, keeps review context local, and gives reviewers a structured path from prompt to published comments. It is available as both a GUI desktop app and a terminal UI.

Table of Contents

• What Is Norn
• Quickstart
• Documentation
• Agent skills
• CLI, App and TUI
• Development
• Architecture
• Configuration
• Roadmap
• Contributing
• Security
• License

What Is Norn

Norn is a local review surface around your provider-hosted PRs. It does not replace Bitbucket or GitHub; it adds an explicit review workflow that is controlled by the reviewer.

It brings together:

• unified PR browsing across Bitbucket and GitHub;
• a diff-first desktop interface (unified + split views, image previews);
• an OpenTUI terminal workspace over a local Rust backend (norn-backend);
• reviewer-owned draft comments and publish controls;
• AI-assist runs (Claude, Codex, or OpenCode/DeepSeek) with local persistence;
• local clone operations for branch sync, fixing, commit, and push flows;
• local review artifacts (runs, findings, evidence, publication state);
• closed-PR analytics and review quality signals.

The same local review contracts and metadata are designed to be usable in desktop and headless paths, not as ad-hoc one-off scripts.

Quickstart

Install Norn

By default, install with Homebrew:

brew tap delaudio/tap
brew install norn
norn auth status
norn skills install --agent all
norn setup --allow-provider-diff --yes

When a release includes the signed and notarized desktop channel, install it alongside the command tools with:

brew install --cask norn

Or run from source with your preferred package runner.

5-minute local onboarding

From a repository you own, run:

cd /path/to/repo
norn init --quick --repo-path . --yes
norn doctor --repo-path .
norn config validate --repo-path .

Then start a review:

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

Norn expects repository policy and review defaults in .norn.yaml. Compatibility files are still read during migration only (.lachesi.yaml, .lachesi/), with .norn.yaml and .norn/ taking precedence.

Develop or install the terminal workspace

Install Rust, pnpm and Bun 1.3.8, then:

pnpm install
cd ui && bun install --frozen-lockfile && cd ..
pnpm run dev

dev builds the Rust backend and browser diff, then opens OpenTUI for the current repository. pnpm run build creates release Rust commands, a standalone OpenTUI executable and the browser assets used by g → b.

pnpm run install:local
# Default destination: ~/.local/bin (override with NORN_INSTALL_PREFIX)
norn

The installed commands include norn, norn-tui, norn-backend, norn-ui and compatibility aliases. The compiled client needs no external Bun runtime. Keep the binaries together and browser assets under share/norn/browser-diff. Noninteractive norn, norn --help, norn --version and CLI subcommands stay Rust-only. A bare Cargo build intentionally does not compile or install the UI; use the complete build/install commands above for interactive use.

Tauri and Ratatui are temporarily retained as optional legacy adapters. pnpm run legacy:desktop:build, pnpm tauri dev --features desktop-bundle and pnpm run legacy:tui are explicit opt-ins. Their CI runs separately; ordinary builds never enable custom-protocol or require desktop libraries.

Documentation

Most workflows are documented in-repo:

• Self-hosting guide: shared review topology and operations.
• Homebrew distribution and release runbook: install, upgrade, rollback guidance.
• Review evaluation: closed-PR quality gate and score.
• Dogfooding private policy packs: exercise external or private packs locally without leaking client context.
• Native capability ownership: current Tauri permissions, owners, and the checklist for adding more.
• Architecture and migration specs: policy engine, findings schema, repository config, publication model.

Additional product references are also available:

• SECURITY.md: safe handling of secrets and local data.
• LICENSE: license terms.

For API consumers and AI-assisted flows, the local configuration is the source of truth: keep local config files in the repository and review commands explicit.

Agent skills

Norn ships a managed norn-review skill for Codex and Claude Code. It runs the headless CLI as an independent review gate after implementation work and before a push. A Homebrew installation needs no source checkout:

norn skills install --agent codex
norn skills install --agent claude
# Or install both:
norn skills install --agent all

Inspect, upgrade, or remove only Norn-managed copies with:

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

Unmanaged destination content is preserved unless install receives an explicit --force.

Invoke it explicitly with $norn-review in Codex or /norn-review in Claude Code. Both agents can also select it automatically when its description matches the current task. An explicit invocation authorizes only that command's selected diff; automatic review uses the locally persisted choice. Codex and Claude Code still ask for their own narrowly scoped permission to run norn review outside the agent sandbox. Norn never edits either agent's permission settings.

CLI and terminal workspace

The ordinary command distribution uses OpenTUI:

• norn: Rust review/repository CLI; no arguments on a terminal opens OpenTUI, while redirected invocation prints help.
• norn-tui: terminal interface for PR browsing and review actions.
• norn-app: optional legacy desktop launcher, excluded from ordinary installation.

Build and install the canonical CLI from source:

make install-local
norn --version
norn-tui --version
norn-backend --version

This installs durable executable files under ~/.local/bin; it does not link back into target/release. Set NORN_INSTALL_PREFIX=/absolute/prefix to use a different <prefix>/bin. The CLI/TUI convenience recipes install the same complete runtime:

make cli-install
make tui-build
make tui-install

See local source installation for atomic replacement behavior, command selection, compatibility aliases, and how to distinguish this path from a Homebrew-managed installation.

norn-tui runs inside a local Git repo and resolves GitHub/Bitbucket from the configured remote.

norn-tui --workspace

norn-tui --workspace opens repository picker mode when the current directory is not a Git checkout with a supported remote.

Press s in the TUI to open Settings as a bounded overlay on the review workspace. AI review options, provider credentials, and CLI readiness have separate sections with contextual actions. Select GitHub or Bitbucket and press Enter to start a labelled credential flow; pasted and typed tokens remain masked and are stored in the OS keychain. Bitbucket guides you through username and token steps, and Esc returns to the previous step. The footer keeps s settings visible on both compact and wide terminals.

Configure keychain credentials without opening the desktop app:

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

Interactive token input is masked. Scripts may pipe a token to norn auth login <provider> --token-stdin; tokens are never accepted as command arguments. Terminal/headless usage can alternatively resolve environment variables referenced in ~/.config/norn/config.toml, for example:

[credentials.github]
token_env = "GITHUB_TOKEN"

[credentials.bitbucket]
username_env = "BITBUCKET_USERNAME"
token_env = "BITBUCKET_TOKEN"

Keep real secrets in environment or keychain only.

Development

Run the core quality gates before submitting a change:

pnpm install
pnpm run typecheck
pnpm run test
pnpm run test:rust:core
pnpm run ui:typecheck
pnpm run ui:test
pnpm run ui:frames:check
pnpm run lint
pnpm run build

Additional scripts are available for docs and design system publishing:

pnpm run storybook
pnpm run storybook:build
pnpm run storybook:deploy
pnpm run docs:dev
pnpm run docs:build
pnpm run docs:deploy

The optional legacy browser mock layer remains available with pnpm run legacy:web:dev; desktop adapter tests use pnpm run test:tauri.

Architecture

Norn uses an OpenTUI React client and Rust stdio backend:

• Frontend: OpenTUI, React and TypeScript; Vite builds the browser diff.
• Backend: Rust engine and versioned JSON messages over stdin/stdout.
• Providers: Bitbucket Cloud and GitHub are handled server-side in Rust.
• State: transient React presentation state and Rust-owned persistence.
• Storage: settings and credentials are handled separately; review state is persisted locally in SQLite.

Important architectural boundaries:

• Credentials are not injected into web content.
• All provider interactions happen in Rust command handlers.
• src/lib/tauri.ts is the single frontend IPC boundary.
• Mock handlers in src/mock-tauri/ keep browser, Storybook and test flows functional without a real provider backend.

Configuration

Project-level app settings include:

• selected providers and repositories;
• local clone integration (branch/sync/fix/commit/push);
• default diff mode and AI runtime mode;
• optional Jira/Notion integration for context.

Per-repository review control is in .norn.yaml, with the current contract including review mode, prompt extension, finding thresholds, rule list and local analyzers.

Example:

version: "0.1"
review:
  mode: balanced
  prompt:
    extend: "Prioritize migration safety and public API usage changes."
  findings:
    minSeverity: low
    requireAnchors: false
paths:
  include:
    - "src/**"
  exclude:
    - "dist/**"

Roadmap

Current focus:

• solidify .norn.yaml policy semantics and evidence pipeline;
• expand policy packs and named review profiles;
• harden headless norn review for local and CI;
• improve provider abstraction and report/export quality;
• continue the review engine migration with structured contracts.

Public planning artifacts remain in GitHub issues and the project’s roadmap flow.

Contributing

We follow lightweight contribution flow:

• open an issue or discussion before large architectural changes;
• keep PRs focused and testable;
• include commands run and scope in the PR description;
• align with the existing ADR and docs-led conventions in this repository.

Before opening a PR, please:

• use GitHub issues for context and discussion;
• keep the change focused and testable;
• include the exact commands you ran in the PR description.

AI-assisted changes are accepted when they are reviewable and scoped to the problem they solve.

Security

Security is mostly about secrets hygiene:

• do not commit tokens;
• do not paste production secrets in PR descriptions, screenshots, or fixtures;
• run with provider tokens in environment/OS store when possible.

For security concerns, use SECURITY.md procedures.

License

Norn is released under the license in LICENSE.