Noah

A language-agnostic context engine for AI coding agents. Noah is the source of technical truth for a project: it generates deterministic scaffolding, auto-detects the tools the project actually uses, and compiles architecture rules into whatever format your agent reads.

npm i -g @sorodriguez/noah-cli

noah init --arch spring-hexagonal --ai cursor
noah g service PaymentService
noah inspect validate

Why

An agent editing your codebase does not know your architecture. Telling it in a prompt does not survive the next session. Noah writes the rules where the agent already looks — .cursor/rules/*.mdc, CLAUDE.md, .windsurf/rules/, .github/instructions/ — and gives it a command to check its own work against them.

❌ ARCHITECTURE VIOLATION DETECTED
File: src/main/java/com/app/controller/UserController.java
Issue: Direct import of 'java.sql.Connection' in Controller level.
Rule Reference: .cursor/rules/spring-hexagonal.mdc (Section 2.1)

Commands

| Command | What it does | |---|---| | noah init --arch <id> --ai <adapter> | Set the project up and write the rule files | | noah g <kind> <name> | Scaffold code and print the rules the AI must follow | | noah sync | Update the cached pack and recompile the context | | noah skill detect | Inject guides for the tools the project actually uses | | noah feature init <Name> | Create a design doc and wire it into the context | | noah inspect tree | A token-cheap summary of the module structure | | noah inspect validate | Check the code against the architecture rules | | noah pack validate | Validate a standards pack (used by pack authors' CI) |

Every command answers --help and -h, and noah help <command> works too. noah --help --json returns the entire command surface as data — an agent should not have to scrape a formatted page to learn what a flag accepts.

Noah also teaches agents to use itself: noah init always emits a noah-usage rule that explains the commands, the exit codes and where it is safe to write. Without it, an agent has the rules but not the command that checks them.

Design

• Zero runtime dependencies. The template engine, glob matcher, argument parser, prompts and schema validator are all written against Node's standard library. dependencies: {} is a CI gate.
• Deterministic. Same input, same bytes. localeCompare, toLocale*, Date.now, Math.random and process.exit are banned by a lint rule, and the acceptance suite runs under a Turkish locale and compares bytes.
• Idempotent. Re-running a command does not duplicate content and does not touch a file whose bytes have not changed.
• It will not eat your edits. Every generated file is hashed into .noah/lock.json. If you edit one by hand, Noah refuses to overwrite it and tells you so. Code inside noah:keep blocks survives regeneration.
• git is required. With no runtime dependencies there is no way to unpack a tarball, so git clone --depth 1 is the only fetch path.

Content lives in a separate repo

Architectures, patterns, skills and adapters ship in noah-standards. Adding a language is content, not code: the CLI has no per-language branches.

Point at your own fork with --pack:

noah init --pack [email protected]:acme/standards.git --ref v2.1.0 --arch acme-clean --ai cursor

Project state

.noah/config.json is authored — a human edits it. .noah/lock.json is derived but committed: it pins the exact pack commit so everyone on the team generates from byte-identical templates, and it is what makes noah sync --check meaningful in CI.

Development

npm install
npm run verify        # typecheck + determinism lint + build + size gate + tests
npm run bench         # start-up budget

Requires Node 24 or newer.