Kalyth

Kalyth turns codebases into living engineering models, helping people and AI agents understand systems, explore architectural alternatives, make grounded decisions, and verify what gets built.

Comment

Inspiration

AI coding agents have become remarkably capable of writing and modifying code. But writing code is only part of engineering.

Before changing a system, I want to understand how its components interact, what constraints matter, why previous decisions were made, what a proposed change might affect, and how to determine whether an implementation actually achieved its intended purpose.

In most development workflows, that understanding is fragmented across repositories, conversations, diagrams, documents and the temporary context of coding agents. When a session ends or another agent takes over, important reasoning can disappear or become outdated.

I started Kalyth around a simple idea: engineering understanding should persist beyond individual conversations, and humans and AI agents should be able to work from the same evolving model of a system.

I wanted to create something that works alongside existing coding agents rather than replacing them—an engineering layer that helps people investigate, design, decide, implement and verify changes more systematically.

What it does

Kalyth is an open-source, evidence-backed engineering environment that connects system architecture, engineering decisions and implementation work.

It statically analyzes Python and TypeScript repositories, constructing a structured model of components, interfaces, data entities and their relationships. Observations are linked to the source code and revision from which they were derived, allowing users to inspect the evidence behind the model.

When someone proposes a change, Kalyth helps investigate it rather than immediately jumping to implementation.

Using NVIDIA Nemotron models through Nebius Token Factory, Kalyth can generate alternative approaches, identify directly affected components, explain potential consequences and surface questions that matter to the decision.

Users can then:

  • Explore a system through an interactive architecture canvas.
  • Inspect source evidence, dependencies and potential change impact.
  • Compare engineering alternatives and their trade-offs.
  • Accept decisions with explicit reasoning and rationale.
  • Compile deterministic context packages containing relevant requirements, constraints and engineering decisions.
  • Hand structured tasks to external coding agents through the Model Context Protocol (MCP).
  • Verify reported Git commits and reconcile implementation changes with the engineering model.

Kalyth also maintains a revision history, tracks stale observations and distinguishes facts directly observed in source code from inferences and user-provided information.

The objective is not to replace coding agents, but to give people and agents shared engineering context that survives individual tasks and sessions.

How I built it

I developed Kalyth as a TypeScript monorepo, with extensive assistance from Claude Code and other AI tools for implementation, testing, technical research and architectural critique.

I directed the product's design, worked through its engineering contracts, reviewed architectural decisions and coordinated development toward a functioning, open-source release.

The implementation combines several systems:

Semantic kernel. A structured engineering model with typed objects, relationships, evidence-backed claims, immutable revisions and a replayable event log stored in SQLite.

Repository analysis. A tree-sitter-based analyzer that examines Python and TypeScript code without executing the analyzed repository. Its observations are pinned to source revisions and can be refreshed as the code changes.

Engineering Navigator. NVIDIA Nemotron generates grounded summaries and alternative designs. Kalyth validates the structured output, checks citations against pinned source excerpts and presents proposals for human review.

Inference gateway. NVIDIA Nemotron 3 Ultra and Nemotron 3 Super are accessed through Nebius Token Factory's OpenAI-compatible API. Model calls use strict JSON schemas, explicit provider consent and a persistent ledger that reserves their worst-case cost before execution.

Decision and context systems. Accepted decisions become part of the persistent engineering model. Kalyth compiles focused, reproducible context packages containing the requirements, constraints, relevant evidence and tasks that coding agents need.

Agent interoperability. An MCP interface allows external coding agents to read engineering context, claim tasks and submit execution reports. The system independently checks reported Git commits against task requirements and reconciles observed implementation changes.

Interactive workbench. A React interface provides architecture visualization, change threads, alternative comparisons, task management, context packages, evidence inspection and historical views.

I deployed the public demonstration on Fly.io. Each visitor receives an isolated copy of an analyzed FastAPI project, with free prerecorded Nemotron responses and a limited allowance for live engineering analysis.

I also validated a complete handoff using a real Claude Code agent: Kalyth provided the engineering task, Claude Code implemented and committed a change, and Kalyth verified and reconciled the resulting Git commit.

Challenges I ran into

Grounding AI responses in real evidence.

One challenge was ensuring that generated architectural statements referred to actual source code.

