Meet the Geocluster Research Harness

TL;DR

• Open-sources the Geocluster Research Harness under Apache-2.0: a browser-based, VS Code-style IDE with a geology-specialised AI agent and a toolbox of more than fifty geoscience analysis tools, addressing a gap general-purpose coding assistants have - they don’t know the domain, and will happily treat a value like “<0.005” as junk rather than a detection limit.
• Runs with a single Docker command and comes pre-loaded with a synthetic exploration project, so a first query works before any user data is uploaded.
• Built from three pieces: the Geology Agent (a heavily adapted fork of the open-source Cline coding agent), geocluster-mcp (a Python MCP server exposing the tools, with every file operation confined to the workspace), and the Docker harness that wires the two together locally.
• The core engineering choice is a four-layer agent architecture with enforced separation of duties - a read-only chat agent, a zero-tool orchestrator that only plans, isolated specialist sub-agents restricted to filtered tool subsets, and a single wildcard layer that alone can install packages and must log every install - with each restriction tied to a specific measured failure it was introduced to fix, such as prompt bloat, runaway context, dependency conflicts, or agents bypassing the plan.
• The agent is designed to keep answers checkable: it inspects large datasets via tools that return schema, statistics, and samples rather than loading raw files into its own context, and produces plots and derived artifacts as ordinary files with source citations for reported figures.
• It is local-first (no accounts, no telemetry, bring-your-own model key) and built openly on top of Cline and code-server, with the fork’s lineage and licensing kept explicit and no claim of affiliation with either upstream project.

Key Takeaways

• The four-layer separation-of-duties architecture is a response to specific, previously observed failure modes, not a general best-practice pattern applied speculatively. Each restriction exists because removing it broke something measurably during development.
• Domain specialisation here is mostly about tool design rather than a smarter underlying model. Correctly parsing a detection-limit notation or keeping large tables out of the model’s own context does more for reliability than model choice does.
• “Answers you can check” is the actual design goal, not an incidental feature. Citing sources and producing artifacts as real files is what lets a geologist verify a claim rather than simply trust it.
• The project is framed as an extension of existing open-source work rather than a from-scratch system, and is treated as ongoing rather than finished. Building openly on Cline and code-server, and explicitly asking for input on what the assistant should refuse to do, signals the harness is meant to be shaped by its users over time.

An open-source AI geology workbench that runs in your browser

Exploration geology lives in a tangle of file formats: multi-element geochemistry tables, LAS well logs, GeoTIFF rasters, and hundred-page technical reports. General-purpose AI coding assistants can write you a pandas script, but they don’t know the domain. They will happily stream a 40,000-row assay table into their own context window, treat a value like “<0.005” as junk instead of a detection limit, or answer a question about a drill program with something that sounds right but points at nothing you can check.

The Geocluster Research Harness is our answer: a browser-based IDE with a geology-specialized AI research agent built in, wired to a toolbox of more than fifty geoscience analysis tools. Today we’re open-sourcing it under Apache-2.0. You can check it out here: Geocluster Research Harness

One command to a working geology lab

If you have Docker installed, this is the whole setup:

git clone https://github.com/EigenformAI/geocluster-research-harness.git
cd geocluster-research-harness
git submodule update --init
docker compose up --build

Open http://localhost:3000 and you’re inside a familiar VS Code-style editor (powered by code-server) with the Geology Agent in the sidebar. Pick a model provider — OpenRouter, Anthropic, or a ChatGPT subscription — paste your API key, and start asking questions. The workspace comes pre-loaded with a synthetic exploration project, so the first “cluster this geochemistry and map it against lithology” works before you’ve uploaded anything of your own. A prebuilt Docker image and a VSIX for desktop VS Code ship with each release.

What’s under the hood

The harness is three pieces working together in one container:

• The Geology Agent — a heavily adapted fork of the open-source Cline coding agent, rebuilt around geological analysis: geology-specific prompting, domain guardrails, and a multi-agent specialist system.

• geocluster-mcp — a Python MCP (Model Context Protocol) server exposing 50+ tools: dataset inspection and cleaning, detection-limit parsing, normalization, clustering, dimensionality reduction, raster band math, gridding and plotting, and anomaly ranking. Every file operation is confined to your workspace.

• The harness itself — the Docker image that wires the IDE, the agent, and the tool server together, seeds the sample workspace, and keeps everything local.

A team of specialists, not one know-it-all

The most interesting engineering in the harness is how the agent is structured. Instead of one model with every tool, the agent is a four-layer team with enforced separation of duties:

• Layer 1 — the Geology Agent you chat with. It can read data and reports, but it is deliberately read-only: no shell, no file writes.

• Layer 2 — an orchestrator that plans multi-step analyses. It has zero tool access; it only routes work.

• Layer 3 — specialists (data operations, transforms, analytics, geo-visualization) that run as separate child processes, each restricted to a filtered slice of the tool set.

• Layer 4 — an “extended” wildcard agent, the only layer allowed to install new packages, and it must record every install.

These rules aren’t style preferences — they are design invariants enforced by an automated test suite, and each one exists because breaking it caused a measured failure during development: prompt bloat, runaway context, dependency conflicts, or agents bypassing the plan. When you ask for a full analysis, you can watch the orchestrator dispatch specialists, and each child reports its token usage back to the chat.

Answers you can check

The agent is instructed never to dump raw data files into its own context; it inspects datasets through tools that return schema, statistics, and samples, and the plots and derived artifacts it produces land in your workspace as ordinary files you keep.

Local-first, bring your own model

There are no accounts and no telemetry. The container runs on your machine, your API key goes into the provider of your choice, and your data never leaves the workspace volume except as the prompts the agent sends to your chosen model. Analytics and error reporting inherited from the upstream project are disabled.

Standing on open shoulders

The Geology Agent is a fork of Cline (Apache-2.0), and we’ve kept the lineage explicit: the extension is renamed so it installs cleanly alongside the original, the license and notices ship with the code, and the project is not affiliated with or endorsed by the Cline team. The IDE experience comes from code-server by Coder. Our thanks to both projects — this kind of tool simply wouldn’t exist without them.

Try it, break it, tell us

The code, documentation, and sample workspace are on GitHub at github.com/EigenformAI/geocluster-research-harness. Fire it up, point it at the bundled Meridian Ridge project (fully synthetic — no real prospect data included), and ask it things like:

• “Inspect data/meridian_ridge_geochem.csv and summarize the dataset.”

• “Which elements are the best pathfinders for gold here?”

• “Cluster the geochemistry and map the clusters against lithology.”

Issues and pull requests are welcome. If you work with geological data and have opinions about what an AI research assistant should refuse to do as much as what it should do — we’d especially like to hear from you.