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.

I, Philip Ciuca, develop Kalyth as an individual developer, with extensive AI assistance: Claude Code for most of the implementation, and other AI tools, ChatGPT among them, for research, architecture, testing and review. I set the direction and make the product, spending and release decisions.

Try the hosted demo

kalyth-demo.fly.dev opens your own copy of Kalyth's model of the FastAPI full-stack template, analysed at tag 0.12.0. Nothing you change there reaches other visitors. You can:

• read the Situation page, the canvas and its lenses, and each element's evidence, pinned to lines of the template's source;

• start one of four change requests in the Navigator, and watch its recorded Nemotron 3 Ultra run play back, free and at once, or write your own request, which runs live on Nemotron 3 Super; the banner says whether a live run can start, and how many you have left today;

• compare the alternatives, accept one, and commit the proposals, which makes new revisions of your copy;

• build the context package that a coding agent would get for the accepted decision.

The hosted demo is deliberately narrower than Kalyth run locally (ADR 0019):

• One project, no imports. It holds the analysed template only and cannot analyse your repository. Run Kalyth locally for that (Analyse a repository).

• No agent access. MCP and agent tokens are off, so no coding agent can connect to it. The hand-off to Claude Code is shown in the demo video and works locally (Connect a coding agent over MCP).

• Live runs are capped. Recorded runs are always free. A live run sends excerpts of the public template, and nothing else, to Nemotron 3 Super on Nebius Token Factory. Each copy has at most three live runs a day, and all visitors share a small daily allowance (0.07 USD a day for the public and 0.03 USD for judges until 1 December, more during judging). A live run reasons within a budget, makes one attempt, takes about half a minute and costs about 0.01 USD. Its alternatives are briefer than the recorded Ultra runs. It is offered only while the allowance left today covers its worst-case cost (0.03 USD), so before December that is about five public runs and one judges' run a day. After that, live runs stop until the next UTC day, and the recorded runs still work.

• Copies are temporary. A copy is deleted after a day without use, or sooner, oldest idle copy first, when new visitors need the space. Every copy starts again from the template when the server restarts or is redeployed.

• One small machine. It sleeps while nobody uses it; the first request after a pause takes about a second. Each address has a daily traffic limit.

Judges: the Devpost testing instructions give a code. I have a judge code, in the banner, gives your copy the judges' own allowance.

Related MCP server: project-surface

Status

Phase 1. What exists and is tested today, in CI on Linux and Windows: 532 unit and integration tests, and 64 browser tests of the main flows by keyboard (57 of the local workbench, 7 of the hosted demo, one at phone width), 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 on a branch or tag, it carries the task's trailer, it descends from the task's base, and the files changed since the base are exactly those reported. Tests are the agent's own claim; Kalyth does not run them. A person completes the task.

• Reconciliation. After a report passes verification, Kalyth's analyser reads the task's commit and compares it with the commit the work started from, element by element: their own source, their fields and their relations. It says which of the decision's changes the source now shows, what else changed, and which changes came from other commits. Links to proposed elements come back as proposals for a person.

• Workbench UI. A Situation page that says what needs you; a canvas of the system with lenses for claim basis, freshness, impact and decisions; one change thread per decision, from the request through alternatives, questions, the decision, hand-off and agent work to reconciliation; a side-by-side comparison; and Records, Proposals, Tasks, Agents and packages, and History, with an inspector. 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.

NVIDIA Nemotron on Nebius Token Factory

Every model call goes through Nebius Token Factory's OpenAI-compatible API, through one gateway (ADR 0010):

• Change requests use Nemotron 3 Ultra (nvidia/Nemotron-3-Ultra-550b-a55b). The hosted demo's four presets replay Ultra answers recorded on Nebius against the same project.

• Element summaries, the evaluation harness, and the hosted demo's live change requests use Nemotron 3 Super (nvidia/nemotron-3-super-120b-a12b). In the hosted demo, Super reasons within a budget of 8,000 thinking tokens and 14,000 output tokens, with one attempt per run (ADR 0019).

• Every call asks for structured output against a strict JSON schema. Every citation is checked against the pinned source. The call needs the project's consent, and its worst-case cost is reserved in a spend ledger before it is made.

Evidence so far

