Maps in the Claude Code Terminal

I use Claude Code for GIS work. When I ask it for a map, I get a URL or a file path. I want to see the map. So I built a plugin that draws it in the terminal.

The idea came from claude-inline-images by kbrianps. It draws PNG files that Claude reads. I wanted the same result for map services. The plugin is inline-maps.

OpenTopoMap tiles of North America, stitched into one map image

What it is

Claude Code loads the plugin at session start. Claude Code calls this type of plugin a "mod". The mod API is early access. You need Claude Code 2.1.287 or later.

The plugin adds two things:

  • A tool, show_map. Claude calls it when you ask for a map.
  • A command, /map. You type it at the prompt.

Both use the same function. Only the way they return the result is different.

Which map services it reads

The plugin reads the URL and identifies the type of map service. Then it makes one request for a map image, or one request for each tile. It tests the patterns in the order of the table.

Map serviceURL patternRequest
XYZ / WMTS RESTful tiles{z} or {TileMatrix}Up to 4 × 4 tiles
ArcGIS MapServer…/MapServerexport, PNG32
ArcGIS ImageServer…/ImageServerexportImage, PNG
OGC API - Maps…/collections/… or …/map…/map?f=png
OGC WMS 1.1.1 / 1.3.0service=wms or /wmsGetCapabilities, then GetMap

If no pattern matches, the plugin tries WMS first. If WMS fails, it tries OGC API - Maps.

OpenStreetMap WMS map image of Europe with country labels and roads
OGC WMS 1.3.0 GetMap, layer OSM-WMS, bbox=-10,35,30,60.

How it works

One function, show(), does these steps for the tool and for the command.

  1. Plan. plan() identifies the map service. It reads the service metadata as text. It returns one image URL or a list of tile URLs. It makes no host API calls, so the tests give it fixed responses.
  2. Size. plan() sets the image size from the ground distance. One degree of longitude is shorter than one degree of latitude, by the cosine of the latitude. Without this step, the map looks stretched.
  3. Download. curl gets each URL into a temporary directory. I use curl because the host function $.http.fetch returns text only.
  4. Check. The plugin accepts a body only if the HTTP status is 2xx and the bytes are a PNG. Some tile servers send an error tile as a PNG, so the PNG check alone is not enough.
  5. Stitch. For tiles, magick montage joins them into one PNG.
  6. Cache. The plugin keeps the last 12 images in memory as base64.
  7. Draw. A ui.render hook replaces the transcript row with the image, a caption and a file link. The terminal draws the image with the kitty graphics protocol.

Two details that cost me time

First, ArcGIS keeps square pixels. WMS and OGC API - Maps stretch the image to the size you request. ArcGIS does not. For an extent in degrees, I request imageSR=3857 (Web Mercator) and size the image with the Mercator aspect ratio. For WMS and OGC API, I keep EPSG:4326 and multiply the width by the cosine of the middle latitude.

Second, WMS 1.3.0 changes the axis order. For EPSG:4326, version 1.3.0 uses latitude, longitude. Version 1.1.1 uses longitude, latitude. The plugin swaps the bounding box for 1.3.0.

Markers

You can put a red pin on the map. Give the point as marker=lon,lat[,label]:

/map https://tile.openstreetmap.org/{z}/{x}/{y}.png bbox=2.22,48.81,2.47,48.91 marker=2.2945,48.8584,Eiffel Tower

OpenStreetMap map of Paris with a red pin on the Eiffel Tower

Each plan carries a frame: the extent in degrees, and whether the image rows are in degrees or in Mercator. markerPixel() uses the frame to convert the point to a pixel. Then magick -draw draws the pin. The label goes in the caption, not on the image. ImageMagick has no default font on my machine, and -annotate would read a label that starts with @ as a file name.

Terminals

TerminalResult
GhosttyMap image
kittyMap image
tmux with passthroughMap image
tmux without passthroughCaption and file path
Other terminalsCaption and file path

For tmux, add these lines to ~/.tmux.conf:

set -g allow-passthrough on
set -g focus-events on

Limits

  • PNG only. A JPEG tile server gives an error.
  • The plugin sends no tokens. A map service that needs authentication gives an error.
  • Each download stops at 4 MiB or 20 s.
  • A map image larger than 2 MiB draws from its file path. SSH and tmux do not show it.
  • The desktop app, VS Code and mobile show text.
  • The tests use fixed responses. They do not cover curl, magick or the terminal output.

Install

You need Claude Code 2.1.287 or later, and curl. For tiles, you also need ImageMagick. Add the marketplace:

claude plugin marketplace add mraad/claude-inline-maps

Install the plugin:

claude plugin install inline-maps@claude-inline-maps

Start a new Claude Code session. Then type /map and a map service URL.

The code is on GitHub: mraad/claude-inline-maps. Next, I want to test more WMS servers. Tell me which one breaks it.

Comments

Post a Comment

Popular posts from this blog

How to use Esri Flex API on Android and iPhone

Image
Update (Jun 2011) : For more updated info, check out my ADC article here . At MAX2010 (Awesome BTW) Adobe introduced Flex SDK Hero and Flash Builder Burrito which enables you to build and deploy Flex mobile applications on Android by default. In addition, using the revitalized Packager for iPhone , you can postprocess the swf into an ipa that you can deploy on an iPhone using iTunes. In this post, I will share with you the steps that I took to use the Flex API for ArcGIS to build a mobile mapping application. First and foremost - RTFM - here are some links that u _need_ to read specially for iPhone provisioning: http://opensource.adobe.com/wiki/display/flexsdk/Hero http://labs.adobe.com/technologies/flashbuilder_burrito/ http://labs.adobe.com/technologies/packagerforiphone/ The cool part of this whole process is now you have one code base to build upon and deploy on Android and iPhone and in the future whatever mobile platform Adobe decides to support. You can download ...
Read more

Augmented Reality, iPhone and ArcGIS Server

Image
I am a HUGE fan of Augmented Reality , and one of my favorite applications on the iPhone is Layar . In this post, I will "walk you" through how to setup a simple ArcGIS Layar Point Of Interests (POI) layer and how to expose it through the iPhone application. In addition, I created a small Flex application that will enable you to add POIs to that feature class through a python geo-processor task. BTW - this is heavily geared to using ESRI desktop and server tools and I'm assuming that you are familiar with these tools. First, request a developer key from http://dev.layar.com/ . This might take a couple of hours to get to you. So, in the meantime, let's get started. Using ArcCatalog, create a new point feature class called 'Layar' in a geodatabase with the following fields: Title (text), Line2 (Text), Line3 (Text), Line4 (Text), Attribution (Text), Type (Integer), ImageUrl (Text:512). Import that layer into a map document using ArcMap. Save and publish the ...
Read more

Weighted Map Feature Clustering With Attributes

Image
Was asked if the WeightedClusterer can cluster features not just by proximity but by proximity and attribute property value. The idea is that there should be at least one cluster per unique attribute property value. Let me explain further:  The above snapshot is a clustering of cities based on proximity and country - note that despite the proximity of Belgium and The Netherlands, two distinct clusters have been created one for BE and the other for NL - now for France - there is a cluster containing one feature over Paris, however due to the distance from Paris (at that scale) a cluster was created based on 3 cities in the south of France. Make sense ? In the implementation of the AttrClusterer class that extends the ESRIClusterer class, we override the clusterGraphics function. This function is invoked indirectly by the Flex framework during the update of the display list. In this function, we overlay a virtual grid on the map. This grid acts as a spatial index. Features that are ...
Read more