navori AI harness
Deep dive

What navori delivers
under the hood.

navori isn't a generic scaffolder. It's an opinionated harness, built for code that already lives in production —with legacy dependencies and half-finished migrations, not lab repos—. It turns Claude Code into a team with non-negotiable standards, memory that persists, and one shared standard across all your repos. Here's why, layer by layer, it's a foundation worth building on.

New to terms like harness, skill, or SDD? Start with the quick glossary ↓

Before you start

Quick glossary

No jargon. Tap any term to see what it means in one sentence.

Harness

The 'harness' around the AI assistant: the rules, agents, and automations that make it work the way your team expects, not on a whim.

Agent / subagent

An assistant with a specific role (explore, write, review). The main agent splits work across specialized subagents.

Skill

A reusable guide for a concrete task ('how to create an endpoint', 'how to verify before calling something done'). The agent loads it when needed.

Hook

An automation that fires at a fixed moment —e.g. run the tests before every commit— so nobody has to remember.

Quality gate

The quality bar: the commands (lint, tests) that must pass to call a change done.

SDD

Spec-Driven Development: instead of rules living in someone's head, they're written and versioned next to the code, updated with one command.

Preset

A config bundle per stack type (Vite + React, NestJS, monorepo…). navori detects your stack and picks the right preset.

Engram

The persistent memory: it stores decisions and learnings so the assistant recalls them next session.

Managed block

A chunk of CLAUDE.md marked 'managed by navori': it updates itself without touching what you wrote around it.

legacyPaths

The folders of old code you flag so agents treat them carefully and don't impose new rules on them.

01 · Orchestration

A team of agents, not a single thread.

The main agent embodies the orchestrator —the center of gravity—. Instead of doing everything in one thread, it decomposes the task and splits it across subagents that work in parallel and return only their conclusion. Each has a strict role and the right model for it.

Tap a card to see what each role does ↓

Orchestrator

opus

The main agent embodies it, not a separate subagent — it's the session's center of gravity. It reads the ticket, decides how many subtasks to split into, launches the workers in parallel, and finally integrates their results into one coherent solution. It uses the most capable model (opus) because its job is to reason and decide, not read files.

Each role, its model — efficiency in time and tokens

haiku Publish

publisher

Fast and cheap for mechanical tasks.

sonnet Read, write & audit

scout · implementer · reviewer · auditor

Balance of quality and cost.

opus Decide

orchestrator

The muscle where judgment matters.

All configurable in config.models. You don't pay a premium model to read files: muscle where decisions happen, speed where you explore.

the orchestrator, on a complex task 
orchestrator › splits the ticket into 3 subtasks
  ├─ scout       → map the module        (own context · sonnet)
  ├─ scout       → how is it validated?  (own context · sonnet)
  └─ implementer → applies the change   → quality gate ✓  (sonnet)
       └─ reviewer → approves against CLAUDE.md          (sonnet)
orchestrator › synthesizes and delegates the commit → publisher  (haiku)
02 · The real terrain

Built for production, not for demos.

Almost every tool assumes a clean, greenfield repo. navori starts from a real team's reality: code already running in production, legacy dependencies, and half-done migrations. From init you pick the terrain, and that choice shapes how the agents work.

Project mode, right from init

You pick the terrain: greenfield (move fast), in production (guard regressions), or legacy migration (watch legacy↔new compatibility). The choice shapes how the agents work.

legacyPaths the agents respect

You flag the legacy folders and the orchestrator, implementer, and reviewer know it: different rules apply there, and they don't impose new conventions on code that isn't theirs to touch.

auditor before migrating

Facing a structural migration (legacy → new backend, monolith → microservices), the agent dissects root cause, affected areas, and compatibility before anyone writes code.

Migration-aware skills

verify-before-done, debug-failure, and review-diff catch the inconsistent states where legacy and new code coexist — the most expensive bug in a half-done migration.

navori init — project mode 
? What terrain are you on?
    greenfield   — new code, move fast
  › production   — in production, guard regressions
    migration    — legacy migration, watch
                   legacy↔new compatibility

→ legacyPaths: [ "src/old-api", "legacy/" ]
  the orchestrator, implementer, and reviewer
  treat those paths with different rules.
03 · Efficiency

Fewer tokens by design.

Orchestration isn't just about speed — it's context economy. The main thread stays clean because the heavy lifting happens in isolated windows —each with its own model— that return only what matters.

Isolated context per subagent

Each subagent runs in its own window and returns only the conclusion. The orchestrator's thread never fills with the dump of files it read.

One model per role

Each agent uses the right model: a light one to read and explore, the powerful one only to decide and review. You don't pay a premium model to read files.

Excerpt-level reads

Scout reads the relevant fragments, not whole files. It locates — it does not photocopy.

Skills on demand

The skill catalog is referenced by index; the heavy content loads only when the task calls for it.

Compact managed blocks

Canonical ordering sorts and dedupes the rules in CLAUDE.md. No pasted copies, no noise piling up session after session.

The contrast

without a harness

One thread reads whole files, piles everything into context, and drags it turn after turn until it saturates.

with navori

Subagents explore in parallel and return conclusions. The orchestrator reasons over summaries, not dumps. Engram keeps what must be remembered outside the context window.

04 · Memory

Engram: memory that persists.

