GaIAecho

🌍 GaIA Echo

When the DANA hit Valencia in October 2024, the early-warning protocols failed. 230 people died.

GaIA Echo replays that catastrophe — and four others — frame by frame on real ERA5 reanalysis fields, with Claude Opus 4.7's adaptive thinking visible at every step. It is a climate-forensics cockpit where the model narrates what happened, audits its own answers when challenged, and never cites a number that did not come from data on disk.

🔗 Live demo: https://echo.gaiapp.es 🏆 Submission: Built with Opus 4.7 Hackathon · April 2026 🎬 Demo video: https://www.youtube.com/watch?v=lRMluo9EVcM

Three things to try in 60 seconds:

1. Open Forensic › DANA Valencia 2024, scrub the timeline to phase 6, watch Opus reason over the convergence collapse.
2. Open ECHO (⌘/Ctrl+K) on any surface, ask "¿Fue el DANA Valencia 2024 más fuerte que la peor hora de lluvia en Pakistán 2022?" — when the model overstates, follow up "¿estás seguro? revísalo" and watch it emit a ### Correction block instead of doubling down.
3. Open this repo in Claude Code — two bundled Skills load automatically and let any agent answer quantitative forensic questions or author NOAA-CPC-style ENSO briefings without inventing a single number.

---

🎯 What is GaIA Echo?

Climate science speaks in NetCDF, ERA5 grids and Hovmöller diagrams. The public speaks in headlines. GaIA Echo collapses that gap by letting Claude Opus 4.7 narrate real catastrophes in real time, with the model's own reasoning trace exposed alongside maps, timelines and 3D atmospheric volumes.

It is not a chatbot wrapped around a weather API. It is a multi-mode analysis cockpit where:

• Every screen ships its own scoped agent with its own system prompt and toolset.
• Every visualization is grounded in real data on disk — no mocked numbers, no hallucinated statistics.
• The model's adaptive thinking is visible at every step, reinforcing trust in a domain (climate forensics) where black-box answers are unacceptable.
• A unified conversational analyst (ECHO) sits on top of all four modes, reading the active screen's context and answering in natural language.

---

✨ Why this project stands out

🎨 Visual design as a first-class citizen

Most data tools look like Bloomberg terminals from 1998. GaIA Echo looks like the cockpit of a climate-monitoring satellite:

• Custom dark glass / cyan-glow design system built from scratch in Tailwind 4 — no UI kit, no template.
• Cinematic forensic mode: timeline scrubber, animated wind-vector overlay, contour-line pressure isobars, climate dial, phase context strip — all synchronized to the model's narration.
• 3D atmospheric volume rendered with Three.js (surface, 850, 500 and 250 hPa layers).
• Bilingual EN/ES down to the system prompts the model receives — not just UI strings.
• Inline SVG icon registry built specifically to dodge a known React 19 + Turbopack hydration regression in popular icon libraries.

🧠 Visible reasoning, not hidden chains of thought

Every Opus response on every surface exposes its summarized adaptive thinking in a collapsible panel. In a domain where "what does the model know?" matters as much as "what did it say?", this is the right default.

♻️ Self-correction by design

ECHO's system prompt instructs the model that changing its mind when challenged is a feature, not a failure. When a follow-up casts doubt on a previous answer, the model re-examines its tool results and — if warranted — emits an explicit ### Correction block (rendered in the UI with a distinct cyan border) acknowledging what it got wrong and why. No sycophancy, no doubling-down. The "I was wrong about X because Y" answer is the most trustworthy signal a forensic tool can produce.

🛰 Real data, end to end

ERA5 reanalysis timelines for five historic events, NOAA ENSO indicators (Niño 3.4, SOI, OLR), region climatologies — all on disk under /data, every number auditable, no API mocks.

🤖 Opus 4.7 with a custom agent loop

ECHO orchestrates Claude Opus 4.7 via an iterative tool-use loop on the public Messages API. Three custom tools give the model read-only access to the underlying ERA5 reanalysis and ENSO state:

• get_phase_data(event_id, phase) — fetches ERA5 grid data for a given forensic phase
• get_enso_state(date) — retrieves ENSO indices at a specific date
• get_event_metadata(event_id) — returns event summary, impacts, and sources

The loop: model emits tool_use → we execute → return tool_result → model continues. Thinking is visible throughout (thinking.summarized). ECHO uses this Messages-API loop because the interactive sidebar needs fine-grained streaming control; Guardian, the long-running scheduler, runs on Claude Managed Agents in production (see below).

We also ship a long-running background scheduler (scripts/guardian-loop.ts, registered under PM2 as echo-guardian) that runs every six hours and emits a fresh briefing into data/enso/briefings/ — not a demo, an actual cadence.

🛠 Managed Agents in production

