i.ai is an AI assistant that works inside the running GRASS session. It answers questions about the data, the session, methods and tools. It turns tasks into plans of GRASS commands and command-line steps that are validated before anything runs. It also writes complete report pipelines: numbered scripts, stored per session, that go from the data to a LaTeX report, run end to end, repair their own failing steps and compile the PDF.
Every GRASS tool installed in the session is available to the assistant.
This covers core tools and addons, so all of them can be found, read and
proposed. The tool catalog is read from the live installation
($GISBASE/bin, $GISBASE/scripts, $GRASS_ADDON_BASE/bin,
$GRASS_ADDON_BASE/scripts and GRASS_ADDON_PATH). Each tool's
interface comes from its own --interface-description, so the assistant
uses the parameters, flags and option values of the installed version.
Every command-line tool on PATH is available as well: GDAL/OGR, LaTeX
(latexmk, pdflatex, bibtex, biber), Graphviz, ImageMagick, pandoc,
jq, curl and the rest. They are searched through the man page index
(apropos, whatis) and described from their man page or --help. The
prompt also lists the installed Python packages that scripts may import.
The language model can be:
IAI_API_KEY or
OPENAI_API_KEY;alias-large), with its key in api_key_file,
BLABLADOR_API_KEY or IAI_API_KEY;claude command), with no API key;opencode/big-pickle model, which needs no account.The design follows GeoCopilot, an agent framework for 3D scene control, adapted to GRASS:
The read-only tools available to the model are:
--version/--help). Pipes and redirections are refused,
and so are paths that may hold credentials (~/.ssh, ~/.aws, tokens);Read-only commands can run on a raster map's own region through a scoped region manager, so the user's computational region never changes. The session context sent to the model holds the project, mapset, CRS, computational region, mask status, the maps in the search path and the installed tools.
Nothing the model proposes runs unchecked. Each command is checked against the live interface of the installed tool and against the existing maps. The following are errors, reported with suggestions when a close match exists:
Nothing is corrected silently. Each valid command also gets a risk level:
Command-line steps and scripts are validated too. Bash goes through
bash -n and Python through its parser. Every command a script calls must
be installed, every Python module it imports must be importable, and the
GRASS calls inside it are checked like GRASS steps. This covers bash
lines, grass_run bash -s <<EOF blocks and gs.run_command(...) calls
with literal arguments. Some patterns are refused outright: sudo,
recursive removal of /, ~ or ., piping a download into a shell,
disk tools, git push, package installs and crontab edits. Scripts also
get a risk level: network for downloads and remote copies, modify
for removals and moves.
Plans run only with the -e flag. Each step is validated again just before it runs. A modify or network step needs a yes at the terminal, or the -y flag; without either, the plan stops before that step. GRASS steps run directly; command-line steps run with bash in the session's workspace (or the current directory). Interactive tools (such as g.gui or v.digit) are refused. Display tools (d.mon, d.rast, d.legend, ...) get the display risk level: they draw on a monitor and run without confirmation, but never as a read-only lookup while the model works out its answer. --overwrite is never added by the model to GRASS steps; it applies only when the user passes it to i.ai.
The command-line backends cannot touch the session themselves. claude runs with all its built-in tools disabled and a JSON schema for the reply. opencode runs its read-only plan agent in an empty temporary directory, without auto-approved permissions.
A pipeline request ("write a report on ...", or operation=report)
produces a report workspace. The workspace is either workdir or, for a
session, ~/.local/share/i.ai/sessions/<session>/, and is laid out
like a scripted report:
scripts/00_env.sh: paths, GRASS project and mapset, the study
settings shared by every step, grass_run (GRASS tools directly inside
a session, through grass ... --exec outside one) and mm (MetaMonitor
progress, a no-op without it);scripts/run_step.sh and scripts/NN_<name>.sh|py: one script per
step, from data preparation to figures (Python), diagrams (Graphviz),
maps (GRASS display tools, cairo driver) and tables (LaTeX tabular
and CSV);<main>.tex and references.bib: the report. The preamble and title
block follow a fixed style; the body is written by the model;Makefile (make analysis, make step-NN, make report, make),
README.md (the run book), figures/, maps/, tables/, data/,
logs/, and the manifest .i.ai/pipeline.json.The pipeline agent first inspects the data and tools and gives an
outline: steps, study settings and report sections. It then writes each
script, and each one must validate before the next is written. Last, it
writes the report body. The report includes every pipeline output with
\figorpending and \taborpending, so it compiles before the data
exist, with a placeholder box for each missing output. The checks on the
report are:
\cite has a BibTeX entry;A script may overwrite only the GRASS maps that this pipeline created (recorded in the manifest), never other existing maps.
With -e, or later with operation=run -e, i.ai runs the steps in
order and logs each one to logs/. It records the GRASS maps each step
created. When a step fails, a repair agent reads its log, inspects files
and tools, and rewrites the script, up to repairs times. The rewrite is
validated, and the first version is kept as <script>.orig. After the
last step, the model rewrites the Executive summary and Results from the
real outputs (tables, CSV files, logs and the list of figures). The report
is then compiled with latexmk, and LaTeX errors go back to the model
for repair. from_step restarts a run at a given step.
A later request in the same session revises the pipeline: unchanged steps
are kept, and only new or changed steps are rewritten. The report title
block takes author and contact (by default from git config),
organization and an optional classification banner.
By default, requests are typed. With input=voice, they can also be
spoken into the PC microphone. In the dialog (-i), an empty line
(Enter) starts recording and Enter stops it. Without -i and without
query, one spoken request is taken. The transcription is put on the
i.ai> prompt line, where it can be edited before Enter sends it. Typed
lines and /commands still work.
Speech is recorded with PipeWire (pw-record, the Debian 13 default; arecord otherwise) as 16 kHz mono WAV, and transcribed by whisper.cpp with the large-v3 model on a GPU, never on a CPU. The recording is deleted after transcription and nothing is stored on the GPU machine. Transcription runs:
IAI_VOICE_HOST
and IAI_VOICE_USER.The GPU search looks for:
/dev/dri/renderD*, /dev/kfd, nvidia-smi);PATH, ~/dev/whisper.cpp,
~/whisper.cpp or the home directory, or at IAI_WHISPER_BIN;ggml-large-v3 model, or the one at IAI_WHISPER_MODEL.whisper-server then starts with the model kept in GPU memory. On a
server it is reached through an ssh tunnel on a random port bound to
127.0.0.1. It must report its GPU backend (whisper_backend_init_gpu:
using ...), or voice input stops with the reason. The server process is
stopped when i.ai exits. voice_language sets the spoken language
(en by default; fr, ..., or auto to detect it). Automatic
detection is not the default because it is unreliable with an accent: it
can pick the speaker's native language and transcribe an English request
in French. The prompt passed to whisper holds GRASS
terms and the session's map names, so they are heard as such.
The openai and blablador backends need an API key, except for a
server on this machine (localhost). The key is read from the file given
as api_key_file, else from the environment variables listed above;
it is never an option value, so it does not end up in the shell history.
i.ai warns when the key file can be read by other users.
At start, i.ai checks the key and the model against the server's model
list: a rejected key, refused access, or a model the server does not
offer (with the list of those it does) stops it with the reason. Calls
refused for the rate limit (HTTP 429) are retried after the wait the
server asks for, up to three minutes per call, with a message. Structured
output is asked as a JSON schema; a server that does not support it gets
JSON mode, then the schema in the prompt, and the level that works is
kept for the session. Reasoning output (<think>...</think>) is ignored.
For Blablador, the key is a personal access token of
Helmholtz Codebase with the
read_user scope, valid for up to a year. Its models are named by
alias: alias-large (default, balanced), alias-fast, alias-code and
alias-huge; alias-embeddings serves operation=index. Its rate
limits are per model and user (for example 10 requests per minute on
alias-large for external users); as each request to i.ai takes
several model calls, a class may prefer alias-fast.
With session, the dialog history and the last plan are saved under
$XDG_DATA_HOME/i.ai/sessions/ (by default ~/.local/share/i.ai/), so a
conversation can continue across calls. The format option prints the
answer and plan as text (plain), the full result as JSON (json),
or the plan as a shell script to review and run later (shell).
The -i flag starts an interactive dialog. Requests are asked in plain words, typed or spoken. Each plan is offered to run (Run this plan? [y/N]), with or without -e. A short approval of the pending plan, typed or spoken, runs it instead of going back to the model: do it, yes, run it, go ahead, and in French vas-y, oui, lance.
The dialog is also a command line. A line that starts with an installed
GRASS tool (d.mon start=wx0, r.info map=elevation) runs that command
directly, and a line that starts with ! runs a shell command
(!gdalinfo data/dem.tif). Both are validated first, like plan steps,
and steps that change existing data or use the network ask for
confirmation (or need -y). The dialog commands are /run (execute
the last plan), /plan, /context, /reset and /exit.
$XDG_CACHE_HOME/i.ai/ (by default ~/.cache/i.ai/).The answer goes to standard output; messages and progress go to standard
error. Plan execution reports its progress through G_percent().
Pipeline scripts run with the user's own permissions. Validation refuses known destructive patterns and asks before network or modifying steps, but it is not a sandbox: read the scripts before running a pipeline on data that matters, or run it in a separate mapset.
Small local models often struggle to follow the JSON step protocol. Models that are good at tool use give the best plans. When the ollama backend has no model, the first installed model is used.
Ask a question with Claude Code:
i.ai backend=claude query="Which Landsat bands are in this project, and what is the mean of elevation over its own extent?"
Plan a task with OpenCode Big Pickle, review the plan, then execute it:
i.ai backend=opencode query="Compute slope in degrees from the DEM, then smooth it with a 5x5 average" i.ai backend=opencode query="Compute slope in degrees from the DEM, then smooth it with a 5x5 average" -e
Write the plan as a shell script:
i.ai backend=claude query="Compute NDVI from the 2002 Landsat 7 bands" format=shell > ndvi.sh
Continue a named dialog:
i.ai backend=claude session=wake query="Delineate the watersheds of the elevation map" i.ai backend=claude session=wake query="Now keep only basins larger than 1 km2" -e
Use an OpenAI-compatible server, here a local llama.cpp server:
i.ai backend=openai url=http://localhost:8080/v1 model=qwen3 query="..."
Use Blablador, with the key kept in a private file:
chmod 600 ~/.blablador_key i.ai -i backend=blablador api_key_file=~/.blablador_key i.ai -i backend=blablador model=alias-fast api_key_file=~/.blablador_key
Write a report pipeline in a dated report folder, run it end to end, and compile the PDF:
i.ai backend=claude operation=report workdir=~/Documents/LaTex/Report/20261017_Terrain \
query="Terrain analysis report of the elevation map: slope, aspect, streams, maps, figures and tables" -e -y
Run it again later from step 04, after editing a script:
i.ai backend=claude workdir=~/Documents/LaTex/Report/20261017_Terrain operation=run from_step=04 -e
The same pipeline runs without i.ai:
cd ~/Documents/LaTex/Report/20261017_Terrain && make
Speak the requests of a dialog, transcribed on a GPU server:
i.ai backend=claude -i input=voice voice_host=192.0.2.10 voice_user=yann
Or set the server once and speak a single request:
export IAI_VOICE_HOST=192.0.2.10 IAI_VOICE_USER=yann i.ai backend=claude input=voice
Mix GRASS and command-line steps in a plan:
i.ai backend=claude query="Export the slope map to a Cloud Optimized GeoTIFF and make a 1000 px PNG preview" -e
Show what the assistant sees, and build the caches:
i.ai operation=info i.ai operation=index
claude command
(logged in), or the opencode command.cmake -B build -DGGML_VULKAN=ON) with the ggml-large-v3 model.g.search.modules, r.mapcalc, r.univar
GeoCopilot, whose agent architecture i.ai follows.
Yann Chemin
Available at: i.ai source code (history)
Accessed: Sunday Nov 15 10:56:30 2026
Main index | Imagery index | Topics index | Keywords index | Graphical index | Full index
© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual