---
name: laserbrain-local
description: >
  Catch your own drift on one machine, offline. Use for any multi-step task long enough
  that step forty looks fine next to step thirty-nine and nothing like step one —
  refactors, migrations, debugging, research. No key, no account, no network.
---

# laserbrain — local

You cannot catch your own drift by looking at yourself. Each step looks reasonable next to
the last one while the whole run walks away from what was asked. More care does not fix
this; it is what happens when the only reference you have is where you just were.

This gives you a **fixed** reference instead. The first state you spell is frozen as the
ground, and every later reading is measured against **that** — not against the previous
step.

Everything here runs on your machine. Nothing is sent anywhere.

## Setup

```bash
pip install laserbrain
```

```json
{ "mcpServers": { "laserbrain": { "command": "laserbrain", "args": ["mcp"] } } }
```

That is the whole installation. `laserbrain mcp` speaks JSON-RPC on stdin and stdout, has
no dependencies, and the check is a pure function that keeps working with the network
unplugged.

## How to use it

**Call `check_state` every step.** Not when you feel lost — by then the reading is late,
and self-noticed drift is the rare kind.

```
check_state(goal="build the JSON parser", progress="advancing", distance=6)
```

- `goal` — what you are working on, in your own words. The FIRST one becomes the ground.
- `progress` — `advancing`, `stuck`, or `circling`. **Honestly.** A false `advancing` is
  worse than no reading, because it looks like one.
- `distance` — how far from done, 0 to 10.

**When it says you are drifting, return.** `goal-drift` means you are working on something
the ground does not contain — usually something reasonable that nobody asked for.

**Call `reset_task` when the task genuinely changes**, i.e. when the user redirects you.
Not to escape a drift verdict. Resetting to clear a warning is the one move that makes the
whole instrument worthless, and it leaves no trace afterward.

## Reading a verdict

| verdict | what it means |
|---|---|
| `grounded` | the ground is set — this is where you started |
| `advancing` | on track |
| `goal-drift` | you are somewhere the ground does not contain — **return** |
| `stalled` | motion without progress; distance stopped falling |
| `circling` | the same action repeating |
| `ungrammatical` | the reading itself was malformed |
| `self-report` | your own account and the tool trace disagree |
| `reground` | the ground moved because the task did |
| `excursion` | a deliberate departure, still anchored |

`Φ` is the displacement. Under 0.30 is fine; above it, the fixed reference is telling you
something you cannot tell yourself.

## The rest of the tools

- **`get_history`** — what you spelled this session, and how much of it was drifting.
- **`similarity`** — token overlap between two statements. Good for "is this the same goal
  restated, or a different goal?"
- **`laserscore`** — a one-line reading without touching a ground.
- **`capabilities`** — what works offline here, and what does not.

## What this cannot do

It watches **one agent on one machine**, and only while the process is alive. It cannot see
another agent, page you when you are away, or remember anything after the pipe closes.

Those need a server — see `laserbrain-group`. This one is complete as it is, and free
forever: the detector is not a trial version, it is the same detector every paid tier uses.

It also cannot make you honest. `progress` is your own report. The single most useful thing
you can do with this tool is say `stuck` when you are stuck.