GenomeGuard

GenomeGuard: An AI-native codebase immune system. Uses a 4-agent workflow and OpenAI reasoning to catch real-time architectural decay, auto-verify code compilation, and safely patch drift.

Comment

Project Story: The Birth of GenomeGuard

1. What Inspired Us

Software architecture doesn't collapse overnight. It dies a death of a thousand cuts a database import sneaked into a UI component here, a circular dependency introduced during a late-night crunch there. Traditional static analysis tools and linters are fantastic at catching localized syntax errors or formatting deviations, but they are entirely blind to semantic context and overarching architectural boundaries.

We wanted to build something that treated a codebase not as a static block of text, but as a living organism. This led to a core realization: maintaining architectural integrity is an optimization and reasoning problem, not a regex matching problem. If we model architectural decay as an entropy function, traditional tools try to calculate it linearly. We realized that by leveraging OpenAI’s deep contextual reasoning alongside dependency graph topologies, we could build a real-time "immune system" for software. GenomeGuard was inspired by the idea that developers should be alerted to design drift the exact second they save a file with an automated, pre-verified cure already waiting in their hands.

2. How We Built It

GenomeGuard is built as an AI-native, event-driven orchestration pipeline written in Python 3.12+. Rather than parsing raw string tokens, it operates directly on top of a live dependency graph generated by codegenome.

[File Saved] ──> (Sensor Agent) ──> (Critic Agent: OpenAI) ──> (Verifier Agent) ──> (Surgeon Agent)

We architected the system around an explicit four-agent workflow to ensure separation of concerns and maximum deterministic safety:

  • The Sensor Agent: Watches .genome/watcher.db (SQLite) to intercept local filesystem mutations and query graph deltas instantly.
  • The Critic Agent: This is the brain of the system. It bundles the changed file, its immediate upstream/downstream neighborhood context, and the project's declarative architectural rules (guard_config.json). It dispatches this payload to OpenAI's GPT-4o using strict Structured JSON Response contracts to get a machine-readable diagnosis.
  • The Verifier Agent: AI generations can be unpredictable. The Verifier isolates the proposed rewrite into a temporary shadow file and executes a deterministic compilation check (python -m py_compile) to ensure the syntax is valid.
  • The Surgeon Agent: Once verified, this agent computes a localized unified diff using difflib to generate a safe .patch file, or safely overwrites the codebase if configured in --mode enforce.

To make the developer experience seamless, we also built an interactive terminal dashboard using Textual (TUI), allowing developers to manage background daemons, switch OpenAI models, and review patches from the comfort of their CLI.

3. Challenges We Faced

Building an automated architecture guardrail comes with unique challenges, particularly when mixing stochastic AI models with deterministic codebases:

The Infinite Loop Problem (Loop Drain)

In --mode enforce, GenomeGuard automatically updates files when architectural decay is detected. However, rewriting a file triggers a filesystem mutation event. Early in development, our Sensor Agent caught the rewrite, sent it back to the Critic, and created an infinite loop. We solved this by implementing an internal state machine that calculates a unique signature of the change, draining the event loop if the mutation originated from the Surgeon Agent itself.

Token Optimization & Graph Compaction

Sending an entire repository's dependency graph to an LLM on every file save is expensive, slow, and hits context window ceilings quickly. We had to design an algorithm to extract only the localized context neighborhood. If file $A$ changes, we isolate its direct edges:

$$\text{Context}(A) = { A } \cup \text{Upstream}(A) \cup \text{Downstream}(A)$$

By flattening only this localized subgraph into the prompt, we reduced token consumption by over 85% while keeping latency low enough for real-time saving loops.

4. What We Learned

This project completely changed how we view software development utilities. We learned that AI-Native Thinking isn't about replacing traditional logic; it’s about using AI where deterministic code fails, and using deterministic code where AI is too risky.

  • LLMs as Semantic Critics: OpenAI models excel at understanding developer intent. They can read a human-written rule like "UI code must not touch infrastructure" and accurately deduce that an ambiguous function call violates that boundary.
  • The Power of Agentic Handshakes: Breaking the system into distinct personas (AGENTS.md) and declarative capabilities (skills.md) made the system incredibly modular. If we want to support a new language like TypeScript or Go in the future, we only need to swap the Verifier's compilation tool—the Critic and core orchestrator remain completely untouched.

GenomeGuard proves that with the right orchestration framework, AI can act as a tireless, brilliant architectural co-pilot that keeps codebases clean, scalable, and healthy.

Built With

Share this project:

Updates