An open platform for AI-driven hydrological research. Describe your intent — the agent delineates watersheds, retrieves streamflow, calibrates models, and builds reproducible provenance. Community-extensible via MCP.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Built on Cline's proven agent loop (Apache 2.0), specialized for hydrology and earth science research. The agent core is Cline; the domain layer — tools, session memory, provenance, and the Python backend — is AI-Hydro.
The Vision
Hydrological research today involves a fragmented cycle: downloading data from scattered federal APIs, wrangling formats, writing processing scripts, calibrating models, and documenting provenance — often spending more time on plumbing than on science. As foundation models become increasingly capable at reasoning over scientific problems, there is an opportunity to fundamentally change how computational hydrology is done.
AI-Hydro is a platform that bridges this gap. It puts foundation models (Claude, GPT-4, Gemini, and others) at the centre of the research workflow and gives them direct access to production-quality hydrological and geospatial tools — not as a chatbot that generates code you then debug, but as an intelligent agent that orchestrates real computations, remembers context across sessions, and adapts its approach when built-in tools fall short by writing standalone scripts leveraging the latest scientific Python ecosystem.
The platform ships with a growing set of built-in tools — from USGS watershed delineation to differentiable HBV-light calibration — but the long-term vision is much larger: a community-driven ecosystem where researchers contribute domain-specific tools (flood frequency analysis, sediment transport, groundwater modelling, remote sensing workflows) that any AI agent can discover and compose into novel research pipelines. Through a simple plugin system, any Python package can register tools that become immediately available to every AI-Hydro user.
This is what the future of computational hydrology and geospatial sciences looks like: researchers describe their intent, and intelligent agents assemble the right data, methods, and models to get it done.
What AI-Hydro Can Do
1. Automated Research via Built-in Tools
When a tool exists for the task, the AI calls it directly — no code generation, no copy-paste, no debugging. Results come back structured and cached.
You: "Delineate the watershed for USGS gauge 01031500, fetch 10 years of
GridMET forcing, and calibrate a differentiable HBV model."
AI-Hydro: [calls delineate_watershed -> fetch_forcing_data -> train_hydro_model]
Watershed: 769 km², Piscataquis River ME
HBV calibration complete: NSE = 0.638, KGE = 0.644
The AI chains multiple tools in a single conversation — delineation, data retrieval, signature extraction, model calibration — building on each step's results.
2. Standalone Script Generation When Tools Don't Exist
AI-Hydro isn't limited to its built-in tools. When the task requires something outside the current toolkit — a custom statistical analysis, a novel visualisation, a niche data format conversion — the AI writes and executes standalone Python scripts, leveraging the full scientific Python ecosystem (NumPy, SciPy, xarray, rasterio, PyTorch, and beyond).
You: "Run a Mann-Kendall trend test on the annual peak flows and plot the
results with a Sen's slope overlay."
AI-Hydro: [writes and runs a standalone script using pymannkendall + matplotlib]
Mann-Kendall p = 0.023 (significant), Sen's slope = -1.2 m³/s per year
Plot saved to session.
This dual capability — structured tools for common tasks, freeform scripting for everything else — means AI-Hydro adapts to the full breadth of research needs.
3. Community-Extensible Tool Ecosystem
AI-Hydro is designed as a platform, not a closed product. Any researcher can package domain-specific tools and make them available to the entire community:
# In your package's pyproject.toml
[project.entry-points."aihydro.tools"]
flood_frequency = "my_package.tools:flood_freq_tool"
sediment_yield = "my_package.tools:sediment_tool"
Install the package, restart the server, and those tools are immediately available to every AI model connected to AI-Hydro. We envision a growing ecosystem of community-contributed tools spanning:
Flood frequency and extreme event analysis
Groundwater modelling and well analysis
Water quality and nutrient cycling
Snow hydrology and glaciology
Hydraulic modelling and flood mapping
Remote sensing-derived hydrology workflows
See the Plugin Guide to contribute a tool or knowledge plugin, or go directly to the Contributing Guide for the full contribution workflow.
Built-in Tools
Category
Tools
Watershed
delineate_watershed, delineate_watershed_from_point — NHDPlus delineation from USGS NLDI
Streamflow
fetch_streamflow_data — USGS NWIS daily discharge
Baseflow
separate_baseflow — Lyne-Hollick + Eckhardt recursive filters with BFI interpretation
50+ built-in tools. Call list_available_tools() for the live count on your installation. See the Tools Reference for full parameters, examples, and return schemas.
Key Capabilities
Research Session Memory
Every tool result is cached in a HydroSession (JSON per gauge). Expensive computations — watershed delineation (~10s), multi-year streamflow downloads (~5s) — are done once and reused across conversations, days, or weeks. The session tracks provenance so you can export a methods paragraph for your paper.
A pure-PyTorch differentiable HBV-light is built in:
12 physically-meaningful calibrated parameters
Multi-restart Adam optimiser with cosine annealing
Automatic CAMELS streamflow via pygeohydro for 671 CONUS gauges
Typical performance: NSE 0.55-0.80
Interactive Map Panel
Every analysis result appears on a live map inside VS Code — no external GIS tool needed.
Auto-push from tools — delineate_watershed pushes the catchment polygon and gauge point automatically; compute_twi and create_cn_grid push colour-mapped raster tiles
8 file formats — drag any GeoJSON, KML, KMZ, GPX, Shapefile (.zip), GeoTIFF, TopoJSON, or CSV onto the map to load it instantly
Agent layer control — the agent can update colours, opacity, class breaks, and choropleth symbology on existing layers via map_update_layer and map_apply_symbology, without duplicating files
Symbology editor — per-layer fill/stroke/opacity and colormap controls inline in the layer panel
13 free basemaps — USGS Imagery, USGS Topo, Esri Hillshade, Esri Ocean, Carto, Stadia, and more; no API token required
Persistent workspace — basemap, view state, and layer visibility are saved across VS Code sessions
HTML Preview — Built-in Python Kernel
A Jupyter-like execution environment embedded directly in VS Code, purpose-built for AI-generated interactive artifacts.
Executable Python cells — click Run ▶ to execute cells; kernel state persists across runs
Auto-open — any HTML file containing the AI-Hydro module manifest opens automatically when the agent writes it
Interactive learning modules — the interactive-module-builder skill produces fully-branded modules with prose, Python cells, JS visualisations, quizzes, peer-reviewed citations, and provenance footers
Animated kernel status chip — colour-coded pill shows Ready (green) / Busy (pulsing blue) / Dirty (amber + ✎) / Error (red) at a glance
Per-artifact kernel isolation — each module gets its own kernel session; variables do not leak between artifacts
Skills — Workflow Playbooks
The agent discovers and follows domain-specific workflow playbooks before planning any multi-step task.
Mandatory pre-flight — before creating any artifact or running a multi-step analysis, the agent calls list_skills() and loads the matching skill
Marketplace — browse and install community-contributed skills from github.com/AI-Hydro/Skills in the VS Code Skills panel
Agent-created — after novel workflows, the agent saves new skills automatically via save_skill()
Governing contracts — skills encode exact format requirements, checklist gates, and quality standards the agent must follow
Authenticated links to external data services, managed through the VS Code Connectors panel.
Google Earth Engine (live) — OAuth-authenticated access to the GEE public catalog; extract NDVI, ET, precipitation, and any other band over your study area; render layers on the Map panel via gee.preview_layer
Secure credential storage — credentials encrypted in VS Code secret storage; never written to plain-text config files
Model Context Protocol (MCP)
All tools communicate via the Model Context Protocol — an open standard for connecting AI models to external capabilities. This means AI-Hydro tools work with any MCP-compatible client, not just the bundled extension.
Works with Any AI Provider
Provider
Recommended model
Anthropic
Claude Sonnet 4.6 / Opus 4.6
OpenAI
GPT-5.4
Google
Gemini 3.1 Pro / 2.5 Flash
AWS Bedrock
Claude on Bedrock
Ollama / LM Studio
Local models
Installation
pip install aihydro-tools[all]
This installs all hydrological tools and the aihydro-mcp server command. The extension auto-detects it on startup.
