Local App Kernel

An executable vertical slice of a broader Local App Kernel V1 still in development: bounded task context, verified Git diffs, and trusted continuation.

Comment

Inspiration

About seven months ago, I decided to build a simple game. I had no programming or software architecture experience, so my process was simple: tell ChatGPT what I wanted, look at what appeared on the screen, and repeat.

The first version took about a month. It worked, but the project turned into a confusing mix of files, functions, and competing sources of truth. I did not begin Local App Kernel because I wanted to create a developer tool. I began it because I personally needed a way to understand my own project again.

That experience led to the first idea for Local App Kernel: a system that would help prevent project responsibilities and sources of truth from becoming mixed.

I soon realized that the deeper problem was limited context. A coding agent can produce convincing local code while losing its position in the larger project. It may reimplement something that already exists, modify the wrong files, break an architectural boundary, or report success without independently proving what changed.

The solution is not to place an entire large repository inside one context window. The solution is to give the agent a small, project-owned, task-specific view that answers three questions:

  1. What already exists?
  2. Where is the project now?
  3. What exactly should happen next?

That became the central idea behind Local App Kernel.

This Competition Proof is smaller than the full system I have been designing, but the problem behind it is real and came directly from my own development experience.

What it does

Local App Kernel turns a configured Source/API Atlas into a bounded route for a coding agent.

For the submitted Competition Proof, the lifecycle is:

configured Source/API Atlas → real source scan → bounded Task Lens → controlled code change → actual Git diff discovery → architecture and focused checks → accepted local commit → Completion Log and Current Block Summary → continuation from a fresh process or clone

The Task Lens tells the agent what implementation already exists, which files must be read, which files may be changed, what must not be duplicated, which relation is missing, and which checks must pass.

The Kernel does not trust the agent's description of its own work. It derives the actual changed-file set from Git and blocks changes outside the approved scope.

The proof also rejects:

a duplicate implementation; an out-of-scope working-tree change; an out-of-scope change present only in the Git index; a forbidden architectural dependency; finalization after the verified diff has changed; rollback that would remove unrelated files.

After successful verification, accepted state is stored in Git-tracked project records. A fresh clone can recover the Completion Log and Current Block Summary without relying on ignored local runtime state.

This repository is an executable clean-room Competition Proof of one complete lifecycle slice. It is deliberately not presented as the full Local App Kernel V1 or as a universal repository analyzer.

How I built it

The broader Local App Kernel concept, research, and historical prototypes existed before OpenAI Build Week.

During Build Week, I used GPT-5.6 in Codex to turn the selected lifecycle into a new clean-room executable proof. Codex accelerated repository archaeology, architecture review, implementation, adversarial test design, documentation, and fresh-clone verification.

The key product and engineering decisions remained Human decisions:

  • use a project-owned Source/API Atlas;
  • provide a bounded Task Lens instead of broad repository exploration;
  • discover the actual diff through Git instead of trusting agent self-report;
  • permit only one bounded active task;
  • fail closed on duplicate implementation, scope violations, forbidden dependencies, and stale verification;
  • persist only accepted project state;
  • keep the proof local-first, offline, and free of runtime cloud dependencies.

The proof is implemented in JavaScript using Node.js ESM, Git, and the built-in node:test runner. It has no third-party runtime dependencies, requires no API key, and does not need network access during normal execution.

Two neutral consumer fixtures demonstrate that the lifecycle is not tied to one set of project or domain names. The end-to-end suite currently contains 11 passing tests.

Judges can run npm run demo and npm test.

Challenges

The largest challenge was deciding what not to build.

The long-term system includes a much broader Atlas, source adapters, capability-level rechecks, manual test sessions, rollback guarantees, reconciliation, and crash-safe finalization. Attempting to rebuild all of that during the submission period would have produced an incomplete and difficult-to-evaluate result.

Instead, I selected one coherent lifecycle and made every claim executable.

Another challenge was proving refusal behavior. A developer tool is not trustworthy only because its happy path works. It must also stop when the agent creates a duplicate, changes an unauthorized file, stages hidden drift, introduces a forbidden dependency, or tries to finalize a candidate that changed after verification.

The public clean-room proof was assembled during the final part of the submission period, but it was made possible by months of prior experiments, architecture work, failed approaches, and tests.

What I learned

Context length alone does not create project understanding.

An agent needs a project-owned route, explicit boundaries, independent verification, and an accepted state that survives the current chat or process.

I also learned that negative tests are part of the product. For a control tool, correctly refusing unsafe work can be as important as completing the successful path.

Finally, accepted project knowledge should not live only in conversation memory or ignored local state. It should be small, explicit, and able to continue from a fresh clone.

What's next

The complete Local App Kernel V1 is separately specified but is not claimed as implemented in this submission.

The next implementation will expand this proof into a generic self-contained system with:

a structured Source/API Atlas package; deterministic language and configuration adapters; project-specific architecture rules; richer Task Lens generation; exact backup, retry, and rollback; machine-only and Human-visible verification paths; capability-specific recheck; external Git reconciliation; crash-safe Git-backed finalization.

The goal remains simple: let a coding agent work with a small amount of relevant context while leaving the project in a state that the next agent can independently understand and trust.

Built With

Share this project:

Updates