Nemotron sometimes changed quotation marks, whitespace or line breaks when reproducing source excerpts. I worked through prompt improvements, strict citation validation and narrowly bounded normalization to distinguish harmless formatting differences from unsupported claims.

Keeping inference spending predictable.

The maximum theoretical cost of a model call can be substantially higher than its actual cost. This becomes important when making a public application available under small spending limits.

I implemented a gateway that checks consent and reserves the maximum permitted cost before initiating inference. Requests that cannot fit within their authorized budget are refused.

Balancing reasoning quality, speed and reliability.

I tested several Nemotron Super configurations.

Disabling reasoning made responses faster and cheaper, but produced weaker architectural alternatives with less meaningful variation. Unbounded reasoning sometimes exhausted the output allowance before producing complete structured JSON.

Bounded reasoning provided a more practical balance, although output completeness and engineering quality still require validation.

Connecting architectural decisions to real implementation.

A model can propose a technically plausible change without ensuring that a coding agent implements the intended result.

Building a verifiable handoff required structured context packages, scoped permissions, task leases, Git verification and a process for reconciling implementation evidence with the accepted engineering decision.

I tested that process with an actual Claude Code session rather than relying exclusively on scripted simulations.

Balancing engineering rigor with usability.

Kalyth deliberately separates investigation, evidence, decisions, implementation and verification. These distinctions preserve accountability, but the current interface can require too much navigation and manual interaction between stages.

Given the hackathon's limited development time, I prioritized a stable, inspectable implementation over automating every transition.

A major next challenge is reducing that workflow friction without hiding reasoning, uncertainty, important choices or human control.

Accomplishments I'm proud of

  • Building a persistent engineering model with explicit provenance, immutable revisions and reproducible history.
  • Connecting model-generated architectural alternatives to source evidence and deterministic impact analysis.
  • Creating an end-to-end workflow from engineering investigation and human decisions to coding-agent execution and reconciliation.
  • Demonstrating a genuine Claude Code integration through MCP, including verification against an actual Git commit.
  • Implementing inference consent, citation validation, structured-output checks and bounded spending controls.
  • Deploying a public demo with isolated visitor environments, recorded and limited live inference, and automated accessibility testing.
  • Publishing Kalyth as an Apache-2.0-licensed open-source project.

What I learned

The most important lesson was that engineering intelligence requires more than generating plausible answers.

A useful engineering system must distinguish observed evidence from interpretation, preserve the reasoning behind decisions, recognize uncertainty and remain connected to what was actually implemented.

I also learned that grounding, authorization, spending controls and verification are more dependable when enforced by the platform rather than delegated entirely to model instructions.

Another lesson was that powerful engineering concepts do not automatically produce an intuitive experience. The challenge is to make systematic engineering accessible without reducing its depth or imposing unnecessary ceremony.

Kalyth is still an early release, but it demonstrates how these principles can come together in a working environment.

What's next

My longer-term vision is to develop Kalyth into an extensible engineering intelligence layer that people can use directly or connect to their preferred development tools and coding agents.

I want to expand it in several directions:

Engineering knowledge. A navigable, evolving knowledge system that connects engineering principles, system-design patterns, constraints, tools, evidence and the situations in which particular approaches are appropriate.

Reusable engineering methods. Extensible methods for architecture analysis, security investigation, research, migrations, performance, reliability and other engineering disciplines.

Human and AI collaboration. More flexible coordination between people and specialized agents, with structured responsibilities, preserved context, explicit permissions and verifiable outputs.

A more natural experience. A workspace where users can explore engineering ideas and systems without manually managing every intermediate step, while retaining access to detailed evidence and decisions when needed.

Evaluation and continuous improvement. Testing whether Kalyth meaningfully improves engineering outcomes. An independent, blinded evaluation of its effects on coding-agent implementation quality has already been designed with frozen ground truth, but has not yet been completed.

I also want users to eventually contribute, adapt and share engineering knowledge and methods while preserving their provenance and allowing them to be challenged and improved.

These are directions for future development, not features I claim are already complete in v0.1.0.

Ultimately, I want Kalyth to help make engineering knowledge more accessible, reusable and actionable—so people and AI agents can understand and evolve complex systems with greater clarity and confidence.

Built With

Share this project:

Updates

Submission history