Interactive Map Builder

Turn existing spatial data into polished, verified map products with an AI agent.

Live demos · 中文说明 · Releases · Changelog

Interactive Map Builder is a Codex-first Agent Skill for turning GeoJSON, GeoPackage, Shapefile, CSV, Excel, and ArcGIS data into portable map products. The Agent recognizes the goal from ordinary language—even when the user never says GIS, Leaflet, web map, or the Skill name—then inspects the data, closes only blocking requirements gaps, writes an auditable MapSpec, resolves a restrained geometry-aware visual starting point, builds a self-contained Leaflet app, verifies the result, and exports slide or paper figures only when requested.

User intent + spatial data → inspect → confirm → MapSpec → build → verify → HTML + optional PNG/SVG/PDF

No frontend build system, no hand-written Folium page, and no hidden cleanup.

Highlights

• Intent-based activation — recognizes requests such as “make this spreadsheet searchable on a map” or “combine roads, water, green space, and parking in one presentation page.”
• Agent-guided setup — works from the user's question and inspected data instead of requiring GIS terminology up front.
• Deterministic builds — the Agent writes MapSpec 1.1; the Python engine owns loading, normalization, visual resolution, rendering, and validation.
• Atlas Studio Light defaults — omitted visual values are resolved from geometry, coarse density, and layer role so the first result is coordinated without pretending to finish the designer's work.
• Two polished map products — a searchable map-and-list explorer and a toggleable multilayer explorer for points, lines, and polygons.
• Portable local delivery — Leaflet, interface code, and business geometry are embedded in one map.html; only online basemap tiles require a network connection.
• Opt-in report exports — generate 16:9 PNG or publication PNG/SVG/PDF from the same visual plan only when those files are explicitly requested.
• Auditable handoff — every build records inspection results, repairs, generated IDs, performance warnings, source notes, hashes, and portability.
• Cached, non-mutating release preflight — Skill tasks check the official Release at most once per 24 hours, never modify the running installation, and keep offline work unblocked.
• Install self-check — interactive-map-builder doctor runs a complete offline build and hash verification after installation.
• Reliable map controls — multilayer maps open in a neutral overview, use one compact layer selector for search focus, keep visibility switches separate, and provide CARTO Positron, OpenStreetMap Standard, plus a no-basemap fallback.
• Cross-agent evaluation — 40 English and Chinese cases cover activation, optional planning, local-versus-public delivery, and out-of-scope requests.

Live demos

Search, filter, compare	Explore independent layers
Map + list. Search addresses and attributes, filter categories and numeric ranges, sort records, watch KPIs update, and inspect a selected parcel.	Multilayer. Start from a neutral overview, choose one layer to search and emphasize, toggle visibility independently, switch basemaps, and inspect feature details.
Open live demo →	Open live demo →

Both demos are generated by the repository's deterministic engine from fixed NYC Open Data snapshots; they are not separate design mockups.

Ask for the outcome, not the tool

The Skill is designed to activate from requests like these:

This Excel sheet has longitude and latitude. Make a browser page where I can search facilities,
filter by type, click a record, and share the result.

Combine the parcel, road, water, green-space, and parking layers into one planning presentation
map with layer switches and object details.

My colleagues do not have ArcGIS. Turn these existing layers into one HTML file and export a 16:9
figure for the meeting.

The user can still invoke $interactive-map-builder explicitly, but naming the Skill is not required for a matching Agent task.

Quick start

1. Install the Skill in Codex

Open a new Codex task and send:

$skill-installer Install the Skill from https://github.com/xlbaoxl/interactive-map-builder and install its Python dependencies. Run interactive-map-builder doctor and interactive-map-builder update --preflight after installation.

Create a new task after installation. Restart Codex once only when the Skill does not appear. Starting with v0.4.3, a repository-copy install can become update-managed automatically only when all Release-owned files exactly match the checksum-verified official package.

2. Attach spatial data and describe the result

Turn my attached spatial data into a searchable, filterable interactive map. Use English for the map audience and export a 16:9 presentation figure.

The Skill first inspects the inputs, then keeps a compact requirements checklist while choices remain unresolved:

- [x] Confirmed: supplied by the user or established by the data
- [~] Inferred: proposed by the Skill and easy to revise
- [ ] Needs confirmation: required before the build can start

It asks one consolidated round only for blocking choices such as CRS, template, primary layer, category meaning, display fields, output formats, and audience locale.

3. Verify the installation

interactive-map-builder doctor
interactive-map-builder update --preflight

doctor creates a temporary coordinate table, builds a map without network access, verifies the packaged Leaflet resources and output hashes, prints a JSON result, and removes the temporary files. It does not download basemaps or send usage telemetry. The update command prints structured JSON containing the local version, official version when known, source, installation type, and status. For a cached status-only query, run interactive-map-builder update --check.

Prefer interactive-map-builder doctor after installation. In a source checkout where the console command is not yet available, use python scripts/cli.py doctor. The internal python scripts/map_builder.py --help command intentionally lists only build commands and must not be used to conclude that the package lacks doctor.

Manual Git installation for zero-touch updates

Use one active Codex Skill directory rather than keeping duplicate .codex and .agents copies. A legacy Windows location may be $HOME\.agents\skills; archive it before using the active Codex directory below.

Windows PowerShell

$CodexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME\.codex" }
New-Item -ItemType Directory -Force "$CodexHome\skills" | Out-Null
git clone https://github.com/xlbaoxl/interactive-map-builder.git `
  "$CodexHome\skills\interactive-map-builder"
Set-Location "$CodexHome\skills\interactive-map-builder"
py -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight

macOS or Linux

CODEX_ROOT="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_ROOT/skills"
git clone https://github.com/xlbaoxl/interactive-map-builder.git \
  "$CODEX_ROOT/skills/interactive-map-builder"
cd "$CODEX_ROOT/skills/interactive-map-builder"
python3 -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight

Install from a versioned Release

Every v0.3.1+ GitHub Release publishes:

• interactive-map-builder-skill-vX.Y.Z.zip — a lean Agent Skill package containing SKILL.md, Agent metadata, references, the deterministic engine, and its packaged web resources;
• a Python wheel and source archive for conventional package installation;
• SHA256SUMS.txt for release-asset verification and managed Skill updates.

The Skill ZIP intentionally excludes demos, screenshots, tests, and CI files. Extract it into an Agent Skills directory, run python -m pip install ., then run interactive-map-builder doctor.

Use with Claude Code or another Agent Skills client

Copy the complete repository or the versioned Skill ZIP into a Skill or rules directory that the client can read, let it load SKILL.md, and install the deterministic engine once:

python -m pip install .
interactive-map-builder doctor

The workflow is client-neutral: inspect data, maintain the requirements checklist, write the canonical MapSpec, build with the packaged engine, verify, and deliver the complete dist directory.

Updates, planning, and public deployment

At the start of a Skill task, the Agent runs interactive-map-builder update --preflight from the Skill root. This is a cached, check-only request: it reuses a valid result for up to 24 hours, never modifies files, stays silent when the installed version is current, and reports only an available update or a failed check. Offline access never blocks map construction. Set IMB_DISABLE_AUTO_UPDATE=1 to opt out.

Applying an update is a separate maintenance action. update --apply and the legacy non-fatal update --auto --force retain checksum, manifest, exact-copy adoption, local-change protection, duplicate-root refusal, post-install doctor verification, and rollback.

Versions v0.3.2–v0.4.2 do not contain the copy-adoption fix. An already installed unmanaged copy of one of those versions needs one official v0.4.3 reinstall. Later compatible releases can then be adopted and applied automatically.

Updates are transactional: after replacing a verified release, the updater reinstalls the engine and runs the offline doctor. A failed install or doctor check restores the prior Git commit or the previous manifest-owned files. Confirmed release metadata is preserved when application fails, so an Agent cannot silently convert “an update is available” into “no update available.” See the verified update policy.

For a genuinely complex Codex task—multiple independent layers, several unresolved design choices, or coordinated HTML/slide/paper outputs—the Agent may suggest Plan mode once as an optional convenience. It continues inspecting immediately whether or not the user switches, and clear single-layer requests do not receive the suggestion.

The normal deliverable is a portable local map.html. “Share with colleagues” means sending that file, not publishing embedded data on the internet. A public URL is discussed only when explicitly requested, after confirming a hosting target and permission to expose the data. Hosting remains a separate workflow from map construction.

Atlas Studio Light

Version 0.4 introduces a lightweight visual-default resolver rather than a full automatic design system. When MapSpec omits low-level visual values, the engine uses geometry family, coarse feature/coordinate density, template role, and stable draw order to choose a restrained first render:

• dense point layers use smaller symbols and lower fill intensity;
• lines and polygons receive separate weights, fills, and outlines;
• map-list primary layers stay prominent while context layers recede;
• multilayer maps open with all visible layers at their base style, then focus a layer only after the user selects it;
• HTML, legends, cards, PNG, SVG, and PDF consume the same resolved visual plan;
• automatic categorical colors stop at eight distinct classes instead of cycling into a rainbow.

Explicit MapSpec values always win. The goal is a credible, presentation-ready starting point—not a replacement for a planner or designer. Users can keep refining color, size, opacity, fields, and hierarchy through natural-language instructions or direct MapSpec edits. Every inferred decision is recorded in build_report.json under visual and visual_system.

Choose the right map product

User goal	Template	Best for	Main interactions
Find, screen, rank, and compare records	map-list	Parcels, buildings, facilities, stores, projects, events, candidate sites	Search, category and numeric filters, sorting, KPI summaries, list-map linkage, detail panel
Explore several independent spatial themes together	multilayer	Boundaries, roads, routes, facilities, environmental layers, planning context	Layer visibility, layer-specific search, point/line/polygon styling, legends, basemap switching, feature details

A map-list may also include context layers. With multiple inputs, the Skill never guesses the business intent from geometry type alone; it asks the user to confirm the template and primary layer.

Basemaps and multilayer controls

New MapSpec files include two credential-free online basemaps: CARTO Positron as the quiet default and OpenStreetMap Standard for detailed street context. The selector also includes No basemap, and repeated tile failures automatically fall back to it, so business layers and interactions remain usable without tiles. Esri World Imagery can be added only when the user provides an authorized service URL or token and accepts that browser-delivered credentials can be visible in the generated HTML.

In the multilayer product, visibility switches are kept in a fixed upper section. The legend is stacked below them, scrolls when long, and starts collapsed at narrow widths, so a large categorical legend cannot cover the layer controls.

Supported inputs

Input	Requirement
GeoJSON / JSON FeatureCollection	Geometry and CRS must be readable
GeoPackage	Select a layer when the package contains more than one candidate
Shapefile ZIP	One Shapefile dataset per ZIP; .cpg/GDAL encoding detection is preserved
CSV	Longitude/latitude columns or WKT geometry plus an explicit source CRS
Excel	Longitude/latitude columns or WKT geometry plus an explicit source CRS
ArcGIS FeatureServer	Downloaded to a local GeoJSON snapshot before rendering

The inspection step reports feature count, geometry type, CRS, field samples, likely ID, label, and category roles, ambiguities, and performance signals before a map is proposed.

Deliverables

File	Purpose
map.html	Portable local Leaflet map with embedded business geometry
map_slide_16x9.png	Presentation-ready 1920×1080 figure when the slide preset is enabled
map_paper.png / .svg / .pdf	Publication outputs when the paper preset is enabled
map_spec.json	Resolved, reusable build contract
inspection.json	Inputs, CRS, fields, candidate roles, and unresolved choices
build_report.json	Counts, repairs, warnings, performance metrics, hashes, and portability
DELIVERY_MANIFEST.json	Managed-file ownership, sizes, and SHA-256 values for transactional verification
README_USAGE.md	Localized handoff note for the final map recipient

A normal build keeps source paths relative to the original project and treats map_spec.json as a build record. Use --bundle-sources when the deliverable must rebuild independently after it is moved.

How it works

User request + spatial files
           │
           ▼
       inspect inputs
  CRS · geometry · fields · scale
           │
           ▼
  confirm unresolved intent once
           │
           ▼
        MapSpec 1.1
           │
           ▼
 Atlas Studio Light resolver
 geometry · density · role · order
           │
           ▼
 deterministic Python engine
 load · normalize · render
           │
           ▼
 verify counts, files, QA hooks,
 provenance, hashes, and browser UI
           │
           ▼
  portable HTML + report figures

The packaged JSON Schema is the only machine-readable MapSpec contract. Canonical keys use snake_case; unsupported fields and schema versions are rejected instead of being silently migrated.

Command-line workflow

For one unambiguous layer:

interactive-map-builder run data.geojson --locale en-US --output dist

For an explicit, reproducible workflow:

interactive-map-builder inspect sites.geojson districts.geojson \
  --output inspection.json

interactive-map-builder init-spec inspection.json \
  --template map-list \
  --primary-layer sites \
  --locale en-US \
  --output map_spec.json

interactive-map-builder build --spec map_spec.json --out dist --bundle-sources
interactive-map-builder verify --dist dist

For independent point, line, and polygon layers, use --template multilayer and omit --primary-layer.

Scope

Interactive Map Builder focuses on existing spatial data → finished map product. It does not currently provide:

• address geocoding;
• buffers, overlays, routing, site-selection models, or statistical inference;
• vector-tile services or million-feature WebGIS infrastructure;
• offline basemap acquisition;
• CRS guessing from coordinate ranges;
• 3D terrain, buildings, or digital twins;
• general maintenance of an existing custom Leaflet or React application;
• automatic public hosting without an explicit deployment request and data-publication approval.

For large GeoJSON payloads, the build report recommends light or medium geometry simplification but does not silently switch rendering engines.

Project status

The current stable release is v0.4.4. This stabilization release makes delivery transactional, adds a managed-file manifest and strict verification, moves ordinary release preflight to cached check-only behavior, limits ZIP extraction resources, and restricts manual Release runs to repairing an existing tag. MapSpec remains 1.1 and cartographic behavior is unchanged.

See the changelog for completed work.

Development

python -m pip install -r requirements-dev.txt
python scripts/evaluate_triggers.py validate
python -m pytest -q -m "not browser"
python -m playwright install chromium
python -m pytest -q -m browser

Build the localized demo site and lean Skill package:

python scripts/build_demo_site.py --output _site
python scripts/build_skill_package.py

The CI matrix covers Python 3.9, 3.10, and 3.12, trigger-suite validation, Chromium interaction tests, wheel creation, the offline installation doctor, a clean out-of-repository build, and the Skill distribution archive. After a new package version passes main CI, the Release workflow creates the tag and assets or repairs an incomplete Release without moving an existing tag.

License

MIT