Claude in GAMA

An AI agent — not another chatbot — living inside the GAMA Platform IDE and inside your running simulation.

A chatbot answers questions about code it has never seen. An agent acts: this
one reads your compiler errors, edits your files (with your approval), runs
your experiments to check its own work, and reaches into the live simulation
while it runs.

Most GAMA users are not programmers. They are ecologists, urban planners,
epidemiologists, geographers, students — people who came for the
simulation, and GAML is just the price of admission. I kept watching
newcomers hit their first compiler error and do the only thing they could:
copy-paste it into a chatbot that has never seen their project and barely
knows GAML. So I put the agent inside GAMA. It sees what the IDE sees: the
compiler errors with exact lines, every model in the workspace, the console.
And it sees what the simulation sees: while your experiment is running it
can pause it, read agent state, change the world, step cycle by cycle, and
literally look at the displays you are looking at.

Here is the moment that sold me on my own tool. My pedestrian simulation was
running. I typed one message — "give each person a circle showing their body
temperature, darker when people are close together, and add a graph of the
highest temperature" — and after a reload this is what I got:

New attribute, new reflex, new aspect, a whole new chart display. I never
opened the editor.

What it can do

Fix the errors in your project

Open a broken project and the chat already knows. The plugin feeds GAMA's own
Xtext diagnostics to the agent — exact files, exact lines, no copy-pasting.
The welcome screen gives you one-click starters:

I clicked Fix errors on a project where the banner said "Impossible to
run any experiment". It read the files, made the edits (every one shows a
real diff you approve), validated the model headlessly, and the run button
came back green:

Start a brand-new project from one message

There doesn't have to be a project yet. Describe what you want and the agent
builds the whole thing — project folder, model file, species, reflexes,
experiment, displays — and auto-imports it into the navigator, ready to run.
My caro (gomoku) game and my chess game each started life as a single chat
message. And if you ask it to, it proves the model works before handing it
over: it runs the experiment headless in the background, reads the monitor
values step by step and the display snapshots, and only then tells you it's
done.

Change your model while the simulation runs

This is the part no generic AI IDE can do. The chat is docked right next to
the Console in the simulation perspective, and every message you send carries
a live status line — current cycle, parameters, monitors — so the agent always
knows a sim is up:

So you just... ask for things. Here I asked for the body-temperature feature
while the sim was at cycle 7959:

