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);
• both interfaces: a Tauri desktop app and a terminal user interface (norn-tui);
• reviewer-owned draft comments and publish controls;
• AI-assist runs (Claude or Codex) 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.

Run GUI App (Tauri)

pnpm install
pnpm tauri dev --features desktop-bundle

This starts the full GUI desktop app with Tauri IPC wired end-to-end.

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.
• 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, App and TUI

Norn ships both a desktop app and terminal interfaces:

• norn: review/repository CLI when subcommands are passed; no subcommand opens norn-tui by default.
• norn-tui: terminal interface for PR browsing and review actions.
• norn-app: launches the desktop GUI (norn/Tauri app).

Build and install the canonical CLI from source:

make install-local
norn --version
norn-tui --version
norn-app --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. Component-specific installs remain available:

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:tauri
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

Local-only development can use the browser mock layer (for UI and review flow experiments) with pnpm dev.

Architecture

Norn is split into a React frontend and Rust/Tauri backend:

• Frontend: React 19, TypeScript, Vite, Tailwind.
• Backend: Tauri v2 with Rust commands over IPC.
• Providers: Bitbucket Cloud and GitHub are handled server-side in Rust.
• State: local React/Tauri state and local persistence for review models.
• 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.