Codex Aware

Codex Aware makes running software legible and safely operable to any authorized AI—turning live application state into grounded context, gated actions, and verified receipts.

Comment

Inspiration

Codex can understand a repository, but by default it cannot know what a running application means right now. The user may be looking at a particular task, game rule, checkout boundary, or failure receipt, while Codex sees only files and prompts. As a developer, I knew that closing this gap would transform context, alignment, and productivity.

I kept encountering the same architectural pattern across four very different applications: each already possessed meaningful identities, commands, runtime guards, and state, but none had a durable way to share that meaning with an external intelligence. That observation became Codex Aware.

What it does

Codex Aware is a semantic continuity layer for running software.

A user selects an entity in the application and pairs Codex with a one-time code. Codex receives the entity's stable application identity, bounded relationships, logical source location, current safety classification, and relevant causal history. It does not require a screenshot, DOM dump, screen coordinates, or a copied explanation.

The connection remains live as the user changes focus. It also works in reverse: Codex can request a declared semantic action, such as revealing the selected entity's blast radius. The application—not the model—decides how to render that request.

Most importantly, dispatch is not treated as success. A receipt remains awaiting_consumer until the browser performs the effect and acknowledges the observed result against the same trace.

Context also never becomes authority. Durable policy proposals are bound to an exact hash and require an explicit browser-human decision. Unknown actions fail closed.

The resulting loop is:

Observe → Ground → Resolve → Propose → Gate → Apply → Verify → Receipt

How I built it

The responsive graph workspace is built with Next.js, React, and TypeScript. A FastAPI service provides pairing, bounded context, semantic actions, proposals, effect acknowledgements, and receipts.

The persistence layer uses SQLite locally and PostgreSQL in production. Its append-only continuity log records workspace-local monotonic events, trace and causation IDs, hashed actors, proposals, directives, and observed effects.

A local MCP bridge makes the same contract available to Codex. A remote MCP surface also lets ChatGPT on Android participate as a bounded semantic actor without receiving filesystem authority. Both surfaces share the same stable identities, policy gates, and receipt vocabulary.

Application adapters declare semantic metadata and allowlisted handler keys; they cannot inject executable code. The web and API services are containerized, tested, and deployed separately on Google Cloud Run with PostgreSQL-backed continuity.

I used Codex with GPT-5.6 to examine the existing applications, recognize their shared pattern, formalize the protocol, implement both services, create the tests, diagnose mobile failures, and deploy the result.

Challenges I faced

The hardest problem was preserving identity across unrelated processes and surfaces. A highlighted rectangle is not meaning. Codex and the browser needed to agree on an application-owned identity that survived navigation, scrolling, mobile suspension, and reconnection.

The second challenge was distinguishing a requested action from a completed effect. A server can successfully enqueue a directive while the browser is suspended. Codex Aware therefore requires a separate observed-effect acknowledgement before finalizing the receipt.

Mobile dogfooding exposed an Android event storm and a race caused by the browser being suspended between dispatch and consumption. I traced both through the continuity log, added regression tests, and changed the client recovery flow so pending directives are consumed when the browser returns—without a manual reload.

The final challenge was safety. The useful version of this idea cannot make awareness equivalent to control. Pairing codes are single-use, actor tokens are scoped and hashed, manifests contain no executable code, proposals are hash-bound, and unknown commands are denied.

Accomplishments I am proud of

  • A real browser and a separate Codex process share live semantic context.
  • Codex follows selection changes without receiving a new explanatory prompt.
  • The channel works in reverse through semantic actions rather than synthetic clicks.
  • Browser-observed effects produce causal receipts on the original trace.
  • Human authority remains visible and enforceable at durable boundaries.
  • The same deployed continuity layer works from Codex and ChatGPT on Android.
  • The complete loop runs on Cloud Run with SQLite/PostgreSQL parity and automated backend and frontend tests.

What I learned

The breakthrough is not that an AI can highlight graph nodes. It is that a running system can describe itself through the same governed surface by which it can be safely controlled.

That changes the integration model. Intelligence no longer has to be embedded inside every application through a bespoke assistant. It can become attachable to any application that exposes stable identity, bounded context, declared authority, semantic actions, and verified consequences.

I also learned that receipts should not be a detached audit log. A receipt can be part of the same semantic graph that explains the resolver, policy gate, directive, observer, database, source, and tests that produced it. The system can become a window into its own live runtime.

Current boundary and what's next

The semantic continuity loop, fail-closed action boundary, hash-bound human gate, and observed-effect receipts are implemented and demonstrated.

Policy classification is intentionally narrower. This release permits one exact seeded classification proposal for the reference incident and denies every other classification request. It proves the enforcement lifecycle; it is not presented as a general policy classifier.

The next conformance level is a repository-controlled registry of versioned policy vocabularies. Deterministic policy packs will match normalized, application-owned facts, preserve deny precedence, require declared grounding, and bind the matched policy version into each proposal and receipt. From there, the architecture can expand into production adapters, conformance tooling, drift detection, organizational governance, and managed semantic continuity across many running systems.

Links

Built With

Share this project:

Updates