It edited the model, told me a reload was needed (a running sim keeps its old
code — that's GAMA, not the plugin), and one reload later I had the circles
and the chart you saw at the top.

It can look at your displays

sim_snapshot captures each display of the running experiment to PNG and the
agent reads the image. Here I switched the model picker to Haiku (fastest)
and asked it to look at the graph:

And it answers from what it actually sees — the max/mean temperature lines,
the oscillation, the spread:

The full toolbox

• Live simulation bridge — sim_status (cycle, parameters, monitors,
  displays), sim_eval (run any GAML against the live world, expressions
  and statements: ask people { ... }, create predator number: 5; —
  displays refresh instantly), sim_control (pause / resume / step / step
  back / reload), sim_snapshot (per-display PNG the agent can read).
• Project intelligence — every .gaml is parsed into a cached semantic
  index; each message carries a compact project map (files, species,
  experiments, displays, with line numbers). gaml_outline and
  find_gaml_symbol navigate without reading whole files.
• Run-and-verify loop — validate_gaml_syntax compile-checks headlessly,
  run_experiment_headless runs any experiment with a step cap and returns
  monitor values per step plus display snapshots, read_ide_console tails
  the IDE console. The agent doesn't guess whether its fix works — it runs it.
• Safe edits, by construction — guardrails live in code, not prompts.
  Read/edit is hard-limited to your project folder. No shell access, ever.
  Every edit shows a diff card, every applied edit is snapshotted and
  undo-able from the History panel.
• IDE conveniences — model picker in the header (Opus for the hard stuff,
  Haiku when you want speed), window snapshot button, "Ask Claude" on any
  error line (right-click or Ctrl+Alt+C), context-folder override, one-click
  fresh session.

Why not just use Cursor?

GAMA is a simulation platform. The loop is not write → compile → ship, it
is write → compile → run → watch what emerges → adjust. A generic AI IDE
stops at the file level. It can never tell you why the epidemic dies out at
cycle 300, because it can't see cycle 300. And the people who model in GAMA
are mostly scientists, not developers — asking them to move their work into a
programmer's editor to get AI help is exactly backwards. The help should come
to where they already are.

Architecture

GAMA (Eclipse RCP + Xtext)
└─ gama.ui.claude (this plugin, Java)
   ├─ ChatView       SWT Browser chat UI + JSON-lines stdio to the agent
   ├─ MarkerBridge   IMarker -> JSON, auto-rescan on save/tab-switch
   ├─ ConsoleBridge  read-only console mirror, refreshed during a turn
   ├─ SimBridge      live bridge into the RUNNING experiment (gama.core):
   │                   status / pause / resume / step / reload,
   │                   GAML eval (Interactive-Console engine, statements too),
   │                   per-display PNG capture
   └─ AgentHost      spawns agent/ide_agent.py
        └─ Claude Agent SDK -> Claude API
           ├─ gaml-tools   outline / find symbol / project map (cached index)
           ├─ gama-tools   validate / run headless / read outputs / console
           ├─ gama-sim     sim_status / sim_eval / sim_control / sim_snapshot
           │                 (RPC over stdio -> SimBridge in the IDE process)
           └─ edit_history pre-edit snapshots, diff cards, undo journal

The sim tools are a tiny RPC channel: the Python agent emits
{"type":"sim_cmd",...}, the Java plugin executes it on the GAMA runtime and
answers with sim_reply. Same trusted process, no extra ports, no server.

Install

Requirements: GAMA 2025.x (its bundled JDK is used to compile), Python ≥ 3.10
with claude-agent-sdk, Node.js ≥ 20, bash (Git Bash on Windows).

git clone https://github.com/mr-thangceoaka/gama-claude-plugin
cd gama-claude-plugin

# 1. build + install into GAMA (auto-detects the install; else set GAMA_DIR)
#    GAMA must be closed, or the old jar can't be replaced
bash build.sh

# 2. python side
python -m venv .venv && . .venv/Scripts/activate   # or bin/activate
pip install claude-agent-sdk

# 3. config: copy gama-claude.properties.example to ~/.gama-claude.properties
#    fill python=, script=, and ONE of oauth_token= / key=

# 4. start GAMA -> the "Claude Chat" view opens by itself

Auth: oauth_token= (from claude setup-token, uses your Claude
subscription) or key= (API credits). The agent runs with an isolated
CLAUDE_CONFIG_DIR, so proxies or model overrides in your own
~/.claude/settings.json cannot hijack it.

Uninstall: delete the gama.ui.claude,... line from
<GAMA>/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info and
remove the jar from <GAMA>/plugins/ (a bundles.info backup is written on
first install).

Why not headless-only?

GAMA's gama-headless -validate doesn't check your file (built-in library
only); -xml does, but costs a full JVM start per check and reports no line
numbers. The IDE's Xtext markers are instant and exact — the plugin just hands
them over. Same story at runtime: headless re-runs are great for reproducible
checks (the agent uses them), but only the live bridge lets you ask about
the simulation you are watching, with its exact seed and history.

Version history

The project grew in milestones, each one tested for real inside the GUI.
What changed from version to version:

v0.1.0 (M0–M4) — the starting point. A Claude Chat view inside GAMA,
GAMA's error markers converted to JSON and attached to your messages, "Ask
Claude" on any error line, edit approval cards with a diff preview, a Stop
button, and a window-snapshot button so the agent could see the IDE.

v0.2.0 (M5) — from single-file to project-wide. The agent got the whole
project as context, a "Context folder" override to point it anywhere, a
clear-conversation button, and the installer learned to remove stale plugin
versions.

v0.3.0 (M6) — the verify loop. Headless validate and run tools, so the
agent could check its own fixes instead of guessing. New projects created by
the agent are auto-imported into the navigator.

v0.4.0 (M7) — the big overhaul. Workspace semantic index with a project
map on every message, gaml_outline / find_gaml_symbol, an IDE console
mirror, run_experiment_headless for any experiment with monitors per step
plus snapshot PNGs, unified-diff approval cards, and a full edit history with
per-entry Undo. Read scope enforced in code via hooks, not prompts.

v0.5.0 (M8) — the live simulation bridge, the feature this whole project
was heading toward. sim_status, sim_eval (expressions and world-mutating
statements, same engine as GAMA's Interactive Console), sim_control
(pause/resume/step/reload), sim_snapshot (per-display PNG). Live sim status
attached to every message.

v0.5.1–v0.5.5 (M8.1–M9.1) — making it feel native. The chat survives
perspective switches, docks into the console stack of the simulation
perspective, got a UI overhaul with a live-sim badge in the header, a model
picker (Opus / Sonnet / Haiku), and a welcome screen with one-click starter
prompts.

License

MIT