norma: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Norma is a macOS-native AI assistant: a TypeScript/Bun daemon (norma-core) that runs the agent loop, plus a native Swift menu-bar app that gives it a face. They talk JSON-RPC 2.0 over NDJSON on a Unix socket (~/.norma/run/core.sock). The daemon is the single source of truth; every client (CLI, app) is a view over its event stream.

Commands

bun install                          # install everything (bun is the runtime; pnpm workspaces orchestrate)

# Tests
pnpm test                            # all workspaces, serially
cd packages/core && bun test         # one package
bun test path/to/file.test.ts        # one file (path substring match)
bun test -t "test name"              # one test by name

# Protocol codegen — REQUIRED after changing packages/protocol/src (events/methods)
pnpm protocol:generate               # regenerates JSON schema + Swift round-trip fixtures

# Workflows e2e — proves the sandboxed runtime on the REAL compiled artifact (dist/norma-core)
bun run verify:workflow

# Swift
cd apple/NormaProtocol && swift test # protocol mirror round-trip tests
cd apple/NormaKit && swift test      # daemon client library
cd apple/Norma && xcodegen generate && \
  xcodebuild -project Norma.xcodeproj -scheme Norma -destination 'platform=macOS' build

# Run the daemon + CLI in dev
cd packages/cli
bun src/main.ts daemon run           # headless daemon
bun src/main.ts -p "hello"           # one-shot prompt (separate terminal)
bun src/main.ts                      # interactive TUI (Ink)

# Dev profile: the Debug app is "Norma Dev" (com.norma.app.dev) on ~/.norma-dev, keychain
# com.norma.core.dev; the global `norma-dev` command (installed by the dev app's menu) is an
# env-setting bun wrapper. The distribution app owns `norma` (symlink installed from the app /
# brew) on ~/.norma, keychain com.norma.core. Explicit NORMA_HOME always wins over both defaults.
# TWO TRAPS: (1) plain `norma` is the DIST CLI — with a dead socket it AUTO-LAUNCHES the dist app
# (`open -g -b com.norma.app`), so never use it for dev/test work: use `norma-dev`, or a temp
# NORMA_HOME with a manually-spawned `daemon run`. (2) Debug builds do NOT embed norma-core —
# "Norma Dev" cannot self-spawn a daemon; start the dev daemon below FIRST or the orb shows
# disconnected.
NORMA_HOME=~/.norma-dev NORMA_PROFILE=dev bun src/main.ts daemon run   # dev daemon (or: norma-dev daemon run)
# THIRD TRAP (Winter Phase 8b, until 8d's bundle drop): every session runs as a spawned `winter` child, and
# a dev daemon resolves that binary from `settings.runtimes.winterExecutable` → `$NORMA_WINTER_EXECUTABLE` →
# `<dirname(execPath)>/winter` → `<NORMA_HOME>/runtimes/bin/winter` — a dev run has none of the last two, so
# build one (`bun run build:winter` → dist/winter, from the ../winter-agent-sdk checkout at the pinned tag)
# and point the daemon at it, or EVERY session.create/session.dispatch refuses typed (winter_executable_unavailable):
NORMA_WINTER_EXECUTABLE="$PWD/../../dist/winter" NORMA_HOME=~/.norma-dev NORMA_PROFILE=dev bun src/main.ts daemon run
# (or set `runtimes.winterExecutable` in ~/.norma-dev/settings.json). FIRST RUN AFTER A REBUILD: the ad-hoc-signed dist/winter
# reads Norma's Keychain items itself, so macOS shows ONE consent dialog per credential item — click "Always Allow" or the
# turn stalls until the CLI's 180 s watchdog aborts it. Credentials are JSON "material" records (`openai:default`,
# `codex-oauth:default`; see packages/core/src/auth/credential-material.ts) — the raw legacy records are migrated at boot.

# Versioning — never edit versions by hand; VERSION file (#.#.### format) is canonical
bun run version:bump                 # +0.0.001 (also --minor / --major)
bun run version:sync                 # restamp package.jsons/plists from VERSION

# Release (one command → signed, notarized, stapled zip+DMG+appcast+cask+gh release)
bun run scripts/release.ts --dry-run --no-bump   # full rehearsal, never publishes
bun run scripts/release.ts                       # real release (bumps version first)