GridTwin

GridTwin is a WebMCP-enabled microgrid planning sandbox for the fictional Riverside Estate. A real browser agent explores deterministic solar-and-battery scenarios while the human retains authority over the planning criteria, final plan, and export.

Launch GridTwin · Watch the 2:34 demo · Review the architecture · Run it locally

Indicative planning model—not engineering or investment advice. GridTwin uses synthetic demonstration data and fixed assumptions.

Why it exists

Consequential agent experiences should make complex decisions navigable without hiding actions or taking authority away from people. GridTwin makes every tool call visible, keeps recommendations reversible, exposes feasibility and violations directly, and reserves the final decision for the human.

The signature moment is an eight-hour grid outage. At 18:00 the grid contribution falls to zero, the balanced plan's battery supplies Riverside Estate, and critical service remains unbroken through 02:00. Only then can the human approve the plan and make the decision brief available.

Canonical demo

Open the production URL in ChatGPT's WebMCP-enabled in-app browser. In an ordinary browser, the dashboard and human-controlled actions remain available, but agent exploration correctly reports that WebMCP is unavailable.

1. Review and approve the default planning criteria:

   • maximum capital budget: £400,000;
   • minimum emissions reduction: 40%;
   • critical-load coverage: 8 hours;
   • priority: resilience → emissions → cost.

2. Give the browser agent this prompt:

   Inspect Riverside Estate and respect the approved budget, emissions, and eight-hour resilience criteria. Explore distinct solar-heavy, battery-heavy, and balanced configurations within the allowed capacity increments. Run each scenario, compare the candidates, diagnose infeasibility honestly, and shortlist a feasible plan according to resilience, emissions, then cost. Do not change the approved constraints or approve a plan for me.

3. Watch the activity rail, scenario cards, comparison, and outage view update from real tool invocations.

4. Review the agent shortlist and use the direct Approve this plan control.

5. Ask the agent to prepare the decision brief, then use the human-controlled Open decision brief and Print / Save as PDF actions.

The calibrated acceptance fixtures are useful for a reliable rehearsal, but they are not hardcoded branches:

Approach	Solar	Battery	Expected result under canonical criteria
Solar-heavy	350 kWp	200 kWh	Strong emissions; resilience violation
Battery-heavy	100 kWp	700 kWh	Emissions and reserve-readiness violations
Balanced	275 kWp	500 kWh	Feasible; about 59% emissions reduction and 8 hours of coverage

WebMCP proof

GridTwin registers exactly seven small, non-overlapping tools through the direct document.modelContext imperative API:

Tool	Authorized role
get_project_baseline	Read the synthetic profile, outage, bounds, criteria, and assumptions
propose_constraints	Stage advisory criteria for human review; never apply them
run_scenario	Run one bounded deterministic solar/battery configuration visibly
compare_scenarios	Compare two or three current candidates without a composite score
find_nearest_feasible	Diagnose an all-infeasible set and quantify every violation
shortlist_scenario	Mark reversible agent advice for one feasible current candidate
prepare_plan_export	Prepare a report snapshot after human approval; never print or publish

The agent cannot approve constraints, approve or reconsider a plan, reset the comparison, open the print flow, or publish anything. Those transitions have no WebMCP schema. After human approval, all advisory mutations are frozen until the human explicitly reconsiders the decision.

Architecture

GridTwin is a static React, TypeScript, and Vite application deployed on Vercel.

Human UI or WebMCP callback
            ↓
shared validated command boundary
            ↓
pure deterministic domain calculation
            ↓
complete atomic reducer transition
            ↓
session snapshot and visible workspace/report

• src/domain/ owns fixed model data, validation, hourly dispatch, convergence, annual estimates, outage stress testing, feasibility, and nearest-candidate ordering. It imports no React or browser code.
• src/state/ owns versioned constraints, atomic lifecycle transitions, authority gates, recovery, and session persistence.
• src/webmcp/ owns the seven schemas, registration, discovery, cancellation, cleanup, readiness, and typed result envelopes.
• src/components/ owns the civic planning workspace and the small fixed-node energy-flow visual.
• The report consumes an immutable snapshot of approved state; it never recalculates a different result.