GaIA Echo's Guardian agent runs on Claude Managed Agents (managed-agents-2026-04-01 beta, model claude-opus-4-7). Every six hours scripts/guardian-loop.ts opens a client.beta.sessions.create call against the agent provisioned by scripts/setup-agents.ts, streams events from client.beta.sessions.events.stream, resolves three custom tools — fetch_latest_indicators, fetch_historic_el_nino, emit_briefing — and persists a markdown briefing to disk.

Every briefing carries the agent_id and session_id in its footer for auditability:

_Generated by Claude Managed Agents · agent agent_011CaLUa7mhZeddcP38NCkHU · session sesn_011CaQBEzBJijYAM833eMgET · 2026-04-25T08:31:25.915Z_

Grep data/enso/briefings/*.md to verify the audit trail. The runtime=managed-agents log line in pm2 logs echo-guardian confirms the dispatcher (GAIA_USE_MANAGED_AGENTS=1) is selecting the Managed Agents runner over the legacy Messages-API path. Both runtimes share the same prompt, custom tools, and output contract (GuardianEvent); flipping the env var to 0 reverts to the legacy loop with zero code changes.

🎲 Live simulation engine

/simulate is a working Monte-Carlo cockpit, not a placeholder. Pick a region, dial a ΔT slider (or open the advanced panel for SST anomaly, MSLP delta, wind and humidity perturbations), and the engine selects historical analogues by similarity, runs a 500-member perturbed ensemble through a first-order physics forward model, then hands the percentile envelope to Opus 4.7 — which writes an AEMET-style operational bulletin in the active locale, streamed live alongside the model's visible thinking. Every run is persisted to data/gaia.db with full inputs, ensemble summary and bulletin; the percentile table, Mapbox cone-of-uncertainty (p05/p25/p50) and bulletin re-render for any saved run.

🗣 Audience-aware terminology

A single audience selector (Public · Researcher · Emergency manager · Student) rewrites the active system prompt and remaps technical terms across every surface — Forensic narration, Guardian briefings, Simulate bulletins and ECHO answers all shift register in lockstep. The terminology dictionary is type-safe and bilingual: a missing translation in any audience × locale × term combination is a TypeScript compile error, not a runtime fallback. Same data, four registers, zero loss of fidelity.

🏗 Production-grade engineering

• Standalone Next.js 16 build, TypeScript strict mode end-to-end.
• Zero-downtime deploys via PowerShell junction-swap script (scripts/deploy.ps1 → releases/<timestamp>/).
• PM2 + Caddy on a Windows VPS, live at https://echo.gaiapp.es.
• Type-safe i18n: missing a translation in either locale is a TypeScript error.
• Resilient transcript hydration: messages stuck in streaming from a crashed tab auto-sanitize on reload.

---

🧭 The Modes

Mode	Route	What it does
🕵️ Forensic	/forensic/[eventId]	Replays a historical disaster (DANA Valencia 2024, Helene 2024, Pakistan 2022, Australia 2019‑20, Europe heatwave 2022) frame by frame. Claude analyzes each timeline phase, generates counterfactuals and overlays wind / pressure / precipitation fields on Mapbox.
🌊 Guardian	/guardian	Live ENSO watchdog. Pulls Niño 3.4, SOI, OLR and Walker indicators; Opus 4.7 issues briefings on whether we're drifting toward El Niño or La Niña.
🎲 Simulate	/simulate	Monte Carlo + analog-based forward projection. Pick a region, year and forcing scenario; Claude reasons over stochastic trajectories and returns a narrated probability envelope.
💬 ECHO	everywhere above	Conversational analyst drawer (⌘/Ctrl+K). Reads the current screen's context and answers questions in natural language with Opus 4.7's reasoning visible.

---

💬 ECHO — the Conversational Analyst

ECHO is the conversational layer that ties the rest of the cockpit together — it reads the active screen's context and answers questions over the same on-disk data the other surfaces show.

• Scoped, not general-purpose. A scope guard rejects anything outside atmospheric science / climate physics. ECHO will not write you a poem.
• Bilingual. Replies in EN or ES based on the gaia_locale cookie. The system prompt is dynamically wrapped per request.
• Three custom tools invoked through the iterative tool-use loop:
  1. get_phase_data — pulls the timeline window currently visible on screen.
  2. get_enso_state — fetches the live indicator snapshot from Guardian.
  3. get_event_metadata — resolves the catalog entry for the active forensic event.
• Visible thinking with thinking: { type: "adaptive", summary: "summarized" } and high effort.
• Streaming with cancellation. Navigating away aborts in-flight calls cleanly; reload sanitizes any orphan stream.
• Suggestion chips contextual to the active surface — first-time users have a one-click way in.
• Keyboard-first. ⌘/Ctrl+K toggles from anywhere; Esc closes; Enter sends.

---

🧩 Use with Claude Code — bundled Skills

This repo ships two Anthropic Skills in .claude/skills/. When you open this repository in Claude Code, both load automatically — no setup, no API call, no upload.

Skill	What it does	Try asking
gaiaecho-forensics	Computes peak metrics (precip, wind, MSLP) and ±°C Clausius–Clapeyron counterfactuals over the 5 bundled ERA5 events.	"What was the peak rainfall hour in DANA Valencia 2024?" · "Compare DANA vs Helene."
enso-briefing-author	Authors a NOAA-CPC-style ENSO briefing in the project's "El Niño Guardian" voice — same format the live agent emits every 6 h.	"Write an ENSO briefing from data/enso/indicators.csv."

Both skills enforce the project's hard rule: never invent a number. Every value cited must come from a tool result or a bundled file; missing indicators are returned as the literal string "not available in this run".

The gaiaecho-forensics skill includes a self-contained Python script (compare_events.py) that reads the ERA5 phase grids in data/events/ and returns compact JSON — so the model never has to load multi-megabyte timelines into context to answer a quantitative forensic question.

---

🔌 Connect to GaIA Echo from Claude Desktop (MCP)

GaIA Echo ships a public Model Context Protocol server at https://echo.gaiapp.es/mcp. Plug it into Claude Desktop and the model gains five forensic-grade tools (compare_events, get_phase_data, get_event_metadata, get_latest_enso_briefing, simulate_counterfactual) plus three resources (events://catalog, events://{id}/timeline, briefings://latest) — every value backed by the same on-disk ERA5 + ENSO data the web cockpit uses, no API keys required.

The browseable, copy-pastable version of this section lives at https://echo.gaiapp.es/mcp.

✅ Recommended — One-click via Claude Desktop UI

Claude Desktop ships a native UI for adding remote MCP servers. No config file, no Node, no npm.

1. Open Claude Desktop.
2. Click the + icon in the chat composer (or open Settings → Connectors).
3. Choose Add custom connector.
4. Paste this URL: https://echo.gaiapp.es/mcp
5. Click Add. Done — gaia-echo now appears in your connectors with five tools and three resources.

Alternative — Manual config via mcp-remote

If you prefer to edit claude_desktop_config.json directly, note that the config file only supports local stdio servers — "type": "http" is not valid there. To bridge a remote Streamable-HTTP MCP server like ours, use the official mcp-remote shim. Requires Node.js (npm) on your machine.

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

If the file does not exist yet, create it. If mcpServers already exists, just add the gaia-echo entry inside it.

{
  "mcpServers": {
    "gaia-echo": {
      "command": "npx",
      "args": ["mcp-remote", "https://echo.gaiapp.es/mcp"]
    }
  }
}

Fully quit and relaunch Claude Desktop after saving. The first run of npx mcp-remote will download the bridge package.

Try one of these prompts

1. Cross-event comparison — "Using GaIA Echo, compare DANA Valencia 2024 with Hurricane Helene 2024." (Claude calls compare_events; you see peak precip, peak 10 m wind and minimum MSLP for each.)
2. Live ENSO briefing — "Using GaIA Echo, what does the latest ENSO briefing say?" (Claude calls get_latest_enso_briefing; the answer cites the tool calls in the briefing footer.)
3. Physics-grounded counterfactual — "Using GaIA Echo, what would the peak rainfall hour of the DANA look like in a +1.5 °C world?" (Claude calls simulate_counterfactual with delta_T_celsius: 1.5; reply is Clausius-Clapeyron-grounded, not free speculation.)

What it looks like

[screenshot pending — owner adds after live demo]

Notes for reviewers

• The MCP endpoint speaks Streamable HTTP (stateless mode). GET /mcp from a browser returns the marketing twin at https://echo.gaiapp.es/mcp; MCP clients reach the JSON-RPC server by sending POST /mcp with Accept: application/json, text/event-stream. Caddy routes both correctly off the same hostname using a header-aware matcher.
• Source for the server lives in mcp-server/ (PM2 process gaia-mcp-server on :3007, Caddy reverse-proxies /mcp*). Tools are TypeScript with strict input schemas; simulate_counterfactual is the only one that calls the LLM, the rest are deterministic over the same files served at /api/events/*.
• Every tool result is reproducible from the public REST API: curl https://echo.gaiapp.es/api/events/catalog, curl https://echo.gaiapp.es/api/events/dana-valencia-2024/timeline, etc.

---

Authorship note

This repository was developed solely by me (sxundstorm). Some commits in the git log appear under my secondary GitHub identity "nexo-network" due to local git config during development — both accounts belong to me. The work is single-author per the hackathon rules.

---

🛠 Tech Stack

• AI engine: Claude Opus 4.7 (claude-opus-4-7) via @anthropic-ai/sdk ^0.90, driven through a custom tool-use orchestration loop on the public Messages API.
• Reasoning config: thinking: { type: "adaptive", summary: "summarized" }, output_config: { effort: "xhigh" | "high" } per surface.
• Frontend: Next.js 16.2 (App Router, webpack default; Turbopack opt-in), React 19.2, TypeScript strict, Tailwind CSS 4 with custom glass / glow utilities.
• Visualization: mapbox-gl 3.22 (forensic + guardian maps), bespoke wind-vector and pressure-contour overlays in pure SVG.
• Persistence: better-sqlite3 for the analysis cache (data/cache/analyses.db) and simulation history (data/gaia.db). Event timelines, ENSO indicators and briefings live as flat files under /data so reviewers can audit every number.
• i18n: gaia_locale cookie + withLocale() helper that wraps every Opus prompt + a type-safe dict (~180 keys, EN ↔ ES).
• Icons: Inline SVG registry — avoids the lucide-react@1.8 + React 19 + Turbopack hydration regression.
• Infrastructure: Standalone Next output, served via PM2 behind Caddy on a Windows VPS. Zero-downtime deploys via junction swap.

---

📂 Project Structure

src/
├─ app/
│  ├─ api/                  Route handlers (analyze, simulate, counterfactual, enso, echo/message)
│  ├─ components/
│  │  ├─ echo/              ECHO drawer: Provider, Console, Launcher, Mount
│  │  ├─ home/, shell/      Landing + AppShell
│  │  └─ *.tsx              ForensicMap, ClimateDial, GuardianFeed, ThinkingPanel, …
│  ├─ forensic/[eventId]/   Forensic mode pages
│  ├─ guardian/             Live ENSO watchdog
│  └─ simulate/             Monte Carlo simulation
├─ data/
│  └─ events-catalog.ts     Display metadata for the 5 forensic events
└─ lib/
   ├─ echo/                 Scoped multi-agent: scope.ts, prompt.ts, tools.ts, agent.ts, agent-legacy.ts
   ├─ managed/              Managed Agents runtime (Guardian uses it in production via GAIA_USE_MANAGED_AGENTS=1)
   ├─ prompts/              Per-surface system prompts (forensic, simulation, counterfactual, guardian)
   ├─ simulation/           Monte Carlo + analog forward projection
   ├─ i18n/                 EN/ES dictionary, provider, prompt-locale wrapper
   ├─ anthropic.ts          SDK singleton (custom tool-use loop on the public Messages API)
   ├─ climatology.ts        Region climatology baselines
   ├─ enso-state.ts         ENSO indicator parser
   ├─ physics.ts            Pressure / wind / precip helpers
   └─ phase-context.ts      Builds the per-phase context object passed to Opus

data/                        On-disk truth: event timelines, ENSO indicators, briefings, simulations
public/brand/                Logo + favicons
scripts/                     deploy.ps1, fetch-enso-*, fetch-event-data, smoke tests

---

🏁 Local Development

# 1. Install
npm install

# 2. Environment
$env:ANTHROPIC_API_KEY     = "sk-ant-..."
$env:GAIA_USE_MANAGED_AGENTS = "1"   # Guardian cron uses Claude Managed Agents in production; set 0 to fall back to the legacy Messages-API loop

# 3. Dev (webpack — recommended)
npm run dev

# 4. Production build
npm run build
npm run start

Open http://localhost:3000, pick Forensic › DANA Valencia 2024, hit play on the timeline, then open ECHO (⌘K, or the cyan pill bottom-right) and ask:

"¿Por qué la convergencia de humedad subió tan rápido entre las fases 4 y 6?"

Watch Opus 4.7 think — visibly — over the real ERA5 timeline data on disk.

---

🚢 Deploy (Windows VPS · PM2 · Caddy)

cd c:\GaIAecho
npm install
npm run build
.\scripts\deploy.ps1     # creates releases/<timestamp>, swaps the `current` junction
pm2 restart echo         # PM2 process listening on :3004 behind Caddy

The deploy script keeps the last N releases for instant rollback.

---

🎓 Why this project deserves your vote

• Scope. Five modes, one cockpit, real data, real domain — not a one-trick demo.
• Craft. Custom design system, custom icon registry, custom overlays, type-safe i18n, resilient streaming, zero-downtime deploys. Production-grade across the stack.
• Right use of Opus 4.7. Visible adaptive thinking on every surface, a custom agent loop with three read-only tools, and a long-running background scheduler that exercises that loop on a six-hour cadence.
• Right domain. Climate forensics is hard, important, and a place where a model that shows its work is meaningfully better than one that doesn't.
• It's live. https://echo.gaiapp.es — open it, ask anything.

---

📝 License

MIT — see LICENSE.

---

Built during the Anthropic "Built with Opus 4.7" Hackathon, April 2026. Made with ❤️ and a lot of thinking: { type: "adaptive" }.