GeoSQL: putting a map inside a coding agent's loop

A skill package, not a library you call

GeoSQL describes itself as a skill for Claude Code, Codex, GitHub Copilot, OpenCode and Mistral Vibe, aimed at data scientists and analysts who work with geospatial data on PostGIS, BigQuery, Snowflake and Wherobots. The delivery mechanism matters. There is no API for your application to call. What ships is an installer that copies a set of instructions, a skill file and reference documents into whichever agent it detects, and from that point the agent, not your code, drives the analysis. The packaging confirms this: the project description in the manifest is Install GeoSQL instructions into local AI CLIs, the console script is geosql = "geosql.cli:main", and the wheel force-includes the skill file and its references so the installed CLI can read them from its own package directory. If you wanted a Python function that returns a GeoDataFrame, this is not it. If you wanted your agent to stop guessing table schemas, it may be what you need.

Five steps: discovery, SQL, cost, validation, map

The documented loop has five stages. Discovery comes first: the skill explores your warehouse metadata, tables, columns and types, rather than guessing schemas, which works with Overture Maps shares on BigQuery and Snowflake and with private tables on PostGIS, BigQuery, Snowflake or Wherobots. The agent then writes spatial SQL using the functions appropriate to the engine, naming ST_INTERSECTS, ST_DISTANCE, H3 and bbox overlap for partition pruning. After that comes a cost check, a geometry validation and a map feedback step, which the project calls the loop that produces the claimed four times improvement. The last stage is the interesting one: the agent renders the result through Dekart, looks at the rendered image, and corrects geometry mistakes that a text-only loop would miss. The README names the classes of error that text-only validation misses, such as mistaking a neighbourhood polygon for a metro-area perimeter, double-counting overlapping features, or picking the wrong join key on coordinate reference systems.

A 10 GiB default cap on BigQuery scans

The cost check is specific rather than advisory. On BigQuery every query is dry-run first to estimate the bytes scanned, and a 10 GiB billing cap is enforced by default. A query over the budget is not executed. Instead it gets rewritten cheaper, with a tighter bounding box, a lower H3 resolution, or more filters, and the rewritten form is what runs. That design has a consequence worth naming: the shape of your query changes depending on its cost, so a result can depend on the budget rather than only on the question. It also means a legitimately large scan, a full national extract for instance, will not simply run. No comparable default is documented for the other warehouses, and the stage list says the cost check applies on BigQuery, so behaviour on PostGIS, Snowflake and Wherobots is a question the documentation leaves open.

Warehouse credentials never reach the agent

The security model is the part of the design most likely to decide adoption. GeoSQL uses your local CLI authentication, naming bq, snow and dekart, so warehouse credentials never go to the agent. The agent issues commands through the same tools you would use from a terminal, and the credentials live in the environment where those CLIs already keep them. The project also states that no SaaS account is needed and that it works entirely locally or self-hosted. Taken with the cost cap, the picture is a tool that is deliberately conservative in both directions: it will not spend your warehouse budget without asking, and it will not hand your keys to a model. The one network behaviour it does document is a version check, described in a separate section of the README and covered below.

Installing the skill and prompting the agent

The install path is a single pip command that starts the interactive installer:

pip install geosql && geosql

The installer first writes the skill into the agent it detects, then checks whether the optional Dekart CLI is ready and, only when that is needed, asks before installing or initialising it. The prompt shows the exact commands and defaults to the recommended option, so nothing is installed silently. After that, a geospatial question is a slash command in the agent, for example:

/geosql Show EV charger density along major roads and render a map

The README offers more prompts in the same shape, covering real estate accessibility in Ottawa, site selection for a Sporting Goods Store in Seattle based on point of interest co-location and distance to the nearest competitor, and EV charging density along major Romanian roads. Updating is a matter of upgrading in the environment where GeoSQL lives and rerunning the installer so the newest skill and references are copied:

pip install --upgrade geosql

If you use the optional Dekart CLI, it is upgraded separately with pip install --upgrade dekart, and then the geosql command is run again.

The accuracy claim rests on three eval cases

The project ships a reproducible eval suite under evals/, and each case asserts specific behaviours such as cost guardrails, validation steps and a correct result, rather than only checking that the agent answered. The published results cover three cases: london-boroughs with four assertions, berlin-create-map with three, and paris-boundaries with one, for eight assertions in total and a reported pass rate of 100 percent. The README also gives the cost of a turn, an average of 3,085 tokens and 72 seconds. You can run the same suite yourself with:

python evals/run.py

Setup instructions and how to add cases live in evals/RUNBOOK.md, and pull requests with new evals are welcomed. Judged on its own terms this is a small suite, and the four times improvement figure is a comparison of the same task set with and without the map-in-loop step rather than a measurement against other tools. The honest reading is that the project demonstrates the mechanism works and gives you a way to check it yourself, which is more than most agent tooling offers, but three cases cannot establish generality.

Telemetry, versioning and the skill packaging

Two housekeeping details decide whether you can install this without thinking about it. The first is telemetry. GeoSQL sends a best-effort version check carrying the package version and an opaque random installation ID, and GeoSQL and the Dekart CLI share that ID, stored at ${XDG_CONFIG_HOME:-~/.config}/dekart/installation_id. Deleting that file resets the identifier, and setting DO_NOT_TRACK=1 or DNT=1 disables the check before an ID is created. Continuous integration sends a reserved non-persisted test ID. The second is versioning: the manifest declares version 0.38.0 and requires Python 3.8 or newer, the licence is MIT, and the repository has no GitHub releases, so the only version reference is the manifest itself. The last push to the default branch was on 2026-10-09. The build also exposes an isolated shell through the Makefile, with targets that hide the warehouse CLIs from the agent so you can test what happens when only Dekart or only bq is present.

Editorial conclusion

GeoSQL suits analysts and data scientists who want an agent to query a spatial warehouse and produce a map without handing warehouse credentials to a model, and who can tolerate a package that installs instructions into their editor. It is the wrong tool if you need a library you call from your own code, or if a BigQuery job might legitimately scan more than 10 GiB, because the default cap rewrites or blocks it. Before adopting it, read the three eval cases under evals/ and the runbook, then check the telemetry setting, since a best-effort version check with a stored installation ID is sent unless DO_NOT_TRACK=1 is set.

Frequently asked questions

Official sources

1. dekart-xyz/geosql on GitHub
2. Issues
3. License: MIT
4. README