@unerr-ai/unerr 0.2.8 → 0.2.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -65
- package/dist/cli.js +1776 -2313
- package/package.json +9 -21
- package/scripts/postinstall.mjs +0 -312
package/README.md
CHANGED
|
@@ -7,11 +7,12 @@
|
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
and the standard it's about to
|
|
10
|
+
Every tool built to help hands your agent <em>advice it can ignore</em> — a memory it has to remember to check,<br/>
|
|
11
|
+
a graph it has to choose to query, a reviewer that only speaks up after the break is already written.<br/>
|
|
12
|
+
<strong>unerr is the guardrail it can't skip.</strong> The moment your agent edits a function, unerr puts the live call graph<br/>
|
|
13
|
+
and the rule you pinned to that exact function <em>into the edit itself</em> — automatically, not on request — and re-anchors<br/>
|
|
14
|
+
that rule when the code moves, so it never goes quietly stale. The 24 callers and the standard it's about to break are<br/>
|
|
15
|
+
on screen <em>before</em> the function changes. Every time. Whether or not the agent thought to ask.
|
|
15
16
|
</p>
|
|
16
17
|
|
|
17
18
|
<p align="center">
|
|
@@ -33,60 +34,59 @@
|
|
|
33
34
|
<sub>Zero configuration. Install, restart your IDE, and the next prompt already knows your repo.</sub>
|
|
34
35
|
</p>
|
|
35
36
|
|
|
36
|
-
<p align="center">
|
|
37
|
-
<sub><strong>It nets your context down, not up.</strong> Five separate MCP servers burn ~55K tokens of schemas just to announce themselves;<br/>
|
|
38
|
-
unerr is one runtime whose tools load on demand, and each edit injects a single scoped line — the rule for the entity in front of it.<br/>
|
|
39
|
-
Measured: the agent lands on the right code with <strong>86–90% fewer tokens</strong>, same corpus, same tokenizer, with a fidelity gate<br/>
|
|
40
|
-
that discards any "saving" that lost the answer. <a href="./benchmarks/README.md">See the benchmarks →</a></sub>
|
|
41
|
-
</p>
|
|
42
|
-
|
|
43
37
|
---
|
|
44
38
|
|
|
45
39
|
<details>
|
|
46
40
|
<summary><strong>Contents</strong></summary>
|
|
47
41
|
|
|
48
|
-
- [
|
|
42
|
+
- [The gap nobody else closes](#the-gap-nobody-else-closes)
|
|
49
43
|
- [The pains this fixes](#the-pains-this-fixes)
|
|
50
44
|
- [What changes when you install it](#what-changes-when-you-install-it)
|
|
51
45
|
- [See it in action](#see-it-in-action)
|
|
52
46
|
- [Quick Start](#quick-start)
|
|
53
47
|
- [Who it's for](#who-its-for)
|
|
54
|
-
- [Why one runtime, not five
|
|
48
|
+
- [Why a guardrail has to be one runtime, not five tools](#why-a-guardrail-has-to-be-one-runtime-not-five-tools)
|
|
55
49
|
- [How the runtime works](#how-the-runtime-works)
|
|
50
|
+
- [Fewer tokens, as a side effect](#fewer-tokens-as-a-side-effect)
|
|
56
51
|
- [License](#license)
|
|
57
52
|
|
|
58
53
|
</details>
|
|
59
54
|
|
|
60
55
|
---
|
|
61
56
|
|
|
62
|
-
##
|
|
57
|
+
## The gap nobody else closes
|
|
63
58
|
|
|
64
|
-
On a small or greenfield project the agent holds the whole repo in its head and
|
|
59
|
+
On a small or greenfield project the agent holds the whole repo in its head and reading the live code is enough — you don't need us. The wall is the *large, existing, multi-contributor* codebase, and it's the same wall every time: the agent can't fit the whole thing in context, so it acts on the slice it can see and never reads the rest. It changes a signature and breaks 7 of 24 callers it never read. It writes a fourth copy of a pattern your team standardized months ago — even with the rule spelled out in `.cursorrules`. Neither shows up as an error. They show up as a senior engineer's afternoon.
|
|
65
60
|
|
|
66
|
-
|
|
61
|
+
The knowledge that would have stopped it — who calls this function, which pattern is load-bearing — already exists. The whole market is built on getting that knowledge to the agent. And it falls into two shapes, both of which leak:
|
|
67
62
|
|
|
68
|
-
|
|
63
|
+
| What it does | The shape | Why it leaks |
|
|
64
|
+
|---|---|---|
|
|
65
|
+
| **Tells the agent things.** Memory stores, code-graph servers, context packers, rule files. | A tool the agent calls *when it remembers to.* | Optional context is optional. Agents skip the retrieval tool **~58% of the time even when explicitly told to use it** ([CodeCompass, 2026](https://arxiv.org/abs/2602.20048)). Advice it can ignore, it ignores. |
|
|
66
|
+
| **Checks the agent afterward.** Reviewers, linters, CI gates. | A pass over the diff *after the code is written.* | The break already happened. Now it's a comment on a pull request and a second round of work — not a change that never broke anything. |
|
|
69
67
|
|
|
70
|
-
|
|
68
|
+
There's a third shape, and almost no one ships it: **guidance wired into the moment of the edit, that the agent can't route around, and that re-anchors itself when the code moves so it never goes quietly stale.** Not a tool it chooses to consult. Not a review after the fact. A guardrail that fires *as it edits* — and stays true to the code because it's recomputed from the code, not from a doc that rots.
|
|
69
|
+
|
|
70
|
+
That's unerr. The agent doesn't have to ask. Before the edit lands, it already sees the callers it would break and the standard it's about to violate.
|
|
71
71
|
|
|
72
72
|
| The old way | With unerr |
|
|
73
73
|
|---|---|
|
|
74
|
-
| The agent changes a function without reading its 24 callers — 7 sites break silently. | **Cascade guard**
|
|
75
|
-
|
|
|
76
|
-
|
|
|
74
|
+
| The agent changes a function without reading its 24 callers — 7 sites break silently. | **Cascade guard** puts the call graph in front of the edit *before it runs* — every caller on screen, no asking required. |
|
|
75
|
+
| You wrote the rule in `.cursorrules`. The agent acknowledged it, then ignored it once context filled up. | **Anchored rules** surface the standard the instant the agent touches that scope — and re-anchor when the code moves instead of going stale. |
|
|
76
|
+
| A rule or spec stays confident long after the code moved out from under it. Nothing recomputes it. | Every fact is pinned to a live entity in the graph. When the code moves, the fact **fails loud** instead of staying silently wrong. |
|
|
77
77
|
|
|
78
78
|
---
|
|
79
79
|
|
|
80
80
|
## The pains this fixes
|
|
81
81
|
|
|
82
|
-
|
|
82
|
+
You know this feeling, and it gets *worse* as the repo grows, not better:
|
|
83
83
|
|
|
84
|
-
-
|
|
85
|
-
- You don't trust it to
|
|
86
|
-
-
|
|
87
|
-
-
|
|
84
|
+
- **You're babysitting it.** You can't fire-and-forget, because the one time you look away is the time it quietly breaks something load-bearing. You've become its scheduler and its safety net at once.
|
|
85
|
+
- **You don't trust it to touch anything important.** It treats your codebase as a flat wall of text — locally correct, globally wrong — so the load-bearing changes still land on you.
|
|
86
|
+
- **The rule you wrote gets acknowledged, then dropped.** A few turns later the context fills up and your `.cursorrules` line may as well not exist.
|
|
87
|
+
- **Approval fatigue.** You approve so many reasonable edits that the dangerous one slides through — the hundredth confirmation looks exactly like the first.
|
|
88
88
|
|
|
89
|
-
These aren't four problems. They're one: **
|
|
89
|
+
These aren't four problems. They're one: **the agent acts on a codebase it can't hold in its head, and nothing it can't bypass is watching the change.** You babysit because there's no guardrail it can't skip. unerr is that guardrail — so you can look away.
|
|
90
90
|
|
|
91
91
|
---
|
|
92
92
|
|
|
@@ -94,16 +94,16 @@ These aren't four problems. They're one: **your agent acts on a codebase it can'
|
|
|
94
94
|
|
|
95
95
|
| You feel | What unerr does |
|
|
96
96
|
|---|---|
|
|
97
|
-
| **
|
|
98
|
-
| **Your rules finally get honored.** The standard you set is
|
|
99
|
-
| **
|
|
100
|
-
| **
|
|
97
|
+
| **You stop babysitting.** The agent runs for an hour and you're not bracing for a silent break. | Every edit is preceded — automatically — by a graph lookup. All 24 callers are visible *before* it touches the function. The guardrail fires whether or not the agent thought to ask. |
|
|
98
|
+
| **Your rules finally get honored.** The standard you set is applied at the edit, not acknowledged and forgotten. | unerr pins each rule and decision to the file or entity it governs and surfaces it the instant the agent touches that scope — then re-anchors it when the code moves. Keep your `.cursorrules` and specs; unerr makes sure they're actually applied. |
|
|
99
|
+
| **It stops thrashing.** No more watching it retry the same broken fix three times. | A **loop breaker** watches the timeline and stops the agent re-trying a change that already failed twice — before it burns your turn and your patience. |
|
|
100
|
+
| **The agent stays sharp at turn 50.** | `file_read({entity})` returns 200 lines instead of 3,000; shell output is trimmed automatically. The window stays uncluttered, so the model isn't fighting "lost in the middle." |
|
|
101
101
|
|
|
102
|
-
**What it looks like in your chat** — before the Edit tool runs, unerr injects this into the agent's context:
|
|
102
|
+
**What it looks like in your chat** — before the Edit tool runs, unerr injects this into the agent's context, on its own:
|
|
103
103
|
|
|
104
104
|
> ⚡ unerr · cascade guard: editing `src/payments/gateway.ts` changes a signature with callers that must be updated in the same change — `processPayment`: **24 callers at risk across 6 files** (19 source, 5 test). Call `get_references({key:'processPayment', direction:'callers'})` and update every caller before finishing.
|
|
105
105
|
|
|
106
|
-
The outcome
|
|
106
|
+
The outcome: **agents that behave like senior engineers** — checking dependencies before editing, honoring the standard, and refusing to thrash on a function they've already failed on three times.
|
|
107
107
|
|
|
108
108
|
---
|
|
109
109
|
|
|
@@ -118,19 +118,19 @@ The outcome you get is **agents that behave like senior engineers** — checking
|
|
|
118
118
|
|
|
119
119
|
Two places unerr shows up so you know it's working — inside the chat, and in a browser.
|
|
120
120
|
|
|
121
|
-
**Inside the chat.** Every coding turn opens with one line naming what unerr loaded ("loaded a convention you wrote yesterday for `src/payments/gateway.ts`…") and closes with one line totalling what it saved
|
|
121
|
+
**Inside the chat.** Every coding turn opens with one line naming what unerr loaded ("loaded a convention you wrote yesterday for `src/payments/gateway.ts`…") and closes with one line totalling what it caught and saved ("this turn: 2 catches · ≈ 4.2k tokens saved · +5 turns of headroom this session"). Catches are *named, countable events*, not a ratio.
|
|
122
122
|
|
|
123
|
-
**In a browser.** A live dashboard at `http://localhost:9847` reads from the same store the agent reads from over MCP — the graph it navigates, the facts it remembers, the
|
|
123
|
+
**In a browser.** A live dashboard at `http://localhost:9847` reads from the same store the agent reads from over MCP — the graph it navigates, the facts it remembers, the breaks it caught, and the score showing which of those facts actually shaped the next answer.
|
|
124
124
|
|
|
125
125
|
<p align="center">
|
|
126
126
|
<img src="https://unerr.dev/open-cli/screenshots/end-of-turn-receipt.png" alt="unerr end-of-turn receipt — tokens saved and headroom kept open this turn" width="380" />
|
|
127
127
|
<img src="https://unerr.dev/open-cli/screenshots/end-of-turn-receipt-2.png" alt="unerr end-of-turn receipt — named, countable catches totalled at the close of a turn" width="380" />
|
|
128
|
-
<br/><sub><strong>End-of-turn receipt</strong> · every coding turn closes with one line totalling what unerr saved you — named, countable catches, not a ratio.</sub>
|
|
128
|
+
<br/><sub><strong>End-of-turn receipt</strong> · every coding turn closes with one line totalling what unerr caught and saved you — named, countable catches, not a ratio.</sub>
|
|
129
129
|
</p>
|
|
130
130
|
|
|
131
131
|
<p align="center">
|
|
132
132
|
<img src="https://unerr.dev/open-cli/screenshots/dashboard.png" alt="unerr dashboard — live overview" width="300" />
|
|
133
|
-
<br/><sub><strong>Dashboard</strong> · live overview — active sessions, recent tool calls, tokens the agent skipped this turn.</sub>
|
|
133
|
+
<br/><sub><strong>Dashboard</strong> · live overview — active sessions, recent tool calls, breaks caught, tokens the agent skipped this turn.</sub>
|
|
134
134
|
</p>
|
|
135
135
|
|
|
136
136
|
<p align="center">
|
|
@@ -176,9 +176,9 @@ Install multiple agents in the same repo — each writes its own config. Idempot
|
|
|
176
176
|
|
|
177
177
|
### 3. Restart your IDE
|
|
178
178
|
|
|
179
|
-
Close and reopen your IDE (or start a new chat session). Your agent picks up unerr through MCP — graph-backed tools, persistent memory,
|
|
179
|
+
Close and reopen your IDE (or start a new chat session). Your agent picks up unerr through MCP — graph-backed tools, persistent memory, the edit-time guardrail all available immediately.
|
|
180
180
|
|
|
181
|
-
> **Dashboard:** <http://localhost:9847> — open any time to watch unerr
|
|
181
|
+
> **Dashboard:** <http://localhost:9847> — open any time to watch unerr at work in real time.
|
|
182
182
|
|
|
183
183
|
> Need manual setup or any other MCP client? `unerr install --show-instructions <agent>` prints copy-pasteable steps.
|
|
184
184
|
|
|
@@ -187,49 +187,53 @@ Close and reopen your IDE (or start a new chat session). Your agent picks up une
|
|
|
187
187
|
## Who it's for
|
|
188
188
|
|
|
189
189
|
- **Engineers on large, existing codebases.** The dependency graph, the load-bearing patterns, and the prior incidents a senior engineer carries in their head — handed to the agent before every edit, so it stops breaking callers it never read.
|
|
190
|
-
- **Teams with conventions worth enforcing.** The standard you agreed on once, applied every time the agent touches that scope — no `.cursorrules` file to hand-maintain, re-paste, or merge-conflict over.
|
|
190
|
+
- **Teams with conventions worth enforcing.** The standard you agreed on once, applied every time the agent touches that scope — no `.cursorrules` file to hand-maintain, re-paste, or merge-conflict over, and no hoping the agent remembers to look.
|
|
191
191
|
- **Solo builders shipping into a codebase that's already grown.** The continuous thread across tools — switch from Claude Code in the terminal to Cursor in the IDE and the graph, rules, and history come with you, instead of relearning the repo every session.
|
|
192
192
|
|
|
193
193
|
---
|
|
194
194
|
|
|
195
|
-
## Why one runtime, not five
|
|
196
|
-
|
|
197
|
-
**unerr is the layer your agents share — sitting *behind* every MCP they already speak.** Every coding agent on your machine — Claude Code, Cursor, Windsurf, Antigravity — speaks MCP. MCP carries tool calls; it does not carry context. Without unerr, every agent rebuilds your codebase's dependency graph, conventions, and prior decisions from scratch — every session, by reading files blindly. With unerr, all of them read the same per-repo runtime over MCP, so your project's graph, memory, and guardrails carry across sessions *and* across IDEs.
|
|
195
|
+
## Why a guardrail has to be one runtime, not five tools
|
|
198
196
|
|
|
199
|
-
|
|
197
|
+
A guardrail the agent *can't skip* can't be a tool the agent chooses to call. That's the whole reason unerr is one local runtime sitting *behind* the MCP every agent already speaks — not a fifth server in the agent's tool list.
|
|
200
198
|
|
|
201
|
-
|
|
202
|
-
|---|---|---|
|
|
203
|
-
| Memory across sessions | dedicated memory tools | Memory tied to the *current* state of the code — facts get drift signals when the file they're about moves. |
|
|
204
|
-
| Code-graph navigation | dedicated code-graph tools | The graph is read *before every file read* — surgical context instead of 3,000-line dumps. |
|
|
205
|
-
| Output compression | dedicated compression tools | Compression is fed through the same MCP runtime as the graph and memory, not a separate tool the agent has to remember to invoke. |
|
|
206
|
-
| Convention enforcement | `.cursorrules`, CLAUDE.md hand-maintained | Conventions auto-detected from ≥70% adherence in the code. No file to maintain. |
|
|
199
|
+
Every coding agent on your machine — Claude Code, Cursor, Windsurf, Antigravity — speaks MCP. MCP carries tool calls; it does not carry context, and it does not fire anything on its own. So a memory server, a graph server, and a compressor sit there *waiting to be invoked* — and an agent under context pressure skips them. unerr instead intercepts at the moment that matters — the read, the edit — and injects the one scoped thing that's relevant, automatically. The agent can't forget to call something that isn't waiting to be called.
|
|
207
200
|
|
|
208
|
-
|
|
201
|
+
That only works if the pieces live in **one** process. The guardrails worth having each fire on a *join* no single tool can make:
|
|
209
202
|
|
|
210
|
-
|
|
203
|
+
- **Cascade guard** needs the call graph *and* the edit-intent ledger on the same process, at the same instant.
|
|
204
|
+
- **Drift** needs memory that's anchored to a live graph — so the fact knows the moment its code moved.
|
|
205
|
+
- **Convention drift** needs the auto-detected pattern store *and* the new-code stream in the same memory space.
|
|
206
|
+
- **Loop breaker** needs the full timeline of what the agent already tried.
|
|
211
207
|
|
|
212
|
-
|
|
213
|
-
- **Tool-selection accuracy collapses 58% → 26% as MCP tools go from 9 to 51** ([LangChain ReAct benchmark](https://blog.langchain.com/react-agent-benchmarking/)) — unerr is one MCP runtime instead of five, freeing the agent's tool-selection budget. Anthropic itself acknowledged this in Jan 2026 by shipping [MCP Tool Search](https://www.anthropic.com/engineering/code-execution-with-mcp) to hide tool definitions until queried.
|
|
214
|
-
- **0** LLM calls per query in the core — facts, conventions, drift signals, and graph lookups are all algorithmic. No API keys, no per-turn inference cost, no telemetry.
|
|
215
|
-
- **86–90%** of an agent's code-navigation tokens removed in head-to-head benchmarks vs grep+read — real tokenizer, fidelity-gated, reproducible on any repo ([benchmarks](./benchmarks/README.md)).
|
|
208
|
+
These aren't features you can buy individually and bolt together. They're emergent properties of one runtime — and they're exactly what turns "context the agent might read" into "a guardrail it can't skip."
|
|
216
209
|
|
|
217
210
|
---
|
|
218
211
|
|
|
219
212
|
## How the runtime works
|
|
220
213
|
|
|
221
|
-
One local process per repo. Four
|
|
214
|
+
One local process per repo. Four mechanisms, joined deterministically — the **mechanisms** are how; the **guardrail** is what you get.
|
|
222
215
|
|
|
223
|
-
|
|
|
216
|
+
| Mechanism (the how) | What's inside | What it powers (the what) |
|
|
224
217
|
|---|---|---|
|
|
225
|
-
| **Live code graph** | CozoDB · tree-sitter ASTs · SCIP-verified call graphs · 18+ languages · <5ms queries |
|
|
218
|
+
| **Live code graph** | CozoDB · tree-sitter ASTs · SCIP-verified call graphs · 18+ languages · <5ms queries | The agent opens 50 targeted lines and a caller list — not 3,000 lines and a guess. Read *before every file read*, so cascade guard knows what an edit breaks. |
|
|
226
219
|
| **Anchored memory** | Typed facts · conventions auto-detected at ≥70% adherence · decay-adjusted confidence | Every fact is pinned to a file or entity in the graph. When the code moves, the fact gets a **drift signal** — never silent staleness. |
|
|
227
|
-
| **Context delivery** | Shell output compression (
|
|
228
|
-
| **Behaviour modules** | cascade guard · convention drift · loop breaker · session continuity · auto-doc · change narrative · architecture guard | Each guardrail fires on a
|
|
220
|
+
| **Context delivery** | Shell output compression (645+ command classifiers) · web fetches (5–10× via Defuddle + BM25) · entity-targeted file reads | The relevant slice arrives automatically at the read — the agent never has to remember which tool to invoke for which content. |
|
|
221
|
+
| **Behaviour modules** | cascade guard · convention drift · loop breaker · session continuity · auto-doc · change narrative · architecture guard | Each guardrail fires on a join of the three above, *at the moment of the edit* — not as a tool the agent chose, not as a review after the fact. |
|
|
222
|
+
|
|
223
|
+
**The unifying point.** Drift detection requires memory anchored to a live graph. Cascade guard requires the graph and the edit-intent ledger on one process. Convention drift requires the pattern store and the new-code stream in the same memory space. Spread these across five disconnected MCP servers and none of them can fire — they can only sit and wait to be called, which is the failure mode this whole thing exists to fix. That's the difference between a stack of tools and a guardrail.
|
|
224
|
+
|
|
225
|
+
---
|
|
229
226
|
|
|
230
|
-
|
|
227
|
+
## Fewer tokens, as a side effect
|
|
228
|
+
|
|
229
|
+
unerr was built to stop bad changes, not to save tokens. But a guardrail that only ever hands over *the one scoped fact that matters* — the rule for the entity in front of the agent, 50 lines instead of 3,000 — spends far fewer tokens almost by accident. So you get this for free:
|
|
230
|
+
|
|
231
|
+
- **86–90%** of an agent's code-navigation tokens removed in head-to-head benchmarks vs grep+read — real tokenizer, fidelity-gated (any "saving" that lost the answer is discarded), reproducible on any repo. [See the benchmarks →](./benchmarks/README.md)
|
|
232
|
+
- **~84%** of an AI coding agent's tokens are tool output, mostly file reads ([JetBrains, NeurIPS 2025](https://blog.jetbrains.com/research/2025/12/efficient-context-management/)) — unerr intercepts at the read layer, so the window isn't diluted.
|
|
233
|
+
- **Tool-selection accuracy collapses 58% → 26% as MCP tools go from 9 to 51** ([LangChain ReAct benchmark](https://blog.langchain.com/react-agent-benchmarking/)) — unerr is one runtime instead of five servers, so it doesn't eat the agent's tool-selection budget. Anthropic itself acknowledged this in Jan 2026 by shipping [MCP Tool Search](https://www.anthropic.com/engineering/code-execution-with-mcp).
|
|
234
|
+
- **0** LLM calls per query in the core — facts, conventions, drift signals, and graph lookups are all algorithmic. No API keys, no per-turn inference cost, no telemetry.
|
|
231
235
|
|
|
232
|
-
|
|
236
|
+
The point was never the token number. It's that the agent lands on the right code, sees the right guardrail, and you stop paying — in tokens *and* in afternoons — for the changes it would otherwise have to undo.
|
|
233
237
|
|
|
234
238
|
---
|
|
235
239
|
|
|
@@ -263,7 +267,7 @@ One local DB per repo. Zero network calls. No API keys. No cloud. Your code neve
|
|
|
263
267
|
|
|
264
268
|
Full module map and source-tree breakdown: **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)**.
|
|
265
269
|
|
|
266
|
-
**Design principles** — zero network calls; stdout is sacred (MCP JSON-RPC only, everything else to stderr); <5 ms query responses; first useful output <5 s (shallow index first, deep enrichment in background); graceful degradation (the agent still works if unerr is down, you just lose the
|
|
270
|
+
**Design principles** — zero network calls; stdout is sacred (MCP JSON-RPC only, everything else to stderr); <5 ms query responses; first useful output <5 s (shallow index first, deep enrichment in background); graceful degradation (the agent still works if unerr is down, you just lose the guardrail layer).
|
|
267
271
|
|
|
268
272
|
**Tech stack** TypeScript (ESM) · CozoDB (Rust/NAPI) · web-tree-sitter (WASM) · MCP SDK · Ink (React CLI) · React + Vite (dashboard) · tsup · Vitest
|
|
269
273
|
|