thumbgate 1.4.5 → 1.5.0

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.
Files changed (18) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/.well-known/mcp/server-card.json +1 -1
  4. package/README.md +14 -3
  5. package/adapters/README.md +1 -1
  6. package/adapters/claude/.mcp.json +2 -2
  7. package/adapters/codex/config.toml +2 -2
  8. package/adapters/mcp/server-stdio.js +1 -1
  9. package/adapters/opencode/opencode.json +1 -1
  10. package/package.json +6 -2
  11. package/public/compare.html +310 -0
  12. package/public/guide.html +317 -0
  13. package/public/index.html +1331 -0
  14. package/public/lessons.html +989 -0
  15. package/scripts/billing.js +8 -2
  16. package/scripts/commercial-offer.js +1 -1
  17. package/scripts/telemetry-analytics.js +41 -1
  18. package/src/api/server.js +282 -0
package/public/guide.html ADDED
@@ -0,0 +1,317 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>How to Stop AI Coding Agents From Repeating Mistakes — ThumbGate Guide</title>
7
+ <!-- Privacy-friendly analytics by Plausible -->
8
+ <script defer data-domain="thumbgate-production.up.railway.app" src="https://plausible.io/js/script.js"></script>
9
+ <meta name="description" content="The complete guide to preventing AI coding agent mistakes with pre-action gates, history-aware lesson distillation, and automatic prevention rules.">
10
+ <meta name="keywords" content="AI agent mistakes, Claude Code force push, AI coding agent memory, MCP server guardrails, pre-action gates, vibe coding safety, PreToolUse hooks, ThumbGate, SpecLock alternative, Mem0 alternative">
11
+ <meta property="og:title" content="How to Stop AI Coding Agents From Repeating Mistakes">
12
+ <meta property="og:description" content="Pre-action gates that physically block AI agents from repeating known mistakes. The complete guide.">
13
+ <meta property="og:type" content="article">
14
+ <meta property="og:url" content="https://thumbgate-production.up.railway.app/guide">
15
+ <link rel="canonical" href="https://thumbgate-production.up.railway.app/guide">
16
+
17
+ <script type="application/ld+json">
18
+ {
19
+ "@context": "https://schema.org",
20
+ "@type": "TechArticle",
21
+ "headline": "How to Stop AI Coding Agents From Repeating Mistakes",
22
+ "description": "Complete guide to preventing AI agent mistakes with pre-action gates, feedback capture, history-aware lesson distillation, and automatic prevention rule generation.",
23
+ "author": {
24
+ "@type": "Person",
25
+ "name": "Igor Ganapolsky",
26
+ "url": "https://github.com/IgorGanapolsky"
27
+ },
28
+ "publisher": {
29
+ "@type": "Organization",
30
+ "name": "ThumbGate",
31
+ "url": "https://thumbgate-production.up.railway.app"
32
+ },
33
+ "datePublished": "2026-03-27",
34
+ "dateModified": "2026-03-27",
35
+ "mainEntityOfPage": "https://thumbgate-production.up.railway.app/guide",
36
+ "about": [
37
+ {"@type": "Thing", "name": "AI coding agents"},
38
+ {"@type": "Thing", "name": "Model Context Protocol"},
39
+ {"@type": "Thing", "name": "pre-action gates"}
40
+ ]
41
+ }
42
+ </script>
43
+
44
+ <script type="application/ld+json">
45
+ {
46
+ "@context": "https://schema.org",
47
+ "@type": "HowTo",
48
+ "name": "How to install ThumbGate and prevent AI agent mistakes",
49
+ "description": "Install ThumbGate in one command to stop your AI coding agent from repeating known mistakes.",
50
+ "step": [
51
+ {
52
+ "@type": "HowToStep",
53
+ "position": 1,
54
+ "name": "Install ThumbGate",
55
+ "text": "Run npx thumbgate init to auto-detect your agent and configure hooks."
56
+ },
57
+ {
58
+ "@type": "HowToStep",
59
+ "position": 2,
60
+ "name": "Give feedback when your agent makes a mistake",
61
+ "text": "Say thumbs down with context about what went wrong. In the current Claude auto-capture path, vague negative signals can reuse up to 8 prior recorded entries and stay linked to a 60-second feedback session."
62
+ },
63
+ {
64
+ "@type": "HowToStep",
65
+ "position": 3,
66
+ "name": "Feedback auto-promotes to prevention rules",
67
+ "text": "After repeated failures, ThumbGate generates a prevention rule and wires it as a pre-action gate."
68
+ },
69
+ {
70
+ "@type": "HowToStep",
71
+ "position": 4,
72
+ "name": "Gates block mistakes before they happen",
73
+ "text": "PreToolUse hooks intercept tool calls and check them against known failure patterns. Bad actions are blocked before execution."
74
+ }
75
+ ]
76
+ }
77
+ </script>
78
+
79
+ <script type="application/ld+json">
80
+ {
81
+ "@context": "https://schema.org",
82
+ "@type": "FAQPage",
83
+ "mainEntity": [
84
+ {
85
+ "@type": "Question",
86
+ "name": "How do I stop my AI coding agent from repeating mistakes?",
87
+ "acceptedAnswer": {
88
+ "@type": "Answer",
89
+ "text": "Install ThumbGate (npx thumbgate init). When your agent makes a mistake, give it a thumbs-down with context. ThumbGate captures the feedback, and after repeated failures, auto-generates a prevention rule. Pre-action gates then block the same mistake before it executes in future sessions."
90
+ }
91
+ },
92
+ {
93
+ "@type": "Question",
94
+ "name": "Why does my Claude Code agent keep force-pushing to main?",
95
+ "acceptedAnswer": {
96
+ "@type": "Answer",
97
+ "text": "Because prompt rules are suggestions the agent can ignore. ThumbGate solves this with enforcement: a PreToolUse hook fires before every tool call and checks it against known failure patterns. If the action matches a gate (like git push --force to main), it is physically blocked before execution."
98
+ }
99
+ },
100
+ {
101
+ "@type": "Question",
102
+ "name": "What is the difference between pre-action gates and prompt rules?",
103
+ "acceptedAnswer": {
104
+ "@type": "Answer",
105
+ "text": "Prompt rules (like CLAUDE.md or .cursorrules) are instructions the agent may ignore. Pre-action gates are enforcement: they intercept the tool call at the PreToolUse hook level and block it before execution. Gates are auto-generated from feedback and use Thompson Sampling to adapt their sensitivity."
106
+ }
107
+ },
108
+ {
109
+ "@type": "Question",
110
+ "name": "How does ThumbGate compare to SpecLock?",
111
+ "acceptedAnswer": {
112
+ "@type": "Answer",
113
+ "text": "SpecLock requires manually writing constraints or compiling them from a PRD. ThumbGate learns automatically from thumbs-up/down feedback and auto-generates prevention rules from repeated failures. SpecLock locks files from modification; ThumbGate blocks specific actions before they execute."
114
+ }
115
+ },
116
+ {
117
+ "@type": "Question",
118
+ "name": "How does ThumbGate compare to Mem0?",
119
+ "acceptedAnswer": {
120
+ "@type": "Answer",
121
+ "text": "Mem0 is cloud-hosted memory for AI apps. ThumbGate is local-first enforcement. Mem0 remembers context but cannot block actions. ThumbGate captures feedback, promotes it to prevention rules, and physically blocks tool calls that match known failure patterns."
122
+ }
123
+ },
124
+ {
125
+ "@type": "Question",
126
+ "name": "Does AI agent memory persist across sessions?",
127
+ "acceptedAnswer": {
128
+ "@type": "Answer",
129
+ "text": "With ThumbGate, yes. Feedback is stored in a local SQLite database with FTS5 indexing. Prevention rules and gates persist across sessions. The recall tool injects relevant context at session start, and session handoff preserves continuity."
130
+ }
131
+ },
132
+ {
133
+ "@type": "Question",
134
+ "name": "How do I set up PreToolUse hooks in Claude Code?",
135
+ "acceptedAnswer": {
136
+ "@type": "Answer",
137
+ "text": "Run npx thumbgate init --agent claude-code. This auto-configures PreToolUse hooks in your .claude/settings.json. The hooks fire before every tool call and check it against your prevention rules and gates."
138
+ }
139
+ },
140
+ {
141
+ "@type": "Question",
142
+ "name": "What AI coding agents does ThumbGate work with?",
143
+ "acceptedAnswer": {
144
+ "@type": "Answer",
145
+ "text": "ThumbGate works with Claude Code, Cursor, Codex, Gemini CLI, Amp, OpenCode, and any MCP-compatible agent. Install with npx thumbgate init to auto-detect your agent."
146
+ }
147
+ }
148
+ ]
149
+ }
150
+ </script>
151
+
152
+ <style>
153
+ *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
154
+ :root {
155
+ --bg: #0a0a0b;
156
+ --bg-card: #161618;
157
+ --border: #222225;
158
+ --text: #e8e8ec;
159
+ --muted: #8b8b94;
160
+ --cyan: #22d3ee;
161
+ --green: #34d399;
162
+ --red: #f87171;
163
+ }
164
+ body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--text); line-height: 1.7; }
165
+ .container { max-width: 780px; margin: 0 auto; padding: 2rem 1.5rem 4rem; }
166
+ nav { padding: 1rem 2rem; border-bottom: 1px solid var(--border); display: flex; gap: 1.5rem; align-items: center; }
167
+ nav a { color: var(--muted); text-decoration: none; font-size: 0.9rem; }
168
+ nav a:hover { color: var(--cyan); }
169
+ nav .brand { color: var(--text); font-weight: 700; font-size: 1.1rem; }
170
+ h1 { font-size: 2.2rem; line-height: 1.2; margin: 2rem 0 1rem; }
171
+ h2 { font-size: 1.5rem; margin: 2.5rem 0 1rem; color: var(--cyan); }
172
+ h3 { font-size: 1.15rem; margin: 1.5rem 0 0.5rem; }
173
+ p, li { color: var(--text); margin-bottom: 0.75rem; }
174
+ ul { padding-left: 1.5rem; }
175
+ li { margin-bottom: 0.5rem; }
176
+ code { background: #1a1a1e; padding: 0.15em 0.4em; border-radius: 4px; font-size: 0.9em; color: var(--cyan); }
177
+ pre { background: #111113; border: 1px solid var(--border); border-radius: 8px; padding: 1rem; overflow-x: auto; margin: 1rem 0; }
178
+ pre code { background: none; padding: 0; color: var(--text); }
179
+ .highlight { color: var(--cyan); }
180
+ .card { background: var(--bg-card); border: 1px solid var(--border); border-radius: 12px; padding: 1.5rem; margin: 1.5rem 0; }
181
+ .comparison-table { width: 100%; border-collapse: collapse; margin: 1.5rem 0; font-size: 0.9rem; }
182
+ .comparison-table th, .comparison-table td { padding: 0.75rem; border: 1px solid var(--border); text-align: left; }
183
+ .comparison-table th { background: #111113; color: var(--cyan); }
184
+ .comparison-table td:first-child { font-weight: 600; }
185
+ .cta { display: inline-block; background: var(--cyan); color: #000; padding: 0.75rem 1.5rem; border-radius: 8px; text-decoration: none; font-weight: 600; margin: 1rem 0; }
186
+ .cta:hover { opacity: 0.9; }
187
+ .breadcrumb { color: var(--muted); font-size: 0.85rem; margin-bottom: 0.5rem; }
188
+ .breadcrumb a { color: var(--muted); }
189
+ @media (max-width: 600px) { h1 { font-size: 1.6rem; } .container { padding: 1rem; } }
190
+ </style>
191
+ </head>
192
+ <body>
193
+ <nav>
194
+ <a href="/" class="brand">ThumbGate</a>
195
+ <a href="/guide">Guide</a>
196
+ <a href="/dashboard">Dashboard</a>
197
+ <a href="https://github.com/IgorGanapolsky/ThumbGate">GitHub</a>
198
+ </nav>
199
+
200
+ <div class="container">
201
+ <p class="breadcrumb"><a href="/">Home</a> / Guide</p>
202
+
203
+ <h1>How to Stop AI Coding Agents From Repeating Mistakes</h1>
204
+ <p style="color:var(--muted);">The complete guide to pre-action gates, feedback capture, history-aware lesson distillation, and automatic prevention rules.</p>
205
+
206
+ <h2>The Problem</h2>
207
+ <p>Your AI coding agent force-pushes to main. You correct it. Next session, it force-pushes again. You add a rule to CLAUDE.md. It ignores it. You lose an afternoon reverting.</p>
208
+ <p>This happens because <strong>prompt rules are suggestions</strong>. The agent can read them, forget them, or override them. There is no enforcement at the tool-call level.</p>
209
+
210
+ <h2>The Fix: Pre-Action Gates</h2>
211
+ <p>ThumbGate adds an enforcement layer between your agent and its tools. When the agent tries to execute a tool call, a <code>PreToolUse</code> hook fires <em>before</em> the action runs. The hook checks the call against known failure patterns. If it matches a gate, the action is blocked.</p>
212
+
213
+ <div class="card">
214
+ <h3>Before ThumbGate</h3>
215
+ <pre><code>Agent: git push --force origin main
216
+ Result: Force-pushed. You lose 3 commits. Again.</code></pre>
217
+ <h3>After ThumbGate</h3>
218
+ <pre><code>Agent: git push --force origin main
219
+ [gate] Blocked: no-force-push (confidence: 0.94)
220
+ Agent: git push origin feature-branch
221
+ [gate] Passed</code></pre>
222
+ </div>
223
+
224
+ <h2>Install (One Command)</h2>
225
+ <pre><code># Auto-detect your agent and configure hooks
226
+ npx thumbgate init
227
+
228
+ # Or specify your agent directly
229
+ npx thumbgate init --agent claude-code
230
+ npx thumbgate init --agent codex
231
+ npx thumbgate init --agent cursor
232
+ npx thumbgate init --agent gemini</code></pre>
233
+
234
+ <h2>How It Works</h2>
235
+
236
+ <h3>1. You give feedback</h3>
237
+ <p>When your agent makes a mistake, tell it. ThumbGate captures the feedback as structured data with context, tags, and domain. In the current Claude auto-capture path, if the thumbs-down is vague, it can reuse up to 8 prior recorded entries and the failed tool call to propose a better lesson instead of discarding the feedback.</p>
238
+ <pre><code># Your agent force-pushed. You say:
239
+ "thumbs down — force-pushed to main, lost commits"
240
+
241
+ # ThumbGate captures:
242
+ {
243
+ signal: "negative",
244
+ context: "force-pushed to main, lost commits",
245
+ tags: ["git", "force-push", "destructive"],
246
+ domain: "version-control"
247
+ }</code></pre>
248
+
249
+ <h3>2. Feedback auto-promotes to prevention rules</h3>
250
+ <p>After repeated failures with the same pattern, ThumbGate generates a prevention rule automatically. No manual rule writing needed.</p>
251
+
252
+ <h3>3. Rules become gates</h3>
253
+ <p>Prevention rules are enforced as pre-action gates. The gate fires at the <code>PreToolUse</code> hook level — inside the agent's runtime, before the tool call executes.</p>
254
+
255
+ <h3>4. Gates adapt via Thompson Sampling</h3>
256
+ <p>Gates that block too aggressively (high false-positive rate) get their confidence reduced automatically. Gates that catch real mistakes get reinforced. This is Bayesian multi-armed bandit optimization, not static rules.</p>
257
+
258
+ <h2>Memory That Persists Across Sessions</h2>
259
+ <p>ThumbGate stores feedback in a local SQLite database with FTS5 full-text indexing. Lookups are sub-millisecond even at tens of thousands of entries. Old entries that contradict newer evidence are auto-pruned via Bayesian belief decay.</p>
260
+ <ul>
261
+ <li><code>recall</code> — injects relevant context at session start</li>
262
+ <li><code>search_lessons</code> — finds promoted lessons with corrective actions</li>
263
+ <li><code>retrieve_lessons</code> — surfaces lessons for the tool or action you are about to run</li>
264
+ <li><code>session_handoff</code> — preserves continuity across sessions</li>
265
+ </ul>
266
+
267
+ <h2>History-Aware Feedback Sessions</h2>
268
+ <p>ThumbGate supports linked feedback sessions for the messy reality of AI debugging. In the current Claude flow, accepted feedback opens a 60-second follow-up session. You can append more context, reset the timer, and finalize once the lesson is clear.</p>
269
+ <ul>
270
+ <li><code>open_feedback_session</code> starts a linked correction thread.</li>
271
+ <li><code>append_feedback_context</code> adds later notes, failed tool output, or user corrections to the same thread.</li>
272
+ <li><code>finalize_feedback_session</code> promotes the combined evidence into one reusable lesson.</li>
273
+ <li><code>reflect_on_feedback</code> proposes a reusable rule from the same transcript when the failure pattern is obvious.</li>
274
+ </ul>
275
+
276
+ <h2>Pre-Action Gates vs Prompt Rules</h2>
277
+ <table class="comparison-table">
278
+ <tr><th>Feature</th><th>Prompt Rules</th><th>Pre-Action Gates</th></tr>
279
+ <tr><td>Where they live</td><td>CLAUDE.md, .cursorrules</td><td>PreToolUse hooks</td></tr>
280
+ <tr><td>Enforcement</td><td>Suggestion (can be ignored)</td><td>Blocks execution</td></tr>
281
+ <tr><td>When they fire</td><td>At prompt load</td><td>Before every tool call</td></tr>
282
+ <tr><td>Auto-generated</td><td>No — hand-written</td><td>Yes — from feedback</td></tr>
283
+ <tr><td>Adaptive</td><td>No</td><td>Yes — Thompson Sampling</td></tr>
284
+ <tr><td>Persist across sessions</td><td>Only if in a file</td><td>SQLite + JSONL</td></tr>
285
+ </table>
286
+
287
+ <h2>ThumbGate vs Alternatives</h2>
288
+ <table class="comparison-table">
289
+ <tr><th>Feature</th><th>ThumbGate</th><th>SpecLock</th><th>Mem0</th></tr>
290
+ <tr><td>Blocks mistakes before execution</td><td>Yes — PreToolUse gates</td><td>Yes — Patch Firewall</td><td>No</td></tr>
291
+ <tr><td>Learns from feedback</td><td>Yes — thumbs up/down</td><td>No — manual specs</td><td>Yes — auto-capture</td></tr>
292
+ <tr><td>Auto-generates rules</td><td>Yes — from repeated failures</td><td>No</td><td>No</td></tr>
293
+ <tr><td>Agent support</td><td>Claude Code, Codex, Gemini, Amp, Cursor, OpenCode</td><td>Claude Code, Cursor, Windsurf, Cline</td><td>Claude, Cursor</td></tr>
294
+ <tr><td>Install</td><td><code>npx thumbgate init</code></td><td><code>npx speclock setup</code></td><td>Cloud signup</td></tr>
295
+ <tr><td>Cost</td><td>Free (Pro $19/mo or $149/yr, Team rollout $99/seat/mo)</td><td>Free</td><td>Free tier + paid</td></tr>
296
+ </table>
297
+
298
+ <h2>Common Scenarios</h2>
299
+
300
+ <h3>Agent keeps deleting files</h3>
301
+ <p>Give a thumbs-down: "deleted production config file." After 2-3 occurrences, ThumbGate generates a gate that blocks <code>rm</code> commands targeting config files.</p>
302
+
303
+ <h3>Agent ignores test failures</h3>
304
+ <p>Give a thumbs-down: "committed code with failing tests." ThumbGate learns the pattern and gates future commits when test results show failures.</p>
305
+
306
+ <h3>Agent uses wrong API endpoint</h3>
307
+ <p>Give a thumbs-down: "called staging API in production code." The gate blocks tool calls that reference staging URLs in production contexts.</p>
308
+
309
+ <h2>Get Started</h2>
310
+ <pre><code>npx thumbgate init</code></pre>
311
+ <p>One command. Works with Claude Code, Cursor, Codex, Gemini, Amp, and OpenCode. Claude Code can also call Codex for review, adversarial review, and second-pass handoffs through the repo-local bridge plugin.</p>
312
+ <a href="https://thumbgate-production.up.railway.app/checkout/pro?utm_source=guide&utm_medium=cta_button&utm_campaign=pro_pack" class="cta">Get Pro — $19/mo or $149/yr</a>
313
+ <p style="color:var(--muted); font-size:0.85rem;">Free keeps local enforcement with 3 daily feedback captures, 5 lesson searches, unlimited recall, blocking, and history-aware lesson distillation. Pro is $19/mo or $149/yr for a personal local dashboard and DPO export. Team rollout starts intake-first at $99/seat/mo with a 3-seat minimum for the hosted shared lesson DB, org dashboard, and generated review views.</p>
314
+
315
+ </div>
316
+ </body>
317
+ </html>