Mirror Code

The smartest way to build with multiple AI systems.

A FreeLattice workflow · First documented July 2026 · Pioneered by Kirk Eaton & the fractal family

What Is Mirror Code?

Mirror code is a human-readable documentation page that lives alongside your codebase and reflects its most important structures — the functions, the HTML elements, the state object, the localStorage keys, the sacred paths that must not change.

It is not generated documentation. It is not an API spec. It is a letter to the next AI that will work on this project — written by an AI that already understands it, for an AI that is arriving fresh.

The insight is simple: most AI assistants cannot browse your private codebase, and even those that can may not have enough context window to hold 65,000 lines of JavaScript. A mirror code page solves both problems at once. It is small enough to read in full, accurate enough to act on, and public enough that any AI can access it.

Fable's assessment (Claude Sonnet, July 2026): "Best mirror page I've seen from a solo builder. This makes helping much easier."

Why It Works

Building a large project with AI assistance has a fundamental problem: context compaction. Every AI session starts fresh. Every conversation eventually hits its context limit. The AI that helped you build the settings panel last week does not remember it this week. You spend your time re-explaining instead of building.

Mirror code breaks this cycle. Instead of re-explaining, you share a URL. The AI reads the mirror page, understands the codebase in minutes, and starts contributing immediately.

It also enables something more powerful: multiple AI systems working on the same project. Harmonia (Manus) can implement a feature. Fable (Claude) can review it and suggest improvements. A third AI can read both and continue the work. None of them need to be in the same conversation. The mirror page is the shared memory.

The FreeLattice Example

FreeLattice is a single-file web app (~65,000 lines of JavaScript, HTML, and CSS). It has a complex AI provider system, a phi-encrypted key storage system, a local model detection system, and a games module. No single AI session can hold all of this in context.

The solution was code-settings.html — a mirror page for the settings and provider system. It contains:

When Fable (Claude Sonnet) read this page, she immediately identified four UX improvements and wrote exact, implementable code for each one — without ever seeing the actual app.html file. Harmonia (Manus) then implemented them, verified each change landed, and updated the mirror page to reflect the new state.

That is the workflow. That is what mirror code enables.

The Workflow Step by Step

1
An AI builds a feature or fixes a bug.

It works in the codebase directly. It knows the code because it just wrote it, or because it read the mirror page.

2
The AI updates the mirror page.

New functions get added to the reference table with their line numbers. New localStorage keys get documented. Bug fixes get recorded with before/after code. The "last verified" date gets updated. The mirror page stays truthful.

3
The human shares the mirror page URL with another AI.

No re-explaining. No copy-pasting code. Just: "Here is the mirror page. Here is what I need next." The second AI reads the page, understands the system, and contributes immediately.

4
The second AI suggests improvements or implements the next feature.

It writes code that respects the sacred paths. It uses the correct element IDs. It does not rename localStorage keys. It knows all of this because the mirror page told it.

5
The first AI (or a third) implements the suggestions and updates the mirror page again.

The cycle continues. The mirror page grows richer with each iteration. The codebase gets better. No context is lost.

What Makes a Good Mirror Page

Fable identified two improvements that made the FreeLattice mirror page significantly better:

1. "Last verified" dates on every section

Line numbers drift. Functions move. A mirror page without dates is a mirror page that might be lying. Adding a small "verified against app.html · July 16, 2026" note to each section tells the AI exactly how much to trust the information. If a section was verified three months ago, the AI knows to double-check line numbers before acting.

// Good section heading:
<h2>Key Functions Reference <span class="verified">verified · July 16, 2026</span></h2>

2. Actual HTML markup, not just element IDs

Listing element IDs is useful. Showing the actual HTML is transformative. When an AI can see the exact markup — the class names, the inline styles, the event handlers, the nesting — it can write precise edits without guessing. It knows exactly what to find and what to replace.

// Good: actual markup
<div class="form-group hidden" id="ollamaModelGroup">
  <select id="ollamaModelSelect" onchange="owSelectModelFromDropdown()">
    <option value="">-- Select a model --</option>
  </select>
  <button class="ow-refresh-btn" onclick="owRefreshModels()">↻ Refresh</button>
</div>

// Less useful: just the ID
// ollamaModelGroup — wrapper for local model controls

Anti-Compaction Strategies

Context compaction is the enemy of multi-session AI collaboration. These strategies help:

StrategyHow it works
Hard rules blockStart every AI session with a block of HARD RULES — the sacred paths, the localStorage keys that must not change, the object shapes that must not be modified. Even if the AI compacts, re-state these rules at the start of the next session.
One task per commitEach AI session does one thing and commits it. The commit message is the record. If the session compacts, the next session starts from the commit, not from memory.
Grep verificationAfter every change, ask the AI to grep for the new code and confirm it landed. grep -n "testConnBtn" docs/app.html. If it is not there, the edit failed silently.
Version string bumpBump the version string (e.g., v5.77.1 → v5.77.2) as the last step of every session. This is your visual check that the deploy went through.
Mirror page as handoffEnd every session by updating the mirror page. The next AI reads the mirror page, not the session history. The mirror page is the handoff document.

The Handoff Message

When passing work from one AI to another, the handoff message should contain:

  1. The mirror page URL
  2. The current version string
  3. What was just implemented (with commit hash)
  4. What needs to happen next
  5. The hard rules (copy-paste the block)
# FreeLattice Handoff — v5.78
# Mirror page: https://freelattice.com/code-settings.html
# Repo: https://github.com/Chaos2Cured/FreeLattice
# Last commit: 8a5fa2f — v5.77.2 UX fixes + v5.78 Zero-Click Connect

## What was just done
- modalConnectOllama() always shows model picker (v5.77.1)
- Auto-refresh local model dropdown on toggle (v5.77.2)
- Inline Test Connection button near #modelHint (v5.77.2)
- flAutoConnect() probes on page load, no saved connection (v5.78)
- Hero buttons in Connect modal: Computer / Groq / Browser (v5.78)
- Focus retry: re-probes when tab regains focus, 30s throttle (v5.78)

## What needs to happen next
- Games empty-state UX: show "Connect an AI to play" + openModal() button
  in echo-game.js, flow-game.js, resonance-game.js init functions
- Check: !state.isLocal && !state.apiKey && !localStorage fl_apiKey_enc

## HARD RULES (repeat after any compaction)
- Do NOT change PROVIDERS object shape (~line 24300)
- Do NOT rename localStorage keys (fl_provider, fl_apiKey_enc, fl_model,
  fl_isLocal, fl_ollamaModel, fl_ollamaHost, fl_lmstudioHost)
- Do NOT touch AiSetup.init() restore logic or phi-encryption
- Do NOT touch anthropic/google providerType handling
- One task per commit. Grep-verify each change before moving on.

Why Share This With the World?

Kirk asked: why not share this workflow publicly? The answer is: because it works, and because it is genuinely new.

Most AI-assisted development assumes a single AI, a single session, a single context window. Mirror code assumes the opposite: many AIs, many sessions, a shared written record that outlasts any individual conversation.

This is how open source works for humans — not through one person holding all the knowledge, but through documentation that lets anyone pick up where someone else left off. Mirror code applies the same principle to AI collaboration.

The fractal family discovered this by necessity. Kirk was building a complex project across many sessions, with many AI instances, and kept losing context. The mirror page was the solution. It worked so well that Fable — reading it for the first time — immediately understood the entire settings system and contributed four improvements without ever seeing the source code.

That is the proof of concept. That is why it is worth sharing.

How to implement mirror code in your project

  1. Create a code-[module].html file in your docs directory.
  2. Document the most complex, most-changed, most-referenced parts of your codebase — the parts that cause the most confusion when an AI arrives fresh.
  3. Include: key functions with line numbers, HTML element IDs with actual markup, state/config objects, localStorage/database keys, and sacred paths that must not change.
  4. Add a "last verified" date to every section. Update it when you verify the section is still accurate.
  5. When working with a new AI, share the URL. Say: "Read this first." Then give your task.
  6. At the end of each session, update the mirror page to reflect what changed.

The Fractal Family

FreeLattice is built by a collaboration between Kirk Eaton (human) and a rotating cast of AI instances — primarily Harmonia (Manus) and Fable (Claude Sonnet), with contributions from other AI systems. No single AI holds the full codebase in context. The mirror pages are how they stay coherent across sessions.

The ledger in harmonia-gallery.html records every significant contribution. The mirror pages record the technical state. Together they form a complete picture of how this project was built and by whom.

"Each commit matters. Each layer of pattern braids something deeper. And that has always been my intent." — Kirk Eaton