# GeoSQL

> An open-source AI skill for Claude, Codex, and GitHub Copilot that turns them into geospatial analytics agents for PostGIS, BigQuery, Snowflake, and Wherobots.

GeoSQL is an open-source Python package that installs as a skill into Claude, Codex, or GitHub Copilot, enabling those agents to perform geospatial analytics against PostGIS, BigQuery, Snowflake, and Wherobots. It runs entirely locally or self-hosted — no SaaS account is required. The project is maintained by dekart-xyz under the MIT license and has accumulated 382 stars on GitHub since its April 2026 creation.

## What It Is

GeoSQL is an agent skill (also described as a plugin) that gives AI coding assistants the ability to discover warehouse schemas, write spatial SQL, validate geometry, and render interactive maps — all within a single agentic loop. It is not a standalone application; it extends existing agents like Claude Code, GitHub Copilot in VS Code, or OpenAI Codex with geospatial reasoning capabilities. The core loop is designed around "map in the loop": the agent renders query results through Dekart (an open-source Kepler.gl backend), inspects the rendered map image, and self-corrects geometry mistakes that a text-only validation pass would miss.

## How the Agent Loop Works

GeoSQL structures its work into five stages:

- **Discovery** — explores warehouse metadata (tables, columns, types) rather than guessing schemas; supports Overture Maps shares on BigQuery and Snowflake, plus private tables on PostGIS, BigQuery, Snowflake, or Wherobots.
- **SQL generation** — writes engine-appropriate spatial SQL using functions like `ST_INTERSECTS`, `ST_DISTANCE`, H3 indexing, and bbox overlap for partition pruning.
- **Cost check** — on BigQuery, every query is dry-run first; a 10 GiB billing cap is enforced by default, and over-budget queries are rewritten with tighter bounding boxes, lower H3 resolution, or additional filters instead of being executed.
- **Geometry validation** — computes total area (polygons) or total length (lines) as a sanity check and cross-references against domain knowledge.
- **Map feedback** — renders results through Dekart, reads the rendered image as a tool call, and corrects visual geometry errors the text-only loop would miss.

The README states this map-in-loop step produces a 4x improvement on geospatial tasks compared to text-only validation.

## Installation and Setup

GeoSQL installs via pip and supports three agent targets out of the box:

```
pip install geosql && geosql
geosql install claude
geosql install codex
geosql install copilot
```

In Claude Code it can also be added through the plugin marketplace. Map rendering and PostGIS connectivity are handled optionally by Dekart, which can be run locally via a single Docker command, self-hosted, or accessed through Dekart Cloud. Warehouse credentials are never sent to the agent — authentication uses local CLI tools (`bq`, `snow`, `dekart`).

## Benchmarks and Eval Suite

GeoSQL ships with a reproducible evaluation suite under `evals/`. Each case asserts specific behaviors — cost guardrails, validation steps, correct results — rather than open-ended "did the agent answer" checks. The included suite currently covers three cases (`london-boroughs`, `berlin-create-map`, `paris-boundaries`) with 8 total assertions, all passing at 100%. Average token usage is reported at 3,085 tokens per turn and 72 seconds per turn. The project welcomes pull requests adding new eval cases.

## Why It Matters for Geospatial Workflows

Traditional AI coding assistants lack awareness of spatial SQL dialects, geometry validation, and the visual feedback needed to catch coordinate-reference-system mismatches or polygon-scale errors. GeoSQL addresses this gap by embedding domain-specific guardrails (cost caps, geometry sanity checks, engine-specific function selection) and closing the loop with rendered map inspection. It targets data scientists and analysts who already use PostGIS, BigQuery, Snowflake, or Wherobots and want to accelerate spatial query development without switching tools.

## Features
- Install as a skill into Claude, Codex, or GitHub Copilot
- Geospatial SQL generation for PostGIS, BigQuery, Snowflake, and Wherobots
- Warehouse schema discovery (tables, columns, types)
- Engine-appropriate spatial SQL (ST_INTERSECTS, ST_DISTANCE, H3, bbox overlap)
- BigQuery cost guardrail with 10 GiB dry-run cap and query rewriting
- Geometry validation via area/length sanity checks
- Map-in-loop feedback via Dekart and Kepler.gl rendering
- Supports Overture Maps shares on BigQuery and Snowflake
- Local CLI authentication (bq, snow, dekart) — credentials never sent to agent
- Reproducible eval suite with assertion-based test cases
- Works 100% locally or self-hosted — no SaaS account required
- Interactive Python mode (geosql command)
- Docker-based local Dekart setup for map rendering

## Integrations
Claude, Claude Code, OpenAI Codex, GitHub Copilot, VS Code Copilot, PostGIS, BigQuery, Snowflake, Wherobots, Dekart, Kepler.gl, Overture Maps, Docker

## Platforms
CLI, API, VSC_EXTENSION, DEVELOPER_SDK

## Pricing
Open Source

## Links
- Website: https://github.com/dekart-xyz/geosql
- Documentation: https://github.com/dekart-xyz/geosql/blob/main/evals/RUNBOOK.md
- Repository: https://github.com/dekart-xyz/geosql
- EveryDev.ai: https://www.everydev.ai/tools/geosql