Control Surface

Context switching between multiple terminals/projects is difficult. Control Surface is a local continuity layer that preserves decisions, failed attempts, and evidence as deterministic project history

Comment

Inspiration

In my clinical AI research, I often work across several projects simultaneously, with multiple AI-assisted terminal sessions running in parallel. Git records code changes, but it does not reliably preserve why a decision was made, which alternatives were rejected, what already failed, or what still needs human judgement.

AI transcripts contain some of this information, but they are long, transient, model-specific, and difficult to treat as trustworthy current state. This is particularly important in clinical-data work, where privacy, provenance, and honest uncertainty matter.

That led to the central idea behind Control Surface:

AI coding sessions are temporary. Projects are not.

Control Surface is designed to help a human or agent return to a project and quickly answer:

  • What are we trying to achieve?
  • What is the current milestone?
  • What changed recently?
  • What needs human judgement?
  • What can an agent do next?
  • What failed, and when would retrying be rational?
  • What evidence supports the current state?

What I built

Control Surface is a local-first continuity explorer for AI-assisted projects.

It stores project history as validated, append-only semantic events rather than relying on a mutable AI-generated summary. These events represent:

  • projects, milestones, and tasks;
  • findings and supporting evidence;
  • proposed, accepted, and required decisions;
  • decision rationale and rejected alternatives;
  • failed attempts and explicit retry conditions;
  • structured session handoffs;
  • unresolved questions and next actions.

Deterministic projections turn this history into two complementary interfaces:

  1. An attention-first portfolio for deciding where to look.
  2. A six-view Project Explorer for understanding how a project reached its current state.

The Project Explorer includes:

  • Overview — purpose, milestone, current state, and next action;
  • Recent — a deterministic handoff-bounded context window;
  • Decisions — rationale, trade-offs, acceptance, and rejected alternatives;
  • Forward — human, agent, system, blocked, and unresolved work;
  • Timeline — inspectable semantic history and evidence;
  • Agent Brief — the exact deterministic briefing supplied to a returning agent.

I also built ergonomic commands for recording findings, failed attempts, and handoffs without requiring users to author JSON manually.

How I built it

Before Build Week, I had developed the underlying local event ledger and synchronization engine. It already supported durable SQLite queues, immutable canonical events, offline capture, duplicate-safe synchronization, and deterministic project projection.

During Build Week, I used the official Codex CLI, with GPT-5.6 as the primary implementation and review model, to turn that foundation into the public Control Surface product.

Codex and GPT-5.6 helped:

  • audit the existing architecture and contracts;
  • preserve the frozen event schemas;
  • implement the public surface CLI;
  • build the server-rendered Project Explorer;
  • create the six structured project views;
  • add ergonomic semantic-capture commands;
  • build a deterministic fictional judge demonstration;
  • implement the opt-in terminal-presence layer;
  • write security, privacy, lifecycle, and regression tests;
  • harden the web application;
  • prepare installation, release, and submission documentation.

I supplied the product requirements, controlled the architecture and privacy boundaries, reviewed the generated work, designed acceptance tests, and made the final scope decisions.

The public judge demo uses entirely fictional data. It simulates offline capture, a lost acknowledgement, duplicate-safe replay, synchronization from a second logical host, and deterministic briefing retrieval through a fresh event-store instance.

Challenges

Preserving truth without another AI summary

The largest design challenge was deciding what should be authoritative. It would have been easy to ask an LLM to summarize every session, but that would create another mutable narrative that could drift or sound more certain than the evidence.

Instead, canonical state remains deterministic and LLM-free. AI can help capture or consume context, but it does not decide project truth.

Treating failures as useful state

Most project tools record successful work and current tasks. They rarely preserve failed approaches in a form that prevents repetition.

Control Surface records the objective, method, outcome, failure reason, conditions, and rational retry criteria. A future agent can therefore distinguish “this failed once” from “this should not be retried until a specific condition changes.”

Offline and duplicate-safe synchronization

A local-first system must handle failed delivery without losing or duplicating work. The demo deliberately simulates a lost acknowledgement: central storage accepts events, but the originating host still believes they are pending.

Replaying those events must be safe. Control Surface identifies exact replays as duplicates while rejecting conflicting identity reuse.

Terminal orientation without terminal surveillance

I wanted to connect durable project history with the terminal sessions where work occurs, but without capturing commands, output, prompts, history, working directories, or process inventories.

The resulting presence layer stores only explicit, bounded operational metadata. During testing, exact visible iTerm2 focus did not pass its owner-observed acceptance test. Rather than shipping an unreliable claim, I made iTerm2 identity observe-only. Zellij navigation remains explicitly container-level rather than claiming exact pane focus.

That failure was an important lesson: truthful limitations are part of product quality.

Separating private development from the public demo

The tool was dogfooded privately, but real clinical and research project state could not enter the public repository or video. I therefore created a clean, fictional demonstration and exported the public repository as a sanitized single-commit release.

What I learned

The strongest lesson was that context switching is not primarily a transcript-retrieval problem. It is an orientation problem.

A useful continuity system must preserve:

  • state;
  • rationale;
  • failed routes;
  • evidence;
  • uncertainty;
  • ownership;
  • executable next actions.

I also learned that deterministic infrastructure and AI assistance complement each other well. Codex and GPT-5.6 were highly effective at inspecting the codebase, implementing features, generating tests, and challenging designs. But human control remained essential for privacy, semantics, acceptance criteria, and deciding which apparently working features were not trustworthy enough to ship.

What is next

The next steps are to evaluate re-entry performance in more workflows, improve low-friction semantic capture, and explore additional terminal adapters without weakening the privacy or truthfulness boundaries.

The long-term goal is simple:

Give every long-running AI-assisted project a durable, inspectable memory—so humans and agents can resume safely without losing the thread.

Built With

Share this project:

Updates