Kalyth

Kalyth keeps a persistent, evidence-backed engineering model of a project. The model holds typed components, data, interfaces, constraints, decisions and alternatives. Each one is linked to the source evidence it rests on and to the revision in which it became true. People and coding agents (Claude Code, Codex and other MCP clients) read the same model and propose changes to it. People decide.

It is built for the Nebius x NVIDIA Global AI Hackathon (October 2026) and meant to outlive it.

Status

Phase 1. What exists and is tested today, in CI on Linux and Windows: 352 unit and integration tests, and 36 browser tests of the main flows by keyboard, with automated accessibility checks:

• Semantic kernel.

  • Typed objects and relations, with a registry of allowed endpoints and impact rules.

  • Claims with an explicit basis: observed, inferred, stated or imported.

  • Evidence pinned to a commit, git blob and line span.

  • Proposals validated against a base revision.

  • Authorised commits that produce immutable revisions and replayable events, and historical reads at any revision.

• Concurrency and integrity.

  • Stale proposals are refused with the references that changed. Unrelated ones rebase automatically, and each rebase re-checks cross-object invariants at the head.

  • One SQLite transaction per commit. The database enforces append-only events, and a replay test proves the event log reproduces the stored state.

• Repository analyser. Static tree-sitter analysis of Python and TypeScript repositories into observed facts with pinned evidence. It finds modules, imports, libraries, FastAPI routes and SQLModel tables. Nothing from the analysed repository is executed. When the repository advances, re-observed facts are refreshed, and vanished ones are reported stale for review, along with anything derived from them.

• Impact traversal. From any elements, it finds the elements a change may affect, each with a typed path, following each relation type's declared impact rule.

• Navigator.

  • Grounded summaries of an element.

  • Alternatives for a change request, with the elements each one changes directly.

  • Exploring a decision again with hybrids of earlier alternatives, and answers to its open questions.

  Every citation is checked against the pinned source text, and an item with a fabricated citation is rejected. Everything becomes a proposal for a person to review. Model calls go through one gateway with consent and a persistent spend cap.

• Decisions. The workbench compares a decision's alternatives side by side: what each changes, what that reaches, and the open questions. A person accepts one.

• Context packages and agent handoff. For an accepted decision or chosen elements, Kalyth builds a deterministic, content-addressed package pinned to one revision.

  • Its mandatory part is never truncated: invariants, constraints, accepted decisions, acceptance criteria and agent policy.

  • Optional items are ranked by typed distance, with an explicit list of what was left out.

• Tasks and execution reports. Coding agents claim tasks with an expiring lease and submit execution reports. Kalyth checks each report against git: the commit exists, it carries the task's trailer, it changes exactly the reported files, and it descends from the task's base. Tests are the agent's own claim; Kalyth does not run them. A person completes the task.

• Workbench UI. Overview, Graph, Records, Proposals, History, Navigator, Handoff, Tasks (board or dependency graph) and Decisions views, with an inspector. Claim basis and freshness show on every node and edge. Light and dark themes, and keyboard shortcuts, listed under the keyboard button in the header.

• Export and import. A project's whole history, as one file that rebuilds the same state.

Real NVIDIA Nemotron inference through Nebius Token Factory has been tested in a keyed spike under a 0.25 USD cap. After a prompt fix, 37 of 52 citations matched their source exactly; the rest differed only in quote style or layout. See docs/feedback/nebius-nvidia.md and ADR 0017.

The hosted demo mode is built and tested (pnpm demo:serve, ADR 0019). It gives each visitor their own copy of the analysed FastAPI template, recorded Nemotron runs and a capped allowance of live ones. It is not deployed yet.

Not done yet:

• the evaluation run against frozen ground truth (docs/evaluation);

• the hosted demo's deployment (deploy/README.md).

This README will say when each one works.

Related MCP server: project-surface

Requirements

• Node 24, 25 or 26. Node runs the TypeScript sources directly, so the server needs no build step.

• pnpm 11.

• git on the PATH. The analyser reads repositories with git.

Quick start

pnpm install
pnpm check          # lint, typecheck, tests
pnpm build          # build the workbench UI
pnpm test:e2e       # optional: browser tests and accessibility checks (needs Chrome)
pnpm dev:seed       # optional: a small sample project
pnpm dev:server     # API and UI on 127.0.0.1:4317

Open the kalyth ui: http://127.0.0.1:4317/#token=... link that the server prints. The token changes on every launch. If a tab shows "Session expired", open the new link in it.

Every root script runs from the repository root, so they all share .kalyth/kalyth.db there. Set KALYTH_DB to use another file. In bash: KALYTH_DB=.kalyth/demo.db pnpm dev:server. In PowerShell: $env:KALYTH_DB = ".kalyth/demo.db"; pnpm dev:server.

pnpm dev:web runs the UI with hot reload; see apps/web/README.md.

Analyse a repository

Kalyth clones the repository bare, over HTTPS, into .kalyth/repos. It never executes it.

pnpm ingest --repo https://github.com/fastapi/full-stack-fastapi-template --ref 0.12.0
pnpm ingest --repo https://github.com/fastapi/full-stack-fastapi-template --ref b1125d8839482cb7bbae603ddc6d0081bf87532e

