mindlas

Mindlas

A coding agent rarely fails at turn one. It fails at turn forty.

The agent said done. The tests disagree. Mindlas (Mind-Atlas) reads the session live, catches the drift as it builds, and hands the agent a correction.

Open and local. Nothing leaves your machine.

Long sessions deteriorate silently. Context fills with tool-output noise. The original task scrolls away and stops steering the agent. Edits spread across files. The same tool fails in a loop. None of this throws an error; the agent keeps producing confident output while its working state rots.

Mindlas catches that moment live: deterministic gauges under your Claude Code prompt that read the session's own signals, alert before a failure compounds, and pair every alert with a concrete correction whose effect is measured before and after.

The whole product runs on one loop, end to end for every gauge:

measure → trigger → explain → correct → remeasure → report

Scores are pure functions of the session's event ledger. Same ledger in, same score out. There is no model and no network call anywhere in the scoring path, and that is permanent: a model grading another model's session is non-reproducible, expensive, and circular. Corrections are deterministic mechanisms, not prompt nudges: an earlier advisory design told the agent to fix itself and failed empirically, so the corrector changes state directly and records a before/after to prove it did something.

What Mindlas does not claim: it does not guarantee correctness, prevent hallucinations, know the model's mental state, or replace tests, reviews, or human judgment. Its claim is narrow and verifiable: detect known deterioration causes from deterministic local signals, apply non-native corrections, record before and after effects, and produce an exportable scorecard.

Sixty seconds to a catch

Requirements: Python >= 3.11, git, Claude Code.

git clone https://github.com/Evolutionairy-AI/MINDLAS.git
cd MINDLAS
python -m venv .venv
source .venv/bin/activate       # macOS / Linux
# .venv\Scripts\activate        # Windows
pip install -e .

mindlas status --demo context_rot_alert                    # a real ALERT, right now
mindlas context repair --apply --demo context_rot_alert    # watch the correction land: 100 -> 4

Already installed from PyPI? pip install mindlas skips the clone and the venv — run the two demo commands directly.

The demo runs the full loop offline against a bundled fixture. Every frame is labeled demo; live sessions earn their own numbers.

Wire it into your live sessions

Two pieces: the hooks, which record session events into the ledger the gauges read, and the status line, the always-on gauge readout under your prompt. The status line installs the same way in both options below. For the hooks there are two paths — pick one, never both: running both records every event twice and inflates the gauges.

Option A — plugin (recommended)

Loads the eight hooks and the five correction slash commands. Still standing in the MINDLAS clone from the quickstart, venv active? The plugin dir is simply .:

claude --plugin-dir .                         # hooks + slash commands, loaded as a plugin
mindlas install-statusline                    # the status line (restart Claude Code after)

To use Mindlas on your own project, launch from that project's directory and point --plugin-dir at the clone instead:

cd ~/my-project
claude --plugin-dir ~/path/to/MINDLAS

The plugin's hooks call mindlas by name, so launch claude from the shell where the venv is active; without that PATH they silently do nothing.

The five slash commands drive the corrections on the live session: /mindlas:mindlas-repair, /mindlas:mindlas-verify, /mindlas:mindlas-blast-split, /mindlas:mindlas-loop-stop, /mindlas:mindlas-loop-release. Each is a thin wrapper over its CLI equivalent (see the CLI reference). The gauges surface them in short form: /mindlas-repair is /mindlas:mindlas-repair.

Option B — CLI install (the PyPI path)

Use this when you installed Mindlas from PyPI — the plugin directory ships with the git clone, not the wheel — or when your setup can't load plugins. It wires the same eight hooks directly into Claude Code's settings.json:

pip install mindlas                           # from PyPI; skip if you already installed from the clone
mindlas install-hooks                         # the same eight hooks (restart Claude Code after)
mindlas install-statusline                    # the status line