Introduction

    {\_/}  │
    (O,O)  │  "Round eyes.
    (:::)  │   Sharp placement."
    -^-^v--│
           └──────────────────────────────────────

Kural answers "where should this code live?"

It is a structural framework for TypeScript codebases built on four pillars. Embed places every type, function, file, and directory into vector space using facets engineered to carry structural information alongside meaning. Score measures how well the codebase is distributed in that space. Audit surfaces specific, actionable issues that cross-validate with scores. Place uses the well-distributed space to position new units and enable information retrieval.

        ┌─────────────────────┐
        │        PLACE        │  Roof: the payoff
        ├──────────┬──────────┤
        │  SCORE   │  AUDIT   │  Pillars: cross-validate each other
        ├──────────┴──────────┤
        │        EMBED        │  Foundation: everything rests on this
        └─────────────────────┘

Why this matters

AI agents now write code that compiles, passes tests, and looks reasonable. They are excellent at one-shotting — generating new code from scratch. But the moment a real codebase enters the picture, that competence falls apart. The function lands in utils/ when it belonged in core/. A new module reinvents an existing pattern. A description drifts toward a sibling's vocabulary. The code works. The codebase decays a little each time.

One-shotting and placing code into an existing codebase are not the same problem. Models have largely solved the first; the second remains open.

A discipline layer for codebases

Kural introduces structural discipline to a codebase — what TypeScript introduced for types. TypeScript didn't catch every bug; it gave the codebase a declarable, checkable layer of structure that humans and tools could rely on. Kural does the same for placement: every unit gets a vector identity, a set of structural scores, and a set of audits that surface drift. Agents and humans place new code against that map.

There will be a structure enforcer for codebases sooner or later, the way TypeScript became the type enforcer. We hope kural becomes that project.

Practical and cheap by design

Kural uses embedding models, not LLMs. Placement, similarity, and drift detection are vector problems — they don't need reasoning. An embedding pass over a 50k-LOC codebase costs under a dollar at hosted rates and zero with local models. The same workload routed through a frontier LLM would cost two-to-three orders of magnitude more and couldn't run on a laptop. Reasoning is reserved for your coding agent, where it actually buys you something. Kural is the structural layer underneath — fast, local-capable, and orders of magnitude cheaper.

Today kural targets TypeScript codebases. The structural concepts — fit, uniqueness, audits, placement — are language-agnostic; the ingestion pipeline is what's TypeScript-specific.

Start here

Deep dive

The four pillars in detail, plus the foundation they rest on and the codebase realities they accommodate.

Reference