• Grounding. In the keyed spike (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 (ADR 0017). In the recorded multi-tenancy run the demo replays, 25 of 39 citations are exact and 4 more match after that bounded normalisation. The 9 items that failed a check, 7 of them for a quote not found in the cited source, were dropped, not repaired.

• Live runs in the hosted demo. Three configurations of Nemotron Super were measured on the same request (ADR 0019). Unbounded reasoning ran out of output tokens once and cost 0.025 USD. Reasoning off was fast but gave inconsistent alternatives. Bounded reasoning, the one deployed, answered on its first attempt in 33 seconds for 0.008 USD, with 4 of 4 citations exact.

• Agent hand-off. Claude Code, connected over MCP, claimed a task, made the change in its own worktree, committed it with the task's trailer and reported. Kalyth verified the report against git and reconciled the commit with the decision (the demo video, and docs/releases/v0.1.0-rc.1.md).

• Not done yet: the independent evaluation. It is a blinded comparison of the same coding agent given a plain prompt, retrieved repository files, or Kalyth's context package and MCP tools, on a demanding change to a pinned open-source repository. Its ground truth was drafted by an AI session separate from Kalyth's implementation, reviewed by ChatGPT, approved by me and frozen (version 2, on the branch eval/independent-2026-10). The run is planned for after the hackathon submission, and this README will say what it found (docs/evaluation).

The hosted demo runs on Fly.io at kalyth-demo.fly.dev (above). It is the same server in demo mode (pnpm demo:serve runs it locally), deployed by hand from the release tag, never automatically on a push (deploy/README.md).

Limitations

• Static analysis, two frameworks. The analyser reads Python and TypeScript with tree-sitter. It finds FastAPI routes and SQLModel tables; other frameworks show up as modules, imports and libraries only. Each observation states its coverage.

• Behaviour is not observed. Nothing from an analysed repository is executed. "Observed" means a tool read a fact in pinned source, never that the code runs correctly. An agent's tests are its own claim.

• The model proposes; a person decides. Navigator output is inferred, carries its citations and lands only when a person commits it. A citation that does not match the pinned source is rejected, but a grounded proposal can still be a poor design. The Navigator has no typed way to propose a new field of an existing entity, so a model may propose one as an entity of its own (User.org_id); reconciliation then finds no element of that name, though it shows the field added to the entity.

• Local first. One person per server, on one machine. The hosted demo gives each visitor a copy of one analysed project, with no imports and no agent access (Try the hosted demo).

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 reads a repository from its git objects at one ref, and never executes it. A remote one is cloned bare, over HTTPS only, into .kalyth/repos:

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

A repository on your machine is read in place, without a copy. Only committed work at the ref is read, so commit what you want analysed:

pnpm ingest --repo /absolute/path/to/your/repo --ref main --project "your project"

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

docs/demo/walkthrough.md is the script for the video. It follows a change request through a person's decision and a coding agent's work over MCP to what the model learns from that work. It runs on the committed demo template (deploy/demo/template.json, the pinned FastAPI template analysed at tag 0.12.0) and replays a Nemotron run recorded against it, at no cost. pnpm demo:setup builds the same analysis from scratch, with new ids that no recording matches.

The hand-off in the video is real. Claude Code connects to Kalyth over HTTP MCP with a token for that one project, and is given the task prompt Kalyth wrote. It claims the task, reads the context package, makes the change in its own worktree, commits it with the task's trailer and submits an execution report. Kalyth then checks the report against git and reconciles the commit with the decision. Nobody types while Claude Code works; the browser steps are scripted, and the video says so. docs/demo/recording.md is how it is recorded: pnpm demo:recording setup makes a disposable project, repository and agent worktree for the hand-off. pnpm demo:agent is a scripted stand-in for rehearsals only.

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, and docs/demo/recording.md: how the video was made.

• docs/releases/v0.1.0.md: the competition release, what was checked and what is known not to work.

• docs/hackathon/submission.md: the hackathon submission text.

• docs/feedback/nebius-nvidia.md: what I hit with Nebius Token Factory and the Nemotron models.

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

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md describes the workflow and the checks every change passes (pnpm check, and pnpm build && pnpm test:e2e for the UI), and AGENTS.md the conventions for coding agents working in this repository. Report vulnerabilities as SECURITY.md describes, not in a public issue.

License

Apache-2.0. See LICENSE.