The second run advances the project's source snapshot. Claims whose evidence changed are refreshed or reported stale (GET /api/v1/projects/:id/freshness, MCP assess_freshness).

Demo

pnpm demo:setup builds .kalyth/demo.db from scratch: the pinned FastAPI template, analysed at tag 0.12.0. docs/demo/walkthrough.md is the script for the video. It follows a change request through a person's decision, a coding agent's work over MCP, and the claims that go stale when the repository advances. pnpm demo:agent is a scripted stand-in agent for rehearsals.

Navigator and model providers

By default the Navigator uses a local mock provider. It is free and deterministic, and it labels everything it produces as mock output. Start a run from the Navigator view, or over HTTP with POST /api/v1/projects/:id/navigator/runs. Only a person can start a run.

Real inference uses NVIDIA Nemotron models on Nebius Token Factory. The gateway refuses a call unless all of these hold:

• the model is in the price catalogue, with the capabilities the run needs;

• the project has consented to sending content to the provider;

• the spend ledger can reserve the call's worst-case cost under the cap.

The ledger lives in ~/.kalyth/ledger.sqlite (override with KALYTH_LEDGER). Without a cap, no paid call is possible.

pnpm budget                                   # show cap, spend and remaining budget
pnpm budget set 0.50 --note "approval reference"

To use Nebius:

1. Copy .env.example to .env, which git ignores.

2. Set KALYTH_PROVIDER=nebius and your own KALYTH_NEBIUS_API_KEY.

3. Set a cap with pnpm budget set.

4. Grant consent for the project in the Navigator view.

The key stays in the server process. It is never sent to the browser, stored in run records or logged.

Once a cap is set, pnpm spike --project "<name>" checks the model ids (listing them is not billed), then makes one summary call and one alternatives call. It records both for replay and reports validity, citations, tokens and cost. pnpm spike:replay checks the recorded answers again without any call. See ADR 0010.

For public repositories and synthetic data only, KALYTH_PROVIDER=openrouter with KALYTH_OPENROUTER_API_KEY uses OpenRouter's free Nemotron endpoint, which may log prompts. Nebius remains the competition provider (ADR 0016).

Connect a coding agent over MCP

Over stdio, the agent's client starts the server itself. Use absolute paths, because the client chooses the working directory.

Claude Code (project scope):

claude mcp add kalyth --scope project -e KALYTH_DB=/absolute/path/to/kalyth.db -- node /absolute/path/to/kalyth/apps/server/src/mcp/stdio.ts

Codex (~/.codex/config.toml):

[mcp_servers.kalyth]
command = "node"
args = ["/absolute/path/to/kalyth/apps/server/src/mcp/stdio.ts"]
env = { KALYTH_DB = "/absolute/path/to/kalyth.db" }

A stdio agent can read and propose in every project in that database. To confine an agent to one project, connect it over HTTP instead. The server must be running. Issue an agent token for the project in the Handoff view, then run:

claude mcp add --transport http kalyth http://127.0.0.1:4317/mcp --header "Authorization: Bearer <agent token>"

For Codex, use url = "http://127.0.0.1:4317/mcp" with bearer_token_env_var = "KALYTH_AGENT_TOKEN". A token works for one project and expires within 30 days. The UI session token is not accepted on /mcp.

Agents get:

• read tools, among them list_decisions, get_context_package, analyze_impact and assess_freshness;

• propose_change;

• task tools: list_tasks, get_task, claim_task, renew_task_lease, release_task and submit_execution_report.

There is no commit or accept tool: proposals wait for a person to review and commit them. No tool spends money either: Navigator runs are started by a person.

Export and import

pnpm project:export --project <project id> --out project.json
pnpm project:import project.json

The export holds the project's full event history and stored excerpts. Import rebuilds the project and refuses the file unless the rebuilt state matches the exported state hash (ADR 0014). The UI's Overview view can also download an export. Use pnpm project:import, never pnpm import: that is pnpm's own command, and it can delete pnpm-lock.yaml.

Configuration

All settings are environment variables, and all are optional. The root scripts read .env in the repository root at startup. A variable set in the environment wins over .env, so KALYTH_PROVIDER=mock pnpm dev:server uses the free mock provider whatever .env says.

Concepts in brief

Documentation

• docs/adr: architecture decisions.

• docs/contracts/kernel.md: the kernel contract summary. The executable contracts are the zod schemas in packages/contracts.

• docs/security/threat-model.md: the threat model for local mode. SECURITY.md explains how to report a vulnerability.

• docs/evaluation: the evaluation and its ground truth.

• docs/demo/walkthrough.md: the demo script.

Repository layout

packages/contracts   shared zod schemas and types (kernel, API, MCP)
packages/core        semantic kernel, SQLite store, application services, export and import
packages/analyzer    static repository analysis and ingest (tree-sitter, git objects)
packages/gateway     provider gateway: model catalogue, spend ledger, consent, providers
packages/navigator   grounded summaries and change alternatives, as proposals
packages/context     deterministic context packages for coding agents
packages/tasks       task leases and execution reports verified against git
packages/eval        evaluation harness: lexical retrieval versus context packages
apps/server          HTTP API, MCP server and command-line tools over the services
apps/web             workbench UI (React, React Flow)
docs/adr             architecture decision records

License

Apache-2.0. See LICENSE.