@unerr-ai/unerr 0.1.9 → 0.2.1
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 +156 -333
- package/dist/cli.js +14570 -4208
- package/dist/rules/developer.mozilla.org.json +9 -0
- package/dist/rules/github.com.json +21 -0
- package/package.json +7 -2
package/README.md
CHANGED
|
@@ -1,22 +1,24 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<a href="https://www.unerr.dev/"><img src="https://unerr.dev/icon-wordmark.svg" alt="unerr —
|
|
2
|
+
<a href="https://www.unerr.dev/"><img src="https://unerr.dev/icon-wordmark.svg" alt="unerr — operational memory for your codebase" width="320" /></a>
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>
|
|
6
|
+
<strong>Stop babysitting your AI.</strong>
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
10
|
-
|
|
11
|
-
|
|
10
|
+
<strong>unerr is operational memory for your codebase</strong> — one local runtime that sits <em>behind</em> every MCP<br/>
|
|
11
|
+
your coding agent already speaks, carrying a shared code graph, persistent memory,<br/>
|
|
12
|
+
drift detection, and the guardrails the protocol itself doesn't.
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<sub><strong>Works with</strong> Cursor · Claude Code · Windsurf · Gemini CLI · Antigravity · GitHub Copilot CLI · and every MCP-compatible client.</sub>
|
|
12
17
|
</p>
|
|
13
18
|
|
|
14
19
|
<p align="center">
|
|
15
|
-
<a href="https://www.unerr.dev/"><img src="https://img.shields.io/badge/website-unerr.dev-8B5CF6?style=flat-square&logo=icloud&logoColor=white" alt="Website" /></a>
|
|
16
20
|
<a href="https://www.npmjs.com/package/@unerr-ai/unerr"><img src="https://img.shields.io/badge/install-npm_i_@unerr--ai/unerr-8B5CF6?style=flat-square&logo=npm" alt="Install" /></a>
|
|
17
|
-
<a href="https://
|
|
18
|
-
<a href="https://x.com/unerr_ai"><img src="https://img.shields.io/badge/follow-@unerr__ai-000000?style=flat-square&logo=x&logoColor=white" alt="X / Twitter" /></a>
|
|
19
|
-
<a href="https://www.linkedin.com/company/unerr"><img src="https://img.shields.io/badge/linkedin-unerr-0A66C2?style=flat-square&logo=linkedin&logoColor=white" alt="LinkedIn" /></a>
|
|
21
|
+
<a href="https://www.unerr.dev/"><img src="https://img.shields.io/badge/website-unerr.dev-8B5CF6?style=flat-square&logo=icloud&logoColor=white" alt="Website" /></a>
|
|
20
22
|
<img src="https://img.shields.io/badge/runtime-Node.js_≥20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js" />
|
|
21
23
|
<img src="https://img.shields.io/badge/protocol-MCP-7C3AED?style=flat-square" alt="MCP" />
|
|
22
24
|
<img src="https://img.shields.io/badge/local--first-no_cloud-22D3EE?style=flat-square" alt="Local-first" />
|
|
@@ -25,86 +27,81 @@
|
|
|
25
27
|
|
|
26
28
|
<p align="center">
|
|
27
29
|
<code>npm install -g @unerr-ai/unerr</code>
|
|
30
|
+
<br /><br />
|
|
31
|
+
<sub>Zero configuration. Install, restart your IDE, and the next prompt is smarter.</sub>
|
|
32
|
+
</p>
|
|
33
|
+
|
|
34
|
+
<p align="center">
|
|
35
|
+
<sub>Measured, not estimated: removes <strong>86–90%</strong> of the tokens an agent spends navigating code —<br/>
|
|
36
|
+
and wins head-to-head against other code-intelligence tools on the same corpus. <a href="./benchmarks/README.md">See the benchmarks →</a></sub>
|
|
28
37
|
</p>
|
|
29
38
|
|
|
30
39
|
---
|
|
31
40
|
|
|
32
|
-
## The
|
|
41
|
+
## The pains this fixes
|
|
33
42
|
|
|
34
|
-
|
|
43
|
+
You've felt all four of these in the last 48 hours:
|
|
35
44
|
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
45
|
+
- Claude is brilliant for 20 minutes, then hallucinates a duplicate component and forgets the styling rules you set five turns ago.
|
|
46
|
+
- More time spent writing `MEMORY.md`, updating `.cursorrules`, and pasting session summaries than writing code.
|
|
47
|
+
- The agent reads a 2,000-line file to find a 5-line function, then still doesn't know that function has 24 callers across three services.
|
|
48
|
+
- You don't trust the agent to refactor anything important. It treats your codebase like a flat string of text — locally correct, globally wrong.
|
|
40
49
|
|
|
41
|
-
|
|
50
|
+
These aren't four problems. They're one: today's agents are incredibly smart but structurally blind and severely amnesiac. They grep when a senior engineer would check the call graph. They forget on Tuesday what they learned on Monday.
|
|
42
51
|
|
|
43
52
|
---
|
|
44
53
|
|
|
45
|
-
## What you
|
|
54
|
+
## What changes when you install it
|
|
46
55
|
|
|
47
|
-
|
|
56
|
+
| You feel | What unerr does |
|
|
57
|
+
|---|---|
|
|
58
|
+
| **Trust returns.** The agent runs for an hour without you watching. | Every edit is preceded by a graph lookup. All 24 callers are visible *before* it touches the function. Refactors stop rippling silently. |
|
|
59
|
+
| **The babysitter tax disappears.** You delete `MEMORY.md` and `.cursorrules`. | A local fact store remembers what you decided, what failed, and the conventions the team accreted — with decay-adjusted confidence. Open the laptop on Tuesday and the agent already knows what you decided on Monday. |
|
|
60
|
+
| **The agent stays sharp at turn 50.** | `file_read({entity})` returns 200 lines instead of 3,000. Shell output is compressed 93% on average. The context window stays uncluttered, so the model isn't fighting "lost in the middle." |
|
|
61
|
+
| **Tool sprawl dies.** | One graph, one set of tools, project-aware routing. Five MCP servers no longer compete for the agent's attention. |
|
|
48
62
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
63
|
+
**What it looks like in your chat:**
|
|
64
|
+
|
|
65
|
+
> ⚡ unerr · cascade guard: `PaymentGateway` has 8 callers across 3 services. Call `get_references({direction:'callers'})` before the edit — refactor it locally and 7 sites break silently.
|
|
66
|
+
|
|
67
|
+
The outcome you get is **agents that behave like senior engineers** — checking dependencies before editing, remembering project history, refusing to thrash on a function they've already failed on three times.
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## See it in action
|
|
72
|
+
|
|
73
|
+
Two places unerr shows up so you know it's working — inside the chat, and in a browser.
|
|
55
74
|
|
|
56
|
-
|
|
75
|
+
**Inside the chat.** Every coding turn opens with one line naming what unerr loaded ("loaded a convention you wrote yesterday for `src/proxy/proxy.ts`…") and closes with one line totalling what it saved you ("this turn: 2 catches · ≈ 4.2k tokens saved · +5 turns of headroom this session"). Catches are *named, countable events*, not a ratio.
|
|
57
76
|
|
|
58
|
-
|
|
77
|
+
**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 tokens it didn't have to chew through, and the score showing which of those facts actually shaped the next answer.
|
|
59
78
|
|
|
60
79
|
<p align="center">
|
|
61
|
-
<img src="https://unerr.dev/open-cli/
|
|
80
|
+
<img src="https://unerr.dev/open-cli/screenshots/dashboard.png" alt="unerr dashboard — live overview" width="300" />
|
|
81
|
+
<br/><sub><strong>Dashboard</strong> · live overview — active sessions, recent tool calls, tokens the agent skipped this turn.</sub>
|
|
62
82
|
</p>
|
|
63
83
|
|
|
64
|
-
<
|
|
65
|
-
<
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
<img src="https://unerr.dev/open-cli/screenshots/reasoning-quality.png" alt="unerr reasoning quality — global" width="240" height="150" />
|
|
86
|
-
<br/><sub><strong>Reasoning Quality · global</strong><br/>Four-pillar score across cleaner context, fewer wasted turns, fewer breakages, persistent memory.</sub>
|
|
87
|
-
</td>
|
|
88
|
-
<td align="center" width="240">
|
|
89
|
-
<img src="https://unerr.dev/open-cli/screenshots/reasoning-session.png" alt="unerr reasoning quality — session" width="240" height="150" />
|
|
90
|
-
<br/><sub><strong>Reasoning Quality · session</strong><br/>Per-session: which facts and conventions were reinforced, acted on, ignored, or corrected.</sub>
|
|
91
|
-
</td>
|
|
92
|
-
<td align="center" width="240">
|
|
93
|
-
<img src="https://unerr.dev/open-cli/screenshots/code-base-intelligence.png" alt="unerr code intelligence" width="240" height="150" />
|
|
94
|
-
<br/><sub><strong>Code Intelligence</strong><br/>Call graph, fan-in/out chokepoints, cross-module surprise links, and a risk grade per file.</sub>
|
|
95
|
-
</td>
|
|
96
|
-
<td align="center" width="240">
|
|
97
|
-
<img src="https://unerr.dev/open-cli/screenshots/project-memory.png" alt="unerr project memory — facts" width="240" height="150" />
|
|
98
|
-
<br/><sub><strong>Project Memory</strong><br/>Conventions, anti-patterns, decisions — with decay-adjusted confidence and reinforcement counts.</sub>
|
|
99
|
-
</td>
|
|
100
|
-
</tr>
|
|
101
|
-
<tr>
|
|
102
|
-
<td align="center" width="240" colspan="4">
|
|
103
|
-
<img src="https://unerr.dev/open-cli/screenshots/activity.png" alt="unerr activity — timeline + heatmap" width="240" height="150" />
|
|
104
|
-
<br/><sub><strong>Activity</strong><br/>Turn-grouped timeline with a 30-day heatmap — each row is one burst of agent work (intent → tools → outcome).</sub>
|
|
105
|
-
</td>
|
|
106
|
-
</tr>
|
|
107
|
-
</table>
|
|
84
|
+
<p align="center">
|
|
85
|
+
<img src="https://unerr.dev/open-cli/screenshots/activity.png" alt="unerr activity — session timeline" width="300" />
|
|
86
|
+
<br/><sub><strong>Activity</strong> · session timeline — every tool call, marker, and catch in order, replayable across sessions.</sub>
|
|
87
|
+
</p>
|
|
88
|
+
|
|
89
|
+
<p align="center">
|
|
90
|
+
<img src="https://unerr.dev/open-cli/screenshots/token-trace-main.png" alt="unerr token trace" width="300" />
|
|
91
|
+
<br/><sub><strong>Token Trace</strong> · context kept out of the window, broken down by mechanism — graph hits, skipped re-reads, compressed shell output, deduped fetches.</sub>
|
|
92
|
+
</p>
|
|
93
|
+
|
|
94
|
+
<p align="center">
|
|
95
|
+
<img src="https://unerr.dev/open-cli/screenshots/prompt-trace.png" alt="unerr prompt trace" width="300" />
|
|
96
|
+
<br/><sub><strong>Prompt Trace</strong> · every prompt and the context unerr fed it — what was recalled, and what shaped the response.</sub>
|
|
97
|
+
</p>
|
|
98
|
+
|
|
99
|
+
<p align="center">
|
|
100
|
+
<img src="https://unerr.dev/open-cli/screenshots/reasoning-quality.png" alt="unerr reasoning quality" width="300" />
|
|
101
|
+
<br/><sub><strong>Reasoning Quality</strong> · which remembered facts actually shaped the next answer — scored, so memory earns its place in context.</sub>
|
|
102
|
+
</p>
|
|
103
|
+
|
|
104
|
+
<p align="center"><sub>More views in the <a href="https://www.unerr.dev/">full dashboard tour</a>.</sub></p>
|
|
108
105
|
|
|
109
106
|
---
|
|
110
107
|
|
|
@@ -118,7 +115,7 @@ Three steps. Step 1 is once per machine; steps 2–3 are per repo.
|
|
|
118
115
|
npm install -g @unerr-ai/unerr
|
|
119
116
|
```
|
|
120
117
|
|
|
121
|
-
Puts the `unerr` binary on your PATH. If
|
|
118
|
+
Puts the `unerr` binary on your PATH. If your shell can't find it (common with nvm, fnm, volta, pnpm), run `unerr doctor` once — it patches your shell config and won't need to run again.
|
|
122
119
|
|
|
123
120
|
### 2. Install for your agent (per repo)
|
|
124
121
|
|
|
@@ -127,265 +124,106 @@ cd ~/your-project
|
|
|
127
124
|
unerr install cursor
|
|
128
125
|
```
|
|
129
126
|
|
|
130
|
-
Writes the MCP config, skills, hooks, and instructions for that agent in the current repo. Swap `cursor` for any of the
|
|
131
|
-
|
|
132
|
-
### 3. Restart your IDE
|
|
133
|
-
|
|
134
|
-
Close and reopen your IDE (or start a new chat session). Your agent picks up unerr through MCP — graph-backed tools, persistent memory, shell compression all available immediately.
|
|
135
|
-
|
|
136
|
-
> **Dashboard:** <http://localhost:9847> — open any time to watch token savings, reasoning quality, and the codebase map update as your agent works.
|
|
137
|
-
|
|
138
|
-
### Supported agents
|
|
139
|
-
|
|
140
|
-
```bash
|
|
141
|
-
unerr install claude-code # → .mcp.json + CLAUDE.md + .claude/skills/ + hooks
|
|
142
|
-
unerr install cursor # → .cursor/mcp.json + .cursor/rules/ + hooks
|
|
143
|
-
unerr install antigravity # → .antigravity/mcp_config.json + .agents/rules/ + .agents/skills/
|
|
144
|
-
unerr install windsurf # → ~/.codeium/windsurf/mcp_config.json + .windsurf/rules/ + .windsurf/skills/
|
|
145
|
-
unerr install gemini-cli # → .gemini/settings.json + GEMINI.md + .gemini/skills/
|
|
146
|
-
unerr install github-copilot-cli # → .copilot/mcp-config.json + .github/copilot-instructions.md + .github/skills/
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
Install multiple agents in the same repo — each writes its own config:
|
|
127
|
+
Writes the MCP config, skills, hooks, and instructions for that agent in the current repo. Swap `cursor` for any of the supported agents:
|
|
150
128
|
|
|
151
129
|
```bash
|
|
152
|
-
unerr install cursor
|
|
153
130
|
unerr install claude-code
|
|
131
|
+
unerr install cursor
|
|
132
|
+
unerr install antigravity
|
|
133
|
+
unerr install windsurf
|
|
134
|
+
unerr install gemini-cli
|
|
135
|
+
unerr install github-copilot-cli
|
|
154
136
|
```
|
|
155
137
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
<details>
|
|
159
|
-
<summary>Manual MCP config (any MCP-compatible client)</summary>
|
|
160
|
-
|
|
161
|
-
```json
|
|
162
|
-
{
|
|
163
|
-
"mcpServers": {
|
|
164
|
-
"unerr": {
|
|
165
|
-
"command": "npx",
|
|
166
|
-
"args": ["@unerr-ai/unerr", "--mcp"]
|
|
167
|
-
}
|
|
168
|
-
}
|
|
169
|
-
}
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
</details>
|
|
138
|
+
Install multiple agents in the same repo — each writes its own config. Idempotent: re-running updates if content changed, skips if identical. Remove with `unerr uninstall`.
|
|
173
139
|
|
|
174
|
-
|
|
175
|
-
<summary>What <code>unerr install</code> writes</summary>
|
|
140
|
+
### 3. Restart your IDE
|
|
176
141
|
|
|
177
|
-
|
|
178
|
-
|------|------|
|
|
179
|
-
| MCP config pointing to `unerr --mcp` | `.mcp.json`, `.cursor/mcp.json`, … |
|
|
180
|
-
| Skills — 12 definitions teaching the agent when to use each tool | `.claude/skills/`, `.cursor/rules/`, … |
|
|
181
|
-
| Instructions — tool-routing table injected into the agent's instruction file | `CLAUDE.md`, `.cursor/rules/unerr-instructions.mdc` |
|
|
182
|
-
| Hooks — shell compression + tool-adoption nudging | `.claude/settings.json`, `.cursor/hooks.json` |
|
|
183
|
-
| Gitignore — keeps `.unerr/` out of commits | `.gitignore` |
|
|
184
|
-
| Force tools (Claude Code only) — denies built-in Read/Grep/Glob so the agent uses graph tools. Opt out with `--no-force-tools`. | `.claude/settings.json` |
|
|
142
|
+
Close and reopen your IDE (or start a new chat session). Your agent picks up unerr through MCP — graph-backed tools, persistent memory, shell compression all available immediately.
|
|
185
143
|
|
|
186
|
-
|
|
144
|
+
> **Dashboard:** <http://localhost:9847> — open any time to watch unerr's operational memory at work in real time.
|
|
187
145
|
|
|
188
|
-
|
|
146
|
+
> Need manual setup or any other MCP client? `unerr install --show-instructions <agent>` prints copy-pasteable steps.
|
|
189
147
|
|
|
190
148
|
---
|
|
191
149
|
|
|
192
|
-
##
|
|
193
|
-
|
|
194
|
-
### First session — instant value
|
|
195
|
-
|
|
196
|
-
- **Graph navigation in <5ms** — `get_entity`, `get_references`, `get_imports`, `search_code`. The agent stops reading 30 files to find one function.
|
|
197
|
-
- **Blast radius before edits** — `get_references` returns every caller. No more confident wrong changes that ripple across services.
|
|
198
|
-
- **Targeted file reads** — `file_read({entity: "fnName"})` returns just that function + relevant conventions/facts, not 2000 lines.
|
|
199
|
-
- **Shell compression** — 11 strategies, 645+ command classifiers. Diffs, errors, logs, test runs, YAML — each compressed differently. **93% average compression** across real-world benchmarks (2 MB → 138 KB). Raw output is kept on disk; the agent can recover it on demand.
|
|
200
|
-
- **Web fetches** — `fetch_url` strips page chrome via Defuddle/Readability, converts to markdown, splits into heading-bounded passages, optionally re-ranks with BM25 when a `prompt` is supplied, and caches by content hash. Replaces built-in WebFetch — **5–10× fewer tokens** per page.
|
|
201
|
-
- **Convention awareness** — naming, structure, import patterns auto-detected and injected into the agent's context.
|
|
202
|
-
- **Tool adoption nudging** — five reinforcement layers (exec nudges, hook interception, instruction injection, skill reminders, default-deny of built-ins on Claude Code) push the agent to use the graph instead of grep.
|
|
203
|
-
|
|
204
|
-
### Session 2+ — it starts compounding
|
|
150
|
+
## Who it's for
|
|
205
151
|
|
|
206
|
-
- **
|
|
207
|
-
- **
|
|
208
|
-
- **
|
|
209
|
-
- **Loop prevention** — a circuit breaker fires after repeated failed attempts on the same entity, surfacing the failure mode instead of letting the agent thrash.
|
|
210
|
-
- **Memory-effectiveness scoring** — every fact and convention opens a 5-turn observation window and resolves to a verdict (reinforced / acted_on / caught / ignored / corrected). The Reasoning Quality pane shows the **load-bearing rate** — not just how much the agent remembered, but how much of it actually mattered.
|
|
152
|
+
- **Vibe coders.** The thing that stops your app from breaking on turn 30 when the AI gets confused.
|
|
153
|
+
- **Solo builders.** The continuous thread. Switch from Claude Code in the terminal to Cursor in the IDE — your project memory comes with you.
|
|
154
|
+
- **Senior / staff engineers.** The dependency graph, prior incidents, and team conventions a human engineer would already carry in their head — fed to AI on every edit.
|
|
211
155
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
While unerr is running these activate automatically — no extra commands:
|
|
215
|
-
|
|
216
|
-
- **Architecture guard** — flags structural violations before they ship.
|
|
217
|
-
- **Cascade guard** — warns when an edit has wide blast radius.
|
|
218
|
-
- **Convention drift** — detects when new code diverges from established patterns.
|
|
219
|
-
- **Auto-doc** — generates docs for undocumented entities.
|
|
220
|
-
- **Change narrative** — tracks the story behind multi-step refactors.
|
|
221
|
-
- **Loop breaker** — intervenes when the agent is stuck retrying.
|
|
222
|
-
- **Session continuity** — preserves state across restarts.
|
|
156
|
+
---
|
|
223
157
|
|
|
224
|
-
|
|
158
|
+
## Why one runtime, not five separate tools
|
|
225
159
|
|
|
226
|
-
|
|
227
|
-
|----------|-------------------|:-:|
|
|
228
|
-
| **diff** | `git diff`, patch output | **99%** |
|
|
229
|
-
| **structured** | JSON APIs, `docker inspect` | **97%** |
|
|
230
|
-
| **progress** | `npm install`, `pip install` | **95%** |
|
|
231
|
-
| **log_text** | Build logs, server logs, `make`, `cargo build` | **89%** |
|
|
232
|
-
| **test_results** | `vitest`, `pytest`, `cargo test`, `playwright` | **80%** |
|
|
233
|
-
| **tabular** | `ps aux`, `docker ps`, `kubectl get` | **77%** |
|
|
234
|
-
| **error_diagnostic** | `tsc`, `eslint`, `rustc`, `shellcheck` | **72%** |
|
|
235
|
-
| **key_value** | `env`, `kubectl describe`, `systemctl status` | **48%** |
|
|
236
|
-
| **tree_paths** | `find`, `tree`, `ls -R` | **42%** |
|
|
237
|
-
| **yaml** | YAML configs, `kubectl get -o yaml`, Helm output | adaptive |
|
|
238
|
-
| **omni** | Fallback for unrecognized output | adaptive |
|
|
160
|
+
**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.
|
|
239
161
|
|
|
240
|
-
|
|
162
|
+
The adjacent space already has strong point tools. unerr's job is not to out-feature any of them in their lane — it's to be the single per-repo runtime that joins them.
|
|
241
163
|
|
|
242
|
-
|
|
164
|
+
| Layer | Where point tools live | What unerr adds |
|
|
165
|
+
|---|---|---|
|
|
166
|
+
| Memory across sessions | claude-mem, Mem0, Zep, Letta | Memory tied to the *current* state of the code — facts get drift signals when the file they're about moves. |
|
|
167
|
+
| Code-graph navigation | Graphify, CodeGraphContext, Serena | The graph is read *before every file read* — surgical context instead of 3,000-line dumps. |
|
|
168
|
+
| Output compression | RTK, Repomix | Compression is fed through the same MCP runtime as the graph and memory, not a separate tool the agent has to remember to invoke. |
|
|
169
|
+
| Convention enforcement | `.cursorrules`, CLAUDE.md hand-maintained | Conventions auto-detected from ≥70% adherence in the code. No file to maintain. |
|
|
243
170
|
|
|
244
|
-
|
|
245
|
-
|----------|:---:|:-:|:-:|:-:|:-:|
|
|
246
|
-
| TypeScript / JavaScript / Python / Go / Java / Kotlin / Scala / Rust / Ruby / C / C++ / C# | 1 | ✓ | ✓ | ✓ | ✓ |
|
|
247
|
-
| PHP / Swift / Lua / Dart / Elixir / Zig | 2 | ✓ | ✓ | ✓ | — |
|
|
171
|
+
We deliberately don't ship a feature-by-feature checkmark matrix against the depth leaders on each lane — that's the trap. Mem0 will out-memory us on memory depth; Graphify will out-graph us on graph aesthetics; RTK will out-compress us on shell compression simplicity. The runtime is the join across all four lanes — not the depth on any one.
|
|
248
172
|
|
|
249
|
-
|
|
250
|
-
**Tier 2** (6 languages): tree-sitter AST + generic extraction. Regex fallback for the rest.
|
|
173
|
+
Three numbers behind the runtime:
|
|
251
174
|
|
|
252
|
-
|
|
175
|
+
- **~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 attention isn't diluted.
|
|
176
|
+
- **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.
|
|
177
|
+
- **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.
|
|
178
|
+
- **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)).
|
|
253
179
|
|
|
254
180
|
---
|
|
255
181
|
|
|
256
|
-
## How
|
|
182
|
+
## How the runtime works
|
|
257
183
|
|
|
258
|
-
|
|
184
|
+
One local process per repo. Four slices, joined deterministically — *the joins are the product, not the slices.* Point tools own one slice each. None of them can ship the joins without becoming a per-repo runtime themselves.
|
|
259
185
|
|
|
260
|
-
|
|
|
261
|
-
|
|
262
|
-
| **
|
|
263
|
-
|
|
|
264
|
-
|
|
|
265
|
-
|
|
|
266
|
-
| **Memory & continuity** | | | | | |
|
|
267
|
-
| Persistent across sessions — typed facts with per-type decay, contradiction handling | ✓ | ✗ | ✗ | ✓ | ✗ |
|
|
268
|
-
| Per-repo isolation — all state in `.unerr/` inside the repo, no cross-project leakage | ✓ | ✓ | ✓ | ✗ | — |
|
|
269
|
-
| **Runtime** | | | | | |
|
|
270
|
-
| Zero LLM in core — no API keys, no per-turn inference cost | ✓ | ✓ | ✓ | ✗ | ✓ |
|
|
271
|
-
| Keeps MCP tools in active rotation — without enforcement, agents revert to built-in Read/Grep/Glob within 3–5 turns | ✓ | ✗ | ✗ | ✗ | ✗ |
|
|
272
|
-
|
|
273
|
-
Three numbers behind the table:
|
|
186
|
+
| Slice | What's inside | What the join enables |
|
|
187
|
+
|---|---|---|
|
|
188
|
+
| **Live code graph** | CozoDB · tree-sitter ASTs · SCIP-verified call graphs · 18+ languages · <5ms queries | Read *before every file read*. The agent opens 50 targeted lines and a caller list — not 3,000 lines and a guess. |
|
|
189
|
+
| **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. |
|
|
190
|
+
| **Context delivery** | Shell output compression (93% overall, 645+ command classifiers) · Web fetches (5–10× via Defuddle + BM25) · Entity-targeted file reads | Compression, graph, and memory share one process — the agent doesn't have to remember which tool to invoke for which kind of content. |
|
|
191
|
+
| **Behaviour modules** | cascade guard · convention drift · loop breaker · session continuity · auto-doc · change narrative · architecture guard | Each guardrail fires on a *join* — cascade-guard reads the graph before the edit, convention-drift compares new code against memory, loop-breaker watches the timeline. None of these are reachable from a single point tool. |
|
|
274
192
|
|
|
275
|
-
-
|
|
276
|
-
- **0** LLM calls per query in the Free tier — facts, conventions, and drift signals are algorithmic.
|
|
277
|
-
- **3–5** turns is how long agents take to revert to built-in Read/Grep/Glob without drift prevention.
|
|
193
|
+
**The unifying point.** Drift detection requires memory anchored to a live graph. Cascade-guard requires the graph and the edit-intent ledger on the same process. Convention-drift requires the auto-detected pattern store and the new-code stream in the same memory space. These aren't "features" you can buy individually — they're *emergent properties of the runtime*, only available when all four slices live in one per-repo process.
|
|
278
194
|
|
|
279
|
-
|
|
195
|
+
Five disconnected MCP servers — one for memory, one for graph, one for compression, one for tracing, one for skills — burn ~55K tokens of schemas just to *announce themselves* (Anthropic's own engineering example). They can't reach across each other to fire any of these guardrails. That's the difference between a stack and a runtime.
|
|
280
196
|
|
|
281
197
|
---
|
|
282
198
|
|
|
283
|
-
|
|
199
|
+
<details>
|
|
200
|
+
<summary><strong>Under the hood — architecture, CLI commands, MCP tools, dev setup</strong></summary>
|
|
201
|
+
|
|
202
|
+
### Architecture
|
|
284
203
|
|
|
285
204
|
```
|
|
286
205
|
AI Agent (Claude Code / Cursor / Windsurf / any MCP client)
|
|
287
206
|
│
|
|
288
207
|
├── stdio MCP ──→ unerr --mcp (bridge, per IDE session)
|
|
289
208
|
│ │
|
|
290
|
-
│ └── UDS ──→ unerrd (lightweight Node process
|
|
291
|
-
│
|
|
209
|
+
│ └── UDS ──→ unerrd (one lightweight Node process
|
|
210
|
+
│ per machine, auto-spawned,
|
|
211
|
+
│ exits after 30 min idle)
|
|
292
212
|
│ │
|
|
293
213
|
│ └── per-repo unerr process(es)
|
|
294
|
-
│ │
|
|
295
214
|
│ ├── CozoDB graph (in-process, <5ms)
|
|
296
215
|
│ ├── Fact store (cross-session memory)
|
|
297
216
|
│ ├── Timeline + ledger (every tool call)
|
|
298
217
|
│ ├── File watcher (incremental reindex)
|
|
299
218
|
│ ├── Convention engine
|
|
300
|
-
│ ├── Compression engine
|
|
301
|
-
│ └── Behavior modules
|
|
219
|
+
│ ├── Compression engine
|
|
220
|
+
│ └── Behavior modules
|
|
302
221
|
│
|
|
303
222
|
└── Dashboard ──→ http://localhost:9847 (SSE-streamed live)
|
|
304
223
|
```
|
|
305
224
|
|
|
306
225
|
One local DB per repo. Zero network calls. No API keys. No cloud. Your code never leaves the machine.
|
|
307
226
|
|
|
308
|
-
---
|
|
309
|
-
|
|
310
|
-
## MCP Tools (20)
|
|
311
|
-
|
|
312
|
-
### Graph Intelligence (8)
|
|
313
|
-
|
|
314
|
-
| Tool | What the agent gets |
|
|
315
|
-
|------|-----|
|
|
316
|
-
| `get_entity` | Any code entity — signature, body, callers, callees, risk |
|
|
317
|
-
| `get_file` | All entities in a file with risk summary |
|
|
318
|
-
| `get_references` | Callers (blast radius) or callees (dependencies) |
|
|
319
|
-
| `get_imports` | Import graph for a file |
|
|
320
|
-
| `search_code` | Graph-ranked full-text search across all entities |
|
|
321
|
-
| `get_conventions` | Detected naming/structure/import patterns + adherence rates |
|
|
322
|
-
| `get_critical_nodes` | High fan-in/fan-out chokepoints |
|
|
323
|
-
| `get_cross_boundary_links` | Unexpected cross-module dependencies, scored by surprise |
|
|
324
|
-
|
|
325
|
-
### Structural Analysis (3)
|
|
326
|
-
|
|
327
|
-
| Tool | What the agent gets |
|
|
328
|
-
|------|-----|
|
|
329
|
-
| `get_project_stats` | Entity counts, risk distribution, health grade |
|
|
330
|
-
| `file_connections` | Imports + co-change correlations for a file |
|
|
331
|
-
| `get_test_coverage` | Direct + transitive tests for any entity |
|
|
332
|
-
|
|
333
|
-
### File Protocol (2)
|
|
334
|
-
|
|
335
|
-
| Tool | What the agent gets |
|
|
336
|
-
|------|-----|
|
|
337
|
-
| `file_read` | Context-aware read — auto-injects conventions and facts |
|
|
338
|
-
| `file_outline` | File structure (entities, exports) without reading the body |
|
|
339
|
-
|
|
340
|
-
### Persistent Memory (2)
|
|
341
|
-
|
|
342
|
-
| Tool | What the agent gets |
|
|
343
|
-
|------|-----|
|
|
344
|
-
| `record_fact` | Persist a convention, decision, or anti-pattern |
|
|
345
|
-
| `recall_facts` | Retrieve facts with hierarchical scope + decay-adjusted confidence |
|
|
346
|
-
|
|
347
|
-
### Session Narrative — Markers (4)
|
|
348
|
-
|
|
349
|
-
Inline markers the agent emits as it works. Persisted to the shadow ledger and `.unerr/timeline.db` — powers turn titles, cross-session intent stitching, the resume strip, and loop/blocker miners.
|
|
350
|
-
|
|
351
|
-
| Tool | What it does |
|
|
352
|
-
|------|-----|
|
|
353
|
-
| `mark_intent` | One-sentence task start (≤80 chars). Becomes the turn title |
|
|
354
|
-
| `mark_decision` | Records a chosen approach + up to 5 alternatives (≤140 chars) |
|
|
355
|
-
| `mark_blocker` | Flags an unresolved obstacle. Carries into the next session's resume strip |
|
|
356
|
-
| `mark_resolution` | Resolves a prior blocker by `marker_id` |
|
|
357
|
-
|
|
358
|
-
### Web Fetch (1)
|
|
359
|
-
|
|
360
|
-
| Tool | What the agent gets |
|
|
361
|
-
|------|-----|
|
|
362
|
-
| `fetch_url` | DOM-extracted markdown of a web page (Defuddle/Readability), split into heading-bounded passages, optionally re-ranked by BM25 against a `prompt`, cached by content hash. Replaces built-in WebFetch — 5–10× fewer tokens. Optional Playwright SPA fallback. |
|
|
363
|
-
|
|
364
|
-
Every response includes `_meta` (latency, risk level, drift status) and inline `ur|<tag>` signals for high-priority guidance (drift, blast-radius warnings, circuit-breaker halts).
|
|
365
|
-
|
|
366
|
-
---
|
|
367
|
-
|
|
368
|
-
<details>
|
|
369
|
-
<summary><strong>CLI commands</strong></summary>
|
|
370
|
-
|
|
371
|
-
```bash
|
|
372
|
-
unerr install <agent> # MCP config + skills + hooks + instructions for one agent
|
|
373
|
-
unerr uninstall # Remove unerr integration from this repo
|
|
374
|
-
unerr doctor # Check PATH + environment, auto-fix if unerr isn't on all shells
|
|
375
|
-
unerr status # Proxy health, entity count, graph age
|
|
376
|
-
unerr stats # Session statistics (tokens, tool calls, compression)
|
|
377
|
-
|
|
378
|
-
unerr --mcp # Stdio bridge — what your IDE invokes via .mcp.json
|
|
379
|
-
unerr # Start a standalone per-repo proxy (rare — IDE invocation covers this)
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
`unerr pm …` manages the cross-repo `unerrd` process — see the [reference](#process-manager-command-reference) below.
|
|
383
|
-
|
|
384
|
-
</details>
|
|
385
|
-
|
|
386
|
-
<details>
|
|
387
|
-
<summary><strong>Architecture</strong></summary>
|
|
388
|
-
|
|
389
227
|
```
|
|
390
228
|
src/
|
|
391
229
|
entrypoints/ CLI entry + boot state machine
|
|
@@ -399,79 +237,64 @@ src/
|
|
|
399
237
|
hooks/ Claude Code hook system integration
|
|
400
238
|
skills/ 12 bundled skill definitions
|
|
401
239
|
server/ + ui/ HTTP API + React (Vite) dashboard
|
|
402
|
-
config/ Agent registry, MCP config writer, instruction injector
|
|
403
|
-
schemas/ Zod schemas
|
|
404
240
|
```
|
|
405
241
|
|
|
406
|
-
**Design principles**
|
|
407
|
-
|
|
408
|
-
- Zero network calls — fully local, no API keys.
|
|
409
|
-
- stdout is sacred — MCP JSON-RPC only; everything else to stderr.
|
|
410
|
-
- <5 ms query responses — CozoDB runs in-process (Rust via NAPI).
|
|
411
|
-
- First useful output <5 s — shallow index first, deep enrichment in background.
|
|
412
|
-
- Graceful degradation — the agent still works if unerr is down, you just lose the intelligence layer.
|
|
242
|
+
**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 operational memory).
|
|
413
243
|
|
|
414
244
|
**Tech stack** TypeScript (ESM) · CozoDB (Rust/NAPI) · web-tree-sitter (WASM) · MCP SDK · Ink (React CLI) · React + Vite (dashboard) · tsup · Vitest
|
|
415
245
|
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
<details>
|
|
419
|
-
<summary><strong>Development</strong></summary>
|
|
246
|
+
### CLI commands
|
|
420
247
|
|
|
421
248
|
```bash
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
249
|
+
unerr install <agent> # MCP config + skills + hooks + instructions for one agent
|
|
250
|
+
unerr uninstall # Remove unerr integration from this repo
|
|
251
|
+
unerr doctor # Check PATH + environment, auto-fix if unerr isn't on all shells
|
|
252
|
+
unerr status # Proxy health, entity count, graph age
|
|
253
|
+
unerr stats # Session statistics (tokens, tool calls, compression)
|
|
254
|
+
unerr --mcp # Stdio bridge — what your IDE invokes via .mcp.json
|
|
255
|
+
|
|
256
|
+
unerr pm status # Process manager: PID, uptime, repos, memory, idle countdown
|
|
257
|
+
unerr pm logs # Tail ~/.unerr/logs/unerrd.log
|
|
258
|
+
unerr pm dashboard # Open http://localhost:9847
|
|
430
259
|
```
|
|
431
260
|
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
<details>
|
|
435
|
-
<summary><strong>Contributing</strong></summary>
|
|
436
|
-
|
|
437
|
-
Contributions welcome — please open an issue first.
|
|
438
|
-
|
|
439
|
-
**Before submitting a PR:**
|
|
440
|
-
- `pnpm run typecheck && pnpm run lint && pnpm run test:run`
|
|
441
|
-
- All output to stderr — never stdout (MCP JSON-RPC channel)
|
|
442
|
-
- All CozoDB interactions are async — always `await`
|
|
443
|
-
- Use `.js` extensions in imports (NodeNext resolution)
|
|
261
|
+
`unerrd` is a lightweight Node process that supervises every registered repo. Your IDE invocation auto-spawns it; it exits cleanly after 30 minutes of no MCP activity. `unerr pm --help` lists the rest.
|
|
444
262
|
|
|
445
|
-
|
|
263
|
+
### MCP tools (20)
|
|
446
264
|
|
|
447
|
-
|
|
265
|
+
Grouped by what the agent gets, not by file:
|
|
448
266
|
|
|
449
|
-
|
|
267
|
+
- **Graph intelligence (8)** — `get_entity`, `get_file`, `get_references`, `get_imports`, `search_code`, `get_conventions`, `get_critical_nodes`, `get_cross_boundary_links`.
|
|
268
|
+
- **Structural analysis (3)** — `get_project_stats`, `file_connections`, `get_test_coverage`.
|
|
269
|
+
- **File protocol (2)** — `file_read` (context-aware, auto-injects conventions and facts), `file_outline` (structure without body).
|
|
270
|
+
- **Persistent memory (3)** — `unerr_remember` (user-stated facts with verbatim quote + confidence), `record_fact` (agent-detected conventions / decisions / anti-patterns), `recall_facts` (hierarchical scope + decay-adjusted confidence).
|
|
271
|
+
- **Session markers (4)** — `mark_intent`, `mark_decision`, `mark_blocker`, `mark_resolution`. Inline as the agent works; powers turn titles and the cross-session resume strip.
|
|
272
|
+
- **Web fetch (1)** — `fetch_url` (DOM-extracted markdown, BM25 re-ranking, content-hash cache). Replaces built-in WebFetch.
|
|
450
273
|
|
|
451
|
-
|
|
274
|
+
Every response carries inline `ur|<tag>` signals for high-priority guidance — drift, blast-radius warnings, circuit-breaker halts — so the agent acts on what it just learned without burning a turn.
|
|
452
275
|
|
|
453
|
-
|
|
276
|
+
### Manual MCP config (any MCP-compatible client)
|
|
454
277
|
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
unerr
|
|
278
|
+
```json
|
|
279
|
+
{
|
|
280
|
+
"mcpServers": {
|
|
281
|
+
"unerr": {
|
|
282
|
+
"command": "npx",
|
|
283
|
+
"args": ["@unerr-ai/unerr", "--mcp"]
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
```
|
|
459
288
|
|
|
460
|
-
|
|
461
|
-
unerr pm remove <path> # Unregister a repo
|
|
462
|
-
unerr pm config <path> <key>=<value> # Per-repo settings (idleTimeout, javaBuildTool, …)
|
|
289
|
+
### Benchmarks
|
|
463
290
|
|
|
464
|
-
unerr
|
|
465
|
-
unerr pm logs --repo <path> # Tail a specific repo's log
|
|
466
|
-
unerr pm logs --bridge --follow # Stream bridge session logs continuously
|
|
467
|
-
unerr pm logs --boot # Most recent spawn sequence only
|
|
291
|
+
unerr removes **86–90% of the tokens** an agent would otherwise spend navigating and reading code — measured, not estimated, with head-to-head runs against other code-intelligence tools on the same questions, same tokenizer, and a fidelity gate that discards any "saving" that lost the answer. Methodology, reproduction commands, and per-repo results: [benchmarks/README.md](./benchmarks/README.md).
|
|
468
292
|
|
|
469
|
-
|
|
470
|
-
```
|
|
293
|
+
### Contributing
|
|
471
294
|
|
|
472
|
-
|
|
295
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, day-to-day commands, code conventions, and pre-PR checklist.
|
|
473
296
|
|
|
474
|
-
|
|
297
|
+
</details>
|
|
475
298
|
|
|
476
299
|
---
|
|
477
300
|
|