norn-cli 0.7.3

Norn: a provider-neutral multi-agent development harness

Norn

Provider-neutral multi-agent development harness for local subscription CLIs. The name evokes the Norns who shape fate: the harness coordinates independent agents toward a bounded outcome.

Status: beta. The norn-cli distribution is published to PyPI; the source repository remains private during the beta period.

Norn provides configuration, CLI, run-state, event journal, recovery, human-readable escalation reports, provider-neutral adapters, and an executable multi-role delivery pipeline for Codex, Claude Code, Grok Build, and future command-based subscription CLIs.

norn init
norn --version
norn doctor
norn validate-config
norn providers
norn plan "add an audit log"
norn run "add an audit log"

Install the bundled explicit-invocation skill for both Codex and Claude Code:

norn install-skill --target all --scope project --project /path/to/repository

This writes .agents/skills/norn for Codex and .claude/skills/norn for Claude Code. Use $norn in Codex or /norn in Claude Code. Install a single user-level copy with --target codex|claude --scope user; use --force only to replace an existing copy intentionally. Loading the skill never starts a model-consuming lifecycle unless the user explicitly requests plan or run.

See Installation for isolated uv tool, pipx, and virtual-environment installs from PyPI.

plan runs orchestration, planning, and plan review. run continues through implementation, language-aware local tests/lint, the four tester roles, triage, and final gate. UI changes require an independent E2E result from every tester. Each required E2E result must include the executed argv, exit code, a concise result summary, and at least one non-empty artifact created in that tester's assigned evidence directory. The harness rejects missing, stale, symlinked, or out-of-directory evidence and archives accepted files under .norf/runs/<run-id>/artifacts/e2e/.

To implement a previously approved plan without invoking orchestration, planning, or plan review again, pass the successful plan run ID with the identical request:

norn plan "add an audit log"
norn run "add an audit log" --from-plan <plan-run-id>

Norn verifies the source run mode and status, project root, request text, and saved artifact schemas before creating the implementation worktree.

For Codex tester roles, the adapter keeps workspace-write filesystem isolation and enables command networking through a loopback-only proxy allowlist (localhost and 127.0.0.1). Planning and implementation roles retain their normal network-off policy.

Profiles keep a stable logical model name while optionally mapping it to a provider-specific identifier. For example, Codex Sol is configured as:

candidates:
  - provider: codex-cli
    model: sol
    model_id: gpt-5.6-sol
    effort: high

Round limits are configured under limits or overridden per invocation:

norn run "task" --max-rounds 5 --max-total-rounds 12 \
  --max-planner-retries 2 --max-final-replans 2

Known Python, Node, Rust, and Go gates are auto-detected. Projects can define additional commands as shell-free argv lists:

gates:
  enabled: true
  auto_detect: true
  commands:
    - name: integration
      kind: test
      command: [python3, -m, pytest, tests/integration]

Each run records role responses, model selections, attempts, findings, test results, and round history below .norf/runs/<run-id>/. Any non-successful stop also produces escalation-report.md and escalation.json for human judgment.

By default, run requires a clean Git repository and implements inside a detached .norf/worktrees/<run-id>/ worktree. Set git.worktree: false only when direct changes to the selected project directory are intentional.

Development and packaging

Install the local development tools and run the same checks as CI:

python3 -m pip install --editable ".[dev]"
ruff format --check .
ruff check .
python3 -m unittest discover -v
python3 -m build
python3 scripts/package_smoke.py dist/norn_cli-0.7.3-py3-none-any.whl

CI runs the quality suite on Python 3.12, 3.13, and 3.14, then installs the built wheel in a clean virtual environment and verifies both Codex and Claude skill copies. It uploads the distributions as a short-lived workflow artifact. Publishing a GitHub Release runs the same deterministic gates before sending the verified artifact to PyPI through OIDC Trusted Publishing; neither workflow invokes subscription models.

Release acceptance is intentionally split in two: CI performs deterministic package checks, while local acceptance invokes the authenticated subscription CLIs. Follow Release acceptance before promoting a release. See CHANGELOG for version history and Security for private vulnerability reporting.

The canonical command is norn. The legacy norf-harness executable remains an alias during the pre-1.0 migration; new automation should use norn.

License

Copyright 2026 uruca-kk. Licensed under the Apache License 2.0.