An LLM's context is ephemeral: close the session and it's forgotten. Engram is the persistent memory navori enables by default. Decisions, root-caused bugs, and conventions get saved and recalled across sessions — and survive context compactions.

  • Survives session closes and context compactions.
  • mem_save stores decisions, root-caused bugs, and conventions; mem_search recalls them on startup.
  • The protocol is injected into the orchestrator: it saves proactively, without being asked.
  • Ships with navori by default (always-on). You never re-explain last week's context.
today's session · next week's session 
# today — after fixing a bug
mem_save "The 360 report breaks if languages[] is empty.
          Root cause: missing guard in report.py. Fix: default []."

# next week — new session, context at zero
mem_search "360 report languages"
→ recalls the decision, the root cause, and the fix.
  You don't re-explain it.
05 · Org scale

One workspace, all your repos.

When you run 15 repos, you don't want 15 standards. The workspace is a cross-repo layer: define your org's quality gate, branch base, and conventions once, and every repo inherits them. The team works the same way no matter which project they're in.

  • Cross-repo config in ~/.navori/workspaces/<org>.json, outside any single repo.
  • Org-wide defaults: quality gate, branch base, shared conventions.
  • Tickets as version-controlled files inside the workspace.
  • workspace render applies the standard to every registered repo in one pass.
the org standard, to every repo 
$ navori workspace init acme
$ navori workspace set-default acme \
    --branch-base main --commits conventional-es
$ navori workspace add-repo acme ./web-app
$ navori workspace add-repo acme ./api-core
  … 13 more repos

$ navori workspace render acme
✓ 15 repos rendered with the same standard
06 · Guardrails

Standards and gates that protect the work.

An agent with write access needs barriers. navori brings non-negotiable standards —simplicity, strict typing— and security and quality gates as part of the harness, not an optional extra. And it keeps them versioned alongside the rest of the config.

Simplicity > cleverness

The standard before writing a line: is it the simplest thing? readable in 6 months? does it keep the existing pattern? No clever solutions nobody understands later.

any forbidden

unknown + narrowing, explicit types. The only exception is a // justified any: <reason> — last resort, not a shortcut that turns into debt.

Semgrep · security gate

Static analysis of dangerous patterns, tied to the reviewer. Security issues get caught in review, not in production.

jscpd · duplication gate

Detects copy-paste code before it multiplies. Less surface to maintain, fewer places for a bug to hide.

Defensive hooks

guard-destructive intercepts dangerous commands; quality-gate runs lint + tests before every commit.

deny / ask permissions

Sensitive operations are blocked or require explicit confirmation. Defense in depth, not a single barrier.

07 · The difference

Why navori, and not a generic scaffolder.

There are many ways to give an AI assistant instructions. Few survive the second month, a real team, or a repo with history. This is what navori does that the alternatives don't — or don't do as polished.

It's not copy-pasting .claude/

A versioned source of truth and idempotent render. Copying folders between repos doesn't scale or survive an update; navori does.

It's not a static template

It detects your real stack —Mantine, Redux, NestJS, pnpm monorepo— and assembles the preset. The standards don't erode because they're versioned and update with one command.

Production and legacy, first-class

Most tools assume a clean repo. navori starts from reality: code that already runs, legacy dependencies, and half-done migrations.

Batteries included and wired

Persistent memory, security and duplication gates, multi-agent orchestration, and a cross-repo standard. All polished and connected, not a README with manual steps.

08 · For your team

Join a repo that already runs navori.

You commit the config once to each repo; the team just follows it. Nobody hand-rolls a harness or copies .claude/ between projects. These are the commands each person runs on the way in.

Have the prerequisites

Node.js 20+, Claude Code and —if the repo uses persistent memory— the engram binary. In step 3, doctor tells you exactly what's missing. 

node --version   # v20 or higher
# Claude Code installed on your machine

Clone and rebuild the harness

The repo already ships navori.config.json (the source of truth). A single command rebuilds every configured engine identically for the whole team. Idempotent: running it twice changes nothing. 

$ git clone <repo> && cd <repo>
$ npx navori render --apply

✓ configured engines rebuilt from the config

Verify with doctor

doctor confirms everything is up to date and, if a tool is missing (e.g. engram), hands you the exact install command. No guessing. 

$ npx navori doctor

◇ All good — nothing pending.
⇡ engram — missing from PATH:
   brew install gentleman-programming/tap/engram \
     && claude plugin install engram

Work as usual

Open Claude Code and you're set: same agents, same skills, same quality gate, same team memory. When someone updates the config, run sync to catch up without touching your code. 

# already productive with the team's harness

# when the repo config changes:
$ npx navori@latest sync

In short, for the team: clone → npx navori render --apply → npx navori doctor and start working with the same harness you use.

From theory to the repo, in a minute.

All of this materializes with a single adoption command. The rest is rendering whenever you change something.

See the Quickstart Command reference
Credits

Shoulders of giants.

navori wasn't born in a vacuum: it integrates excellent tools and synthesizes ideas from open projects and standards. Credit for each piece belongs to whoever built it.

Builds on

Ideas & standards

Projects that inspired it

navori took ideas from these projects; codegraph is also integrated as a plugin. Per-project notes live in docs/inspiration.md.

Built with clack citty zod Astro Tailwind CSS