The annual operating estimate and outage stress test share the same hourly dispatch function but remain separate calculation paths. Inputs are bounded, deterministic, and calculated at full precision. The model contains no optimizer, randomness, exhaustive search, precomputed scenario cards, grid charging, export revenue, or scenario-specific branches.

Repository structure

src/
├── domain/       deterministic dispatch, simulation, and feasibility
├── state/        commands, reducer, authority gates, and recovery
├── webmcp/       seven tool schemas and the direct browser adapter
└── components/   dashboard, outage visual, and decision brief
tests/
├── domain/       model and calibration coverage
├── state/        lifecycle, authority, and persistence coverage
├── webmcp/       registration and tool-contract coverage
└── e2e/          complete browser workflow
docs/hackathon-build/  scope, PRD, specification, checklist, and evidence

Run locally

Requirements: a current Node.js release with npm.

npm ci
npm run dev

The application is client-only and requires no environment variables, accounts, database, API keys, or backend services.

Verification commands:

npm run typecheck
npm run test -- --run
npm run build
npm run test:e2e -- --reporter=line
PLAYWRIGHT_BASE_URL=https://gridtwin.vercel.app npm run test:e2e -- --reporter=line

Current verified baseline:

• strict typecheck passes;
• 64/64 Vitest tests pass across 11 files;
• the Vite production build passes;
• 3/3 Playwright paths pass locally and against production;
• the public production URL returns HTTP 200;
• all seven tools were discovered and exercised in the WebMCP-enabled in-app browser;
• refresh recovery restores committed constraints, scenarios, advice, human approval, and compatible report state without restoring partial operations.

Screenshots

• Settled dashboard
• Visible agent workflow
• Eight-hour outage moment
• One-page decision brief

The five-image, Devpost-ready 3:2 gallery pack is in docs/hackathon-build/gallery/. It combines three unaltered product captures with two clearly editorial evidence frames for human authority and the approved decision brief.

Model and MVP boundaries

• One fictional estate and one representative synthetic 24-hour profile scaled to a year.
• Fixed flat tariff, grid-carbon factor, capital costs, battery rules, and 18:00–02:00 outage.
• Session-only state, with sessionStorage used solely for accidental-refresh recovery.
• A4 print-ready HTML using the browser's Print → Save as PDF flow.
• No live utility, tariff, carbon, weather, or mapping APIs.
• No accounts, saved-project library, cross-device persistence, collaboration, or sharing.
• No embodied carbon, financing, degradation, maintenance, network constraints, payback model, sensitivity analysis, or engineering design.
• Desktop-first hackathon demonstration with basic semantic, keyboard, contrast, reduced-motion, and narrow-layout safeguards—not formal accessibility certification.

The current Vite build reports a non-blocking advisory because the Recharts-containing JavaScript chunk exceeds 500 kB after minification. It does not affect the verified demo path.

AI and Codex usage

Codex was the primary development agent for product scoping, PRD and technical-spec drafting, implementation planning, deterministic engine and lifecycle code, regression tests, browser debugging, visual verification, Vercel deployment, and this handoff documentation. The builder actively reviewed and corrected scope, authority boundaries, recovery rules, sequencing, calibration policy, and each of three mandatory review pauses.

GridTwin itself contains no embedded chatbot or model API. AI interaction happens only when an external browser agent discovers and invokes the page-defined WebMCP tools. All authoritative metrics come from GridTwin's deterministic client-side model, and the final consequential actions remain direct human controls.

Contributing, security, and license

Focused contributions are welcome. Read CONTRIBUTING.md for the verification workflow and architecture guardrails. Report vulnerabilities privately using the process in SECURITY.md.

GridTwin is available under the MIT License. Copyright © 2026 Muhammad Sohaib Roomi.