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
        └─────────────────────┘

How well we embed, score, audit, and place is what gives meaning to Kural.

Getting Started

Install Kural, configure an embedding provider, and run your first structural analysis in minutes.

Configuration

Domain keywords, dictionary, sensitivity — the settings that shape embedding and audit behavior after setup.

AI Code Editors

A must-have for agentic coding. Give your AI assistant structural awareness so it writes code in the right place. Supports 18 editors.

Architecture

System overview: the pipeline, tiers, data model, and sync design.

Foundation

Embedding

Every unit becomes a vector. Facets capture name, description, and structural shape. Signals anchor them in filesystem context.

Pillars

Scoring

Three perspectives on structural health: fit (does it belong here?), uniqueness (how distinct from siblings?), and subtree health (is everything below organized?).

Util Scoring

Real codebases organize by domain and capability. These are two axes that must not mix — each capability container gets its own scoring space.

Audits

15 statistical checks surface specific, actionable issues. Score and Audit cross-validate — fixing audit findings should improve scores.

Codebase Realities

Kural Params

The vector space can't naturally represent every codebase reality. Kural Params declare constraints — utilities, patterns, bound nodes, residuals — so the four pillars can adjust.

Pattern Nodes

When multiple siblings are structural repetitions of one concept, they're collapsed into a single representative.

Bound Nodes

When a unit's identity is inseparable from its context (barrel exports, entry points, primary exports), the system adjusts rather than flagging architecture as a flaw.

Infrastructure

Database

SQLite snapshot persistence, schema, lifecycle, and caching.