OpenState

OpenState gives developers human-approved, hash-bound control over Codex changes—from plan to accepted Git commit.

Comment

Inspiration

As autonomous AI agents become more powerful, they increasingly operate as "black boxes." When an agent attempts a complex multi-file task, a single wrong assumption in step 1 can quietly cascade into hours of debugging broken code across the entire codebase.

We were inspired to build OpenState to bridge the gap between autonomous AI speed and developer trust. Instead of letting agents run unsupervised, OpenState creates a transparent workspace where agents must lay out their architectural plan in an auditable file and pause for explicit developer approval before executing any code.

What it does

OpenState is a transparent, human-in-the-loop multi-agent developer workspace:

  • Architect Agent (GPT-5.6): Parses high-level user requests and writes a multi-step execution plan into a plain-text PLAN.md file.
  • Deterministic Execution Gates: Execution automatically pauses at each step, allowing developers to inspect, edit, or steer the plan directly from the UI checklist.
  • Coder Agent (Codex): Executes targeted code changes only after the human developer approves the active step.
  • Live Diff & Observability: Displays side-by-side git diffs in real time as each approved step is written to disk.

How we built it

We built OpenState around a zero-database, file-based state machine (PLAN.md) acting as the single source of truth:

  • GPT-5.6: Serves as the system architect, generating execution plans structured with YAML frontmatter to track global execution state $S_t$.
  • OpenAI Codex: Operates as the targeted code synthesis engine for individual steps.
  • Frontend: Built with Next.js, Tailwind CSS, and @monaco-editor/react for side-by-side code diffing.
  • Backend: Node.js server using file watchers (chokidar) and Server-Sent Events (SSE) to stream file modifications to the browser in real time.

Challenges we ran into

  • State Synchronization: Guaranteeing real-time synchronization between disk file writes (PLAN.md), background model API responses, and the frontend UI state without introducing race conditions.
  • Prompt Schema Constraints: Engineering system prompts for GPT-5.6 to ensure it strictly outputs valid YAML frontmatter and markdown checklists without conversational fluff.
  • Scoped Agent Execution: Constraining the Coder Agent so that it strictly modifies only the specific target files declared in the approved step, preventing unintended side effects across the repository.

Accomplishments that we're proud of

  • Zero-Database Overhead: Successfully built an entire multi-agent orchestration state machine driven completely by a plain-text, Git-friendly PLAN.md file.
  • True Human Steerability: Built a fluid UI that allows developers to edit AI plan steps mid-flight before any code is generated.
  • Sub-Second Feedback Loop: Integrated real-time SSE streaming to render live code diffs the moment Codex finishes writing a patch.

What we learned

  • Human-in-the-Loop Unlocks Trust: AI coding tools are significantly more reliable when developers can review and edit the architectural logic before code generation begins.
  • Plain-Text State Machines: Storing execution state in a human-readable markdown file provides instant observability and native version control compatibility out of the box.

What's next for OpenState

  • VS Code Extension: Bring the OpenState plan editor directly into the IDE sidebar so developers never have to leave their primary editor.
  • Automated Testing Gates: Automatically run local test suites (e.g., jest or pytest) at each step boundary before requesting human approval.
  • Multi-Repo Support: Expand the Architect Agent's context window to plan cross-repository microservice changes simultaneously.

Built With

Share this project:

Updates