agent tokens to green (OSS historical-bug slice) source
Cost, measured
Shorter repair loops, cheaper payloads
Variables show up close to runtime and violations carry actual / expected / actions — so agents detect earlier and iterate less. Numbers are in-repo baselines (OSS slice + micro probes), not a closed benchmark.
gate rounds on the documented fix path source
median single-file analyze (vs tsc.LS in micro probe) source
TS “cheap” tokens are often silent green. Nudo pays tokens to report. Method and bounds →
Beyond declared types
Values TypeScript widens away
Nudo evaluates on Abs, so results track actual computation — literal strings, splits, loop sums — not a declared upper bound.
"0x" + idstring`0x${string}`"hello".slice(1, 3)string"el""a,b,c".split(",")string[]["a", "b", "c"]for (let i = 0; i < 5; i++) sum += inumber10The template `SAVE-${code.toUpperCase()}` is not plain string — when the call site is coupon("vip"), Nudo observes "SAVE-VIP".
Real code, real results
Call sites become signatures
Observation check prints unconstrained params as any. Point Nudo at real usage — tests, call sites — and the interpreter synthesizes precise signatures from evidence. No type annotations. No library rewrite.
What call-site discovery returns
couponfrom cart.js call siteno call-site evidence → any("vip") => "SAVE-VIP"deepEqualfrom @hapi/hoek usageno call-site evidence → any({a:1,b:{c:2}}, {a:1,b:{c:2}}) => booleanflattenfrom recursive + loop usageno call-site evidence → any([1,[2,[3,4]]]) => [1,2,3,4]Product path
Observation → Contracts → leave tsc
Observation: `nudo check` prints signatures and diagnoses entry may-throw. Contracts: sidecar contracts turn call-site facts into L1 obligations. Ecosystem: `export` projects artifacts from Abs. Exit: `migrate retire` — coexistence is not the end state.
- ObservationObserve + gate
npx nudojs check src/ - ContractsAdd contracts
lib.nudo.js · @nudo:contract · nudo check - EcosystemProject artifacts
npx nudojs export src/ --format dts|schema - ExitRetire tsc
npx nudojs migrate status|strip|verify|retire
Write logic, then generate contracts
Call sites are evidence. `contract --draft` can generate a reviewable contract draft; accept into `*.nudo.js`. Drafts never become check obligations by themselves.
npx nudojs contract --draft lib.js --from test/Write contracts, then guide / constrain logic
Write `*.nudo.js` or `@nudo:contract` first. The same contract face guides implementation and constrains logic in `check`.
npx nudojs check src/Validate vs. project
The flow is centered on the Abs contract face. `check` only validates. `export` projects `.d.ts` / Zod / Standard Schema / guards from Abs; IDE and agents read Abs directly.
nudo check
Validation / CI only. Does not generate artifacts.
export · dts
`.d.ts` for TypeScript consumers. Lossy projection.
export · Zod / guards
Runtime validators from Abs. Not a substitute for `check`.
export · Standard Schema
Standard Schema validators for runtime checks and downstream tooling.
IDE / LSP
Hover / inlay read Abs directly.
Agent / MCP
Coding agents read the same Abs via LSP / MCP — see the AI agents section.
Start by role
Pick your entry path
The docs are organized by audience. Choose the path that matches your situation — every card lands on a runnable first step.
Type / CI gate on real JS
Mental model, then a runnable check on your own files — signatures even when the gate is green.
Quick StartTypeScript userSee the difference, then leave tsc
Honest comparison, migration path, and a one-way retire gate — coexistence is not the end state.
Nudo vs TypeScriptExisting JS packageContracts from real usage
Point Nudo at tests and call sites. Draft contracts from evidence; accept only what you mean.
Logic-first guideCI / platformStable gates and diagnostics
Recipes for `nudo check` in CI, machine-readable reports, and the diagnostics glossary.
RecipesAI coding agentSame Abs face via LSP / MCP
Agents run `nudo check`, respect sidecar contracts, and parse stable diagnostic IDs.
Agent docsAI agents
Agents that gate contracts — not invent types
Coding agents and editors read the same Abs face via LSP / MCP. They run `nudo check`, respect sidecar contracts, and parse stable diagnostic IDs — not a second type language.
Same Abs as the IDE
Hover / inlay and agent tools consume Abs directly. `export` projections stay lossy; Abs remains the source of truth.
npx nudojs check src/ --jsonLSP + MCP surface
`@nudojs/lsp` exposes agent `executeCommand` tools. Wire MCP for Cursor, Claude Code, and other agent clients without a separate server protocol.
@nudojs/lsp · nudo.contract · nudo.whatIfStable product rules
Agents must not invent body-AST obligations or treat `@nudo:case` as contracts. Entry `any` ≠ `unknown`. Observation is `check`; Contracts is `contract` + `check`.
actual ⊭ expected · nudo:constraint-violatedAgent entrypoint
Publish `agents.md` + `llms.txt` so coding agents can set up Nudo without guessing product nouns. Paste the setup block into your agent and go.
nudojs.github.io/nudo/agents.mdRead https://nudojs.github.io/nudo/docs/reference/agents
Primary gate: npx nudojs check <path>
Contracts are *.nudo.js / @nudo:contract
Do not invent body-AST obligations. @nudo:case is debug-only.
Entry params print as any; unknown = inference failed.Ready to come back to JS?
Observe intermediates in the browser, gate contracts on your own files with the CLI, or point a coding agent at the same Abs face. Your JS stays JS.
npx nudojs check ./pricing.js