thumbgate 1.4.6 → 1.5.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/.claude-plugin/marketplace.json +2 -2
- package/.claude-plugin/plugin.json +1 -1
- package/.well-known/mcp/server-card.json +1 -1
- package/README.md +241 -228
- package/adapters/README.md +1 -1
- package/adapters/claude/.mcp.json +2 -2
- package/adapters/codex/config.toml +4 -2
- package/adapters/mcp/server-stdio.js +34 -3
- package/adapters/opencode/opencode.json +1 -1
- package/bin/cli.js +21 -8
- package/bin/postinstall.js +25 -17
- package/config/evals/agent-safety-eval.json +131 -0
- package/config/github-about.json +5 -2
- package/config/specs/agent-safety.json +79 -0
- package/package.json +44 -8
- package/public/compare.html +3 -3
- package/public/guide.html +2 -2
- package/public/index.html +255 -94
- package/public/lessons.html +2 -2
- package/scripts/auto-wire-hooks.js +77 -27
- package/scripts/billing.js +8 -2
- package/scripts/bot-detection.js +165 -0
- package/scripts/cli-feedback.js +6 -2
- package/scripts/commercial-offer.js +5 -5
- package/scripts/dashboard.js +152 -2
- package/scripts/decision-trace.js +354 -0
- package/scripts/feedback-loop.js +4 -8
- package/scripts/rate-limiter.js +77 -24
- package/scripts/sales-pipeline.js +681 -0
- package/scripts/session-episode-store.js +329 -0
- package/scripts/session-health-sensor.js +242 -0
- package/scripts/spec-gate.js +362 -0
- package/scripts/statusline.sh +6 -9
- package/skills/thumbgate/SKILL.md +1 -1
- package/src/api/server.js +368 -12
package/README.md
CHANGED
|
@@ -1,82 +1,154 @@
|
|
|
1
1
|
# ThumbGate
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Your AI coding bill has a leak.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Stop paying $ for the same AI mistake.**
|
|
6
|
+
|
|
7
|
+
Every retry loop, every hallucinated import, every *"let me try a different approach"* — those are billable tokens on every LLM vendor's bill. Thumbs-down once; ThumbGate blocks that exact mistake on every future call. Across Claude Code, Cursor, Codex, Gemini, Amp, OpenCode — any MCP-compatible agent, forever.
|
|
8
|
+
|
|
9
|
+
Under the hood: your thumbs-down becomes a **Pre-Action Gate** that physically blocks the pattern **permanently** on every future call — across every session, every model, every agent. It is **self-improving agent governance**: every correction promotes a fresh prevention rule, and your library of Pre-Action Gates grows stronger with every lesson. Works with Claude Code, Cursor, Codex, Gemini CLI, Amp, OpenCode, and any MCP-compatible agent. The monthly Anthropic / OpenAI bill stops paying for the same lesson over and over — local-first enforcement, zero tokens spent on repeats.
|
|
10
|
+
|
|
11
|
+
> **Prevent expensive AI mistakes. Make AI stop repeating mistakes. Turn a smart assistant into a reliable operator.**
|
|
12
|
+
|
|
13
|
+
> **Mission:** make AI coding affordable by making sure you never pay for the same mistake twice.
|
|
6
14
|
|
|
7
15
|
[](https://github.com/IgorGanapolsky/ThumbGate/actions/workflows/ci.yml)
|
|
8
16
|
[](https://www.npmjs.com/package/thumbgate)
|
|
9
17
|
[](LICENSE)
|
|
10
|
-
[](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=badge_cta#workflow-sprint-intake)
|
|
11
|
-
[](https://thumbgate-production.up.railway.app/go/gpt?utm_source=github&utm_medium=readme&utm_campaign=badge_cta&cta_id=readme_badge_open_gpt&cta_placement=readme_badge)
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
---
|
|
14
20
|
|
|
15
|
-
|
|
21
|
+
## 🎬 90-second demo
|
|
22
|
+
|
|
23
|
+
Watch the force-push scenario: agent tries to `git push --force`, one thumbs-down, next session it's blocked — zero tokens spent on the repeat.
|
|
24
|
+
|
|
25
|
+
[**▶ Watch the 90-second demo**](https://thumbgate-production.up.railway.app/#demo?utm_source=github&utm_medium=readme&utm_campaign=demo_video) · [Script](docs/marketing/demo-video-script.md) · [ElevenLabs narration: `npm run demo:voiceover`](scripts/generate-demo-voiceover.js)
|
|
26
|
+
|
|
27
|
+
<!-- Video embed lives on the landing page and YouTube. Script + voiceover automation ship with the repo so anyone can re-record. -->
|
|
16
28
|
|
|
17
|
-
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## First-dollar activation path
|
|
32
|
+
|
|
33
|
+
If someone is not already bought into ThumbGate, do not lead with architecture. Lead with one repeated mistake.
|
|
18
34
|
|
|
19
|
-
|
|
35
|
+
1. **Show the pain:** open the **[ThumbGate GPT](https://thumbgate-production.up.railway.app/go/gpt?utm_source=github&utm_medium=readme&utm_campaign=first_dollar_activation&cta_id=readme_first_dollar_open_gpt&cta_placement=readme_first_dollar)** and paste the bad answer, risky command, deploy, PR action, or agent plan before it runs again.
|
|
36
|
+
2. **Capture the lesson:** type `thumbs down:` or `thumbs up:` with one concrete sentence. Native ChatGPT rating buttons are not the ThumbGate capture path; typed feedback is.
|
|
37
|
+
3. **Enforce the repeat:** run `npx thumbgate init` where the agent executes so the lesson can become a Pre-Action Gate instead of another reminder.
|
|
38
|
+
4. **Upgrade only after proof:** Solo Pro is for the dashboard, DPO export, proof-ready evidence, and higher capture limits after one real blocked repeat. Team starts with the Workflow Hardening Sprint around one repeated failure, one owner, and one proof review.
|
|
20
39
|
|
|
21
|
-
|
|
40
|
+
The buying question is simple: **what repeated AI mistake would be worth blocking before the next tool call?**
|
|
41
|
+
|
|
42
|
+
---
|
|
22
43
|
|
|
23
|
-
|
|
44
|
+
## The Problem — the bill nobody talks about
|
|
24
45
|
|
|
25
|
-
|
|
46
|
+
Frontier-model calls are not cheap. Sonnet 4.5 is ~$3 / 1M input tokens and ~$15 / 1M output tokens. Opus is 5× that. Every time your agent:
|
|
47
|
+
|
|
48
|
+
- hallucinates a function name and you have to correct it,
|
|
49
|
+
- retries the same failing tool call until it gives up,
|
|
50
|
+
- regenerates a 4,000-token plan you already approved last session,
|
|
51
|
+
- repeats a destructive command you blocked manually yesterday,
|
|
52
|
+
|
|
53
|
+
…you are paying for that round-trip. *Twice if it retries. Three times if you re-prompt.* And the agent has no memory across sessions, so the meter resets every Monday.
|
|
26
54
|
|
|
27
|
-
```
|
|
28
|
-
|
|
55
|
+
```
|
|
56
|
+
Session 1: Agent force-pushes to main. You fix it. +4,200 tokens
|
|
57
|
+
Session 2: Agent force-pushes again. You fix it. +4,200 tokens
|
|
58
|
+
Session 3: Same mistake. Again. You lose 45m. +5,800 tokens
|
|
29
59
|
```
|
|
30
60
|
|
|
31
|
-
|
|
61
|
+
That's ~$0.21 in tokens just to fix the same mistake three times — multiplied by every developer, every repeated-mistake class, every week. The math gets ugly fast.
|
|
32
62
|
|
|
33
|
-
|
|
63
|
+
## The Solution — fix it once, the bill never sees it again
|
|
34
64
|
|
|
35
|
-
|
|
65
|
+
```
|
|
66
|
+
Session 1: Agent force-pushes to main. You 👎 it. +4,200 tokens
|
|
67
|
+
Session 2: ⛔ Gate blocks the force-push. Zero round-trip. +0 tokens
|
|
68
|
+
Session 3+: Never happens again. +0 tokens
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
One thumbs-down. The PreToolUse hook intercepts the call **before** it reaches the model — no input tokens, no output tokens, no retry loop. The dashboard tracks **tokens saved this week** as a live counter so you can see exactly what your prevention rules are worth.
|
|
36
72
|
|
|
37
|
-
|
|
73
|
+
ThumbGate doesn't make your agent smarter. It makes your agent *cheaper to be wrong with.*
|
|
38
74
|
|
|
39
|
-
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Quick Start
|
|
40
78
|
|
|
41
79
|
```bash
|
|
42
|
-
|
|
80
|
+
npx thumbgate init # auto-detects your agent, wires everything
|
|
81
|
+
npx thumbgate capture "Never run DROP on production tables"
|
|
43
82
|
```
|
|
44
83
|
|
|
45
|
-
|
|
84
|
+
That single command creates a gate rule. Next time any AI agent tries to run `DROP` on production:
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
⛔ Gate blocked: "Never run DROP on production tables"
|
|
88
|
+
Pattern: DROP.*production
|
|
89
|
+
Verdict: BLOCK
|
|
90
|
+
```
|
|
46
91
|
|
|
47
92
|
---
|
|
48
93
|
|
|
49
|
-
##
|
|
94
|
+
## Architecture
|
|
50
95
|
|
|
51
|
-
|
|
96
|
+
ThumbGate operates as a 4-layer enforcement stack between your AI agent and your codebase:
|
|
52
97
|
|
|
53
|
-
ThumbGate
|
|
98
|
+
|
|
54
99
|
|
|
55
|
-
|
|
56
|
-
-
|
|
57
|
-
- **Turn AI into a reliable operator** — move from a smart assistant that apologizes after damage to a production-ready operator with checkpoints, proof, and enforcement.
|
|
100
|
+
### Layer 1: Feedback Capture
|
|
101
|
+
Your thumbs-up/down reactions are captured via MCP protocol, CLI, or the ChatGPT GPT surface. Each reaction is stored as a structured lesson with context, timestamp, and severity.
|
|
58
102
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
│ Session 1: Agent breaks something. You 👎 it. │
|
|
70
|
-
│ Session 2: ⛔ Gate blocks the mistake before it happens. │
|
|
71
|
-
│ Session 3+: Never see it again. │
|
|
72
|
-
└─────────────────────────────────────────────────────────────┘
|
|
73
|
-
```
|
|
103
|
+
### Layer 2: Gate Engine
|
|
104
|
+
The gate engine converts lessons into enforceable rules using pattern matching, semantic similarity (via LanceDB vectors), and Thompson Sampling for adaptive rule selection. Rules are stored locally in `.thumbgate/gates/`.
|
|
105
|
+
|
|
106
|
+
### Layer 3: Pre-Action Interception
|
|
107
|
+
Before any agent action executes, ThumbGate's `PreToolUse` hook intercepts the command and evaluates it against all active gates. This happens at the MCP protocol level — the agent physically cannot bypass it.
|
|
108
|
+
|
|
109
|
+
### Layer 4: Multi-Agent Distribution
|
|
110
|
+
Gates are distributed across all connected agents via MCP stdio protocol. One correction in Claude Code protects Cursor, Codex, Gemini CLI, and any MCP-compatible agent.
|
|
111
|
+
|
|
112
|
+
Prompt engineering still matters, but it is only the starting point. ThumbGate adds prompt evaluation on top: proof lanes, benchmarks, and self-heal checks tell you whether your prompt and workflow actually held up under execution instead of leaving you to guess from vibes.
|
|
74
113
|
|
|
75
|
-
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Install for Your Agent
|
|
121
|
+
|
|
122
|
+
| Agent | Command |
|
|
123
|
+
|-------|---------|
|
|
124
|
+
| **Claude Code** | `npx thumbgate init --agent claude-code` |
|
|
125
|
+
| **Cursor** | `npx thumbgate init --agent cursor` |
|
|
126
|
+
| **Codex** | `npx thumbgate init --agent codex` |
|
|
127
|
+
| **Gemini CLI** | `npx thumbgate init --agent gemini` |
|
|
128
|
+
| **Amp** | `npx thumbgate init --agent amp` |
|
|
129
|
+
| **Claude Desktop** | [Download extension bundle](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-claude-desktop.mcpb) |
|
|
130
|
+
| **Any MCP agent** | `npx thumbgate serve` |
|
|
131
|
+
|
|
132
|
+
Works with **Claude Code, Cursor, Codex, Gemini CLI, Amp, OpenCode**, and any MCP-compatible agent.
|
|
133
|
+
|
|
134
|
+
### Status bar proof
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
Claude renders the live ThumbGate footer today. `npx thumbgate init --agent codex` now installs the full Codex hook bundle and writes the ThumbGate `statusLine` target into `~/.codex/config.json` so you can test it on your local Codex build immediately.
|
|
141
|
+
|
|
142
|
+
### Install Codex Plugin
|
|
143
|
+
|
|
144
|
+
Download the standalone Codex plugin bundle and follow the install guide:
|
|
145
|
+
|
|
146
|
+
1. Download: [thumbgate-codex-plugin.zip](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-codex-plugin.zip)
|
|
147
|
+
2. Follow: [plugins/codex-profile/INSTALL.md](plugins/codex-profile/INSTALL.md)
|
|
76
148
|
|
|
77
149
|
---
|
|
78
150
|
|
|
79
|
-
## How It Works
|
|
151
|
+
## How It Works
|
|
80
152
|
|
|
81
153
|
```
|
|
82
154
|
STEP 1 STEP 2 STEP 3
|
|
@@ -91,46 +163,75 @@ ThumbGate is the **Reliability Gateway** for AI coding agents — turning your f
|
|
|
91
163
|
agent action reinforced (or ✅ allowed)
|
|
92
164
|
```
|
|
93
165
|
|
|
94
|
-
|
|
166
|
+
No manual rule-writing. No config files. Your reactions teach the agent what your team actually wants.
|
|
95
167
|
|
|
96
168
|
---
|
|
97
169
|
|
|
98
|
-
|
|
170
|
+
ThumbGate sells three concrete outcomes:
|
|
171
|
+
|
|
172
|
+
- **Prevent expensive AI mistakes** — catch bad commands, destructive database actions, unsafe publishes, and risky API calls before they run.
|
|
173
|
+
- **Make AI stop repeating mistakes** — fix it once, turn the lesson into a rule, and block the repeat before the next tool call lands.
|
|
174
|
+
- **Turn AI into a reliable operator** — move from a smart assistant that apologizes after damage to a production-ready operator with checkpoints, proof, and enforcement.
|
|
175
|
+
- **Measure prompts instead of rewriting them blindly** — use proof lanes, ThumbGate Bench, and `self-heal:check` to evaluate whether prompts and workflows actually improved behavior.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Use Cases
|
|
180
|
+
|
|
181
|
+
- **Stop force-push to main** — Gate blocks `git push --force` on protected branches before it runs
|
|
182
|
+
- **Prevent repeated migration failures** — Each mistake becomes a searchable lesson that fires before the next attempt
|
|
183
|
+
- **Block unauthorized file edits** — Control which files agents can touch with path-based rules
|
|
184
|
+
- **Memory across sessions** — The agent remembers your feedback from yesterday
|
|
185
|
+
- **Shared team safety** — One developer's thumbs-down protects the whole team
|
|
186
|
+
- **Auto-improving without feedback** — Self-improvement mode evaluates outcomes and generates rules automatically
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Built-in Gates
|
|
99
191
|
|
|
100
192
|
```
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
Agent force-pushes again. │ ⛔ Gate blocks force-push.
|
|
109
|
-
It learned nothing. │ Agent uses safe push instead.
|
|
110
|
-
│
|
|
111
|
-
Session 3: │ Session 3+:
|
|
112
|
-
Same mistake. Again. │ Permanently fixed.
|
|
113
|
-
And again. │
|
|
193
|
+
⛔ force-push → blocks git push --force
|
|
194
|
+
⛔ protected-branch → blocks direct push to main
|
|
195
|
+
⛔ unresolved-threads → blocks push with open reviews
|
|
196
|
+
⛔ package-lock-reset → blocks destructive lock edits
|
|
197
|
+
⛔ env-file-edit → blocks .env secret exposure
|
|
198
|
+
|
|
199
|
+
+ custom gates in config/gates/custom.json
|
|
114
200
|
```
|
|
115
201
|
|
|
116
202
|
---
|
|
117
203
|
|
|
118
|
-
##
|
|
204
|
+
## CLI Reference
|
|
119
205
|
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
206
|
+
```bash
|
|
207
|
+
npx thumbgate init # detect agent, wire hooks
|
|
208
|
+
npx thumbgate doctor # health check
|
|
209
|
+
npx thumbgate capture # create a gate from text
|
|
210
|
+
npx thumbgate lessons # see what's been learned
|
|
211
|
+
npx thumbgate explore # terminal explorer for lessons, gates, stats
|
|
212
|
+
npx thumbgate dashboard # open local dashboard
|
|
213
|
+
npx thumbgate serve # start MCP server on stdio
|
|
214
|
+
npx thumbgate bench # run reliability benchmark
|
|
129
215
|
```
|
|
130
216
|
|
|
131
217
|
---
|
|
132
218
|
|
|
133
|
-
##
|
|
219
|
+
## Pricing
|
|
220
|
+
|
|
221
|
+
| | Free | Pro ($19/mo) | Team ($49/seat/mo) |
|
|
222
|
+
|---|---|---|---|
|
|
223
|
+
| Local CLI + enforced gates | ✅ | ✅ | ✅ |
|
|
224
|
+
| Feedback captures/day | 3 | Unlimited | Unlimited |
|
|
225
|
+
| Prevention rules | 1 | Unlimited | Unlimited |
|
|
226
|
+
| Agent connections | 1 | Unlimited | Unlimited |
|
|
227
|
+
| Personal dashboard | — | ✅ | ✅ |
|
|
228
|
+
| DPO export (model fine-tuning) | — | ✅ | ✅ |
|
|
229
|
+
| Team lesson export/import | — | ✅ | ✅ |
|
|
230
|
+
| Shared hosted lesson DB | — | — | ✅ |
|
|
231
|
+
| Org-wide dashboard | — | — | ✅ |
|
|
232
|
+
| Approval + audit proof | — | — | ✅ |
|
|
233
|
+
|
|
234
|
+
The free tier gives you 3 feedback captures, 1 rule, and 1 agent — enough to prove the enforcement loop works. Pro is $19/mo or $149/yr for unlimited everything plus a dashboard and history-aware lesson recall. Team is $49/seat/mo with shared hosted lesson DB, org dashboard, and shared enforcement. Pro and Team include open_feedback_session, append_feedback_context, and finalize_feedback_session for structured multi-turn feedback capture.
|
|
134
235
|
|
|
135
236
|
**Best first paid motion for teams:** the **Workflow Hardening Sprint** — qualify one repeated failure before committing to a full rollout. **[Start intake →](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=team_rollout#workflow-sprint-intake)**
|
|
136
237
|
|
|
@@ -138,223 +239,135 @@ Session 3: │ Session 3+:
|
|
|
138
239
|
|
|
139
240
|
**Paid path for individual operators:** [ThumbGate Pro](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme&utm_campaign=pro_page) is the self-serve side lane for a personal dashboard and export-ready evidence.
|
|
140
241
|
|
|
141
|
-
**
|
|
242
|
+
**[Start free](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme)** · **[See Pro](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme)** · **[Team Sprint intake](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme#workflow-sprint-intake)**
|
|
142
243
|
|
|
143
244
|
---
|
|
144
245
|
|
|
145
|
-
##
|
|
146
|
-
|
|
147
|
-
```bash
|
|
148
|
-
npx thumbgate init # detects your agent and wires everything up
|
|
149
|
-
npx thumbgate doctor # health check
|
|
150
|
-
npx thumbgate lessons # see what's been learned
|
|
151
|
-
npx thumbgate explore # terminal explorer for lessons, gates, and stats
|
|
152
|
-
npx thumbgate dashboard # open local dashboard
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
Or wire MCP directly: `claude mcp add thumbgate -- npx --yes --package thumbgate thumbgate serve`
|
|
156
|
-
|
|
157
|
-
Works with **Claude Code, Cursor, Codex, Gemini CLI, Amp, OpenCode**, and any MCP-compatible agent.
|
|
246
|
+
## Team Lesson Sharing (Pro + Team)
|
|
158
247
|
|
|
159
|
-
|
|
248
|
+
One team's hard-won lessons shouldn't stay trapped on one laptop. ThumbGate Pro and Team can export lessons as portable bundles and import them into any other ThumbGate instance — so a mistake caught by Team A becomes a prevention rule for Team B.
|
|
160
249
|
|
|
161
|
-
|
|
250
|
+
**Export lessons from one project:**
|
|
162
251
|
|
|
163
|
-
### Claude Code
|
|
164
252
|
```bash
|
|
165
|
-
|
|
253
|
+
curl -X POST http://localhost:3456/v1/lessons/export \
|
|
254
|
+
-H "Authorization: Bearer $THUMBGATE_API_KEY" \
|
|
255
|
+
-H "Content-Type: application/json" \
|
|
256
|
+
-d '{"outputPath": "./lessons-export.json"}'
|
|
166
257
|
```
|
|
167
|
-
Wires hooks automatically. Works immediately.
|
|
168
258
|
|
|
169
|
-
|
|
170
|
-
```bash
|
|
171
|
-
npx thumbgate init --agent cursor
|
|
172
|
-
```
|
|
173
|
-
Installs as a Cursor extension with 4 skills: capture feedback, manage rules, search lessons, recall context.
|
|
259
|
+
Filter by signal or tags:
|
|
174
260
|
|
|
175
|
-
### Codex
|
|
176
261
|
```bash
|
|
177
|
-
|
|
262
|
+
curl -X POST http://localhost:3456/v1/lessons/export \
|
|
263
|
+
-H "Authorization: Bearer $THUMBGATE_API_KEY" \
|
|
264
|
+
-H "Content-Type: application/json" \
|
|
265
|
+
-d '{"signal": "down", "tags": ["push-notifications", "ci"]}'
|
|
178
266
|
```
|
|
179
|
-
Bridges to Codex CLI with 6 skills including adversarial review and second-pass analysis.
|
|
180
267
|
|
|
181
|
-
|
|
182
|
-
```bash
|
|
183
|
-
npx thumbgate init --agent gemini
|
|
184
|
-
```
|
|
268
|
+
**Import into another team's ThumbGate:**
|
|
185
269
|
|
|
186
|
-
### Amp
|
|
187
270
|
```bash
|
|
188
|
-
|
|
271
|
+
curl -X POST http://localhost:3456/v1/lessons/import \
|
|
272
|
+
-H "Authorization: Bearer $THUMBGATE_API_KEY" \
|
|
273
|
+
-H "Content-Type: application/json" \
|
|
274
|
+
-d @lessons-export.json
|
|
189
275
|
```
|
|
190
276
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
Starts the MCP server on stdio. Connect from any MCP-compatible client.
|
|
196
|
-
|
|
197
|
-
### Claude Desktop
|
|
198
|
-
Add to your `claude_desktop_config.json`:
|
|
199
|
-
```json
|
|
200
|
-
{
|
|
201
|
-
"mcpServers": {
|
|
202
|
-
"thumbgate": {
|
|
203
|
-
"command": "npx",
|
|
204
|
-
"args": ["--yes", "--package", "thumbgate", "thumbgate", "serve"]
|
|
205
|
-
}
|
|
206
|
-
}
|
|
207
|
-
}
|
|
208
|
-
```
|
|
209
|
-
Or [download the packaged extension bundle](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-claude-desktop.mcpb) and install directly.
|
|
277
|
+
What happens on import:
|
|
278
|
+
- **Deduplication** — lessons with the same ID or title+signal are skipped
|
|
279
|
+
- **Provenance tracking** — every imported lesson is tagged `team-import` with original source project, export timestamp, and original ID
|
|
280
|
+
- **No overwrite** — import is additive; existing lessons are never modified
|
|
210
281
|
|
|
211
|
-
|
|
282
|
+
The export bundle includes full lesson metadata: signal, title, context, tags, failure type, skill, structured rules, and diagnosis. It's the same data you see in the lesson detail dashboard — portable as JSON.
|
|
212
283
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
-
|
|
216
|
-
-
|
|
217
|
-
-
|
|
218
|
-
- **Memory across sessions** — The agent remembers your feedback from yesterday without any manual rule-writing
|
|
219
|
-
- **Shared team safety** — One developer's thumbs-down protects the whole team from the same mistake
|
|
220
|
-
- **Auto-improving without feedback** — Self-improvement mode evaluates outcomes and generates rules automatically
|
|
284
|
+
**Use cases:**
|
|
285
|
+
- Share enforcement patterns across repos in the same org
|
|
286
|
+
- Onboard a new team with pre-built lessons from a mature project
|
|
287
|
+
- Export lessons before a project handoff so institutional knowledge transfers
|
|
288
|
+
- Feed lessons from multiple teams into a centralized DPO training pipeline
|
|
221
289
|
|
|
222
290
|
---
|
|
223
291
|
|
|
224
|
-
##
|
|
225
|
-
|
|
226
|
-
Give the agent more context when a thumbs-down isn't enough:
|
|
227
|
-
|
|
228
|
-
```
|
|
229
|
-
👎 thumbs down
|
|
230
|
-
└─► open_feedback_session
|
|
231
|
-
└─► "you lied about deployment" (append_feedback_context)
|
|
232
|
-
└─► "tests were actually failing" (append_feedback_context)
|
|
233
|
-
└─► finalize_feedback_session
|
|
234
|
-
└─► lesson inferred from full conversation
|
|
235
|
-
```
|
|
292
|
+
## Tech Stack
|
|
236
293
|
|
|
237
|
-
|
|
294
|
+
| Layer | Technology |
|
|
295
|
+
|-------|-----------|
|
|
296
|
+
| **Storage** | SQLite + FTS5, LanceDB vectors, JSONL logs |
|
|
297
|
+
| **Capture** | 3 feedback capture/day (free), unlimited (Pro) |
|
|
298
|
+
| **Intelligence** | MemAlign dual recall, Thompson Sampling |
|
|
299
|
+
| **Enforcement** | PreToolUse hook engine, Gates config |
|
|
300
|
+
| **Interfaces** | MCP stdio, HTTP API, CLI (Node.js >=18) |
|
|
301
|
+
| **Billing** | Stripe |
|
|
302
|
+
| **Execution** | Railway, Cloudflare Workers, Docker Sandboxes |
|
|
303
|
+
| **Governance** | Workflow Sentinel, control plane, Docker Sandboxes |
|
|
238
304
|
|
|
239
|
-
|
|
305
|
+
Every Changeset is tied to the exact `main` merge commit and generates Verification Evidence for Release Confidence.
|
|
240
306
|
|
|
241
307
|
---
|
|
242
308
|
|
|
243
|
-
|
|
309
|
+
**Popular buyer questions:** **[Stop repeated AI agent mistakes](https://thumbgate-production.up.railway.app/guides/stop-repeated-ai-agent-mistakes?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)** · **[Cursor guardrails](https://thumbgate-production.up.railway.app/guides/cursor-agent-guardrails?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)** · **[Codex CLI guardrails](https://thumbgate-production.up.railway.app/guides/codex-cli-guardrails?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)** · **[Gemini CLI memory + enforcement](https://thumbgate-production.up.railway.app/guides/gemini-cli-feedback-memory?utm_source=github&utm_medium=readme&utm_campaign=buyer_questions)**
|
|
244
310
|
|
|
245
|
-
|
|
246
|
-
┌─────────────────────────────────────────────────────────┐
|
|
247
|
-
│ ENFORCEMENT LAYER │
|
|
248
|
-
│ │
|
|
249
|
-
│ ⛔ force-push → blocks git push --force │
|
|
250
|
-
│ ⛔ protected-branch → blocks direct push to main │
|
|
251
|
-
│ ⛔ unresolved-threads → blocks push with open reviews │
|
|
252
|
-
│ ⛔ package-lock-reset → blocks destructive lock edits │
|
|
253
|
-
│ ⛔ env-file-edit → blocks .env secret exposure │
|
|
254
|
-
│ │
|
|
255
|
-
│ + custom gates in config/gates/custom.json │
|
|
256
|
-
└─────────────────────────────────────────────────────────┘
|
|
257
|
-
```
|
|
311
|
+
**[Workflow Hardening Sprint](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=top_cta#workflow-sprint-intake)** · **[Live Dashboard](https://thumbgate-production.up.railway.app/dashboard?utm_source=github&utm_medium=readme&utm_campaign=top_cta)**
|
|
258
312
|
|
|
259
313
|
---
|
|
260
314
|
|
|
261
|
-
##
|
|
315
|
+
## Integrations
|
|
262
316
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
│ 3 captures/day │ Org-wide dashboard │ Review-ready exports │
|
|
270
|
-
│ 5 searches/day │ Approval + audit proof │ │
|
|
271
|
-
│ Unlimited recall │ Isolated execution guidance │ │
|
|
272
|
-
└──────────────────┴──────────────────────────────┴──────────────────────┘
|
|
273
|
-
```
|
|
274
|
-
|
|
275
|
-
**[Start Workflow Hardening Sprint](https://thumbgate-production.up.railway.app/?utm_source=github&utm_medium=readme&utm_campaign=top_cta#workflow-sprint-intake)** · **[Live Dashboard](https://thumbgate-production.up.railway.app/dashboard?utm_source=github&utm_medium=readme&utm_campaign=top_cta)** · **[See Pro](https://thumbgate-production.up.railway.app/pro?utm_source=github&utm_medium=readme&utm_campaign=pro_page)**
|
|
276
|
-
|
|
277
|
-
**Where to start:**
|
|
278
|
-
- **Teams:** Begin with the Workflow Hardening Sprint — prove one costly repeat failure can be blocked before committing to a full rollout
|
|
279
|
-
- **Solo operators:** ThumbGate Pro adds personal enforcement proof, a gate debugger, and export-ready evidence
|
|
280
|
-
- **Individuals & open source:** Free CLI tier, self-hosted, with local Pre-Action Gates after install
|
|
317
|
+
- **[Open ThumbGate GPT](https://thumbgate-production.up.railway.app/go/gpt?utm_source=github&utm_medium=readme&utm_campaign=readme_gpt)** — ThumbGate GPT: start here. Paste agent actions, get advice + checkpointing. No, users do not have to keep chatting inside the ThumbGate GPT to use ThumbGate — the hard enforcement layer still runs where the work happens.
|
|
318
|
+
- **[Claude Desktop Extension](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-claude-desktop.mcpb)** — One-click install for Claude Desktop
|
|
319
|
+
- **[Codex Plugin](https://github.com/IgorGanapolsky/ThumbGate/releases/latest/download/thumbgate-codex-plugin.zip)** — Standalone bundle for Codex CLI
|
|
320
|
+
- **[Perplexity Command Center](docs/PERPLEXITY_MAX_COMMAND_CENTER.md)** — AI-search visibility + lead discovery
|
|
321
|
+
- **[ThumbGate Bench](docs/THUMBGATE_BENCH.md)** — Reliability benchmark for gate evaluation
|
|
322
|
+
- **[Manus AI Skill](skills/thumbgate/SKILL.md)** — ThumbGate integration for Manus AI agents
|
|
281
323
|
|
|
282
324
|
---
|
|
283
325
|
|
|
284
|
-
##
|
|
326
|
+
## Feedback Sessions
|
|
327
|
+
|
|
328
|
+
Give the agent more context when a thumbs-down isn't enough:
|
|
285
329
|
|
|
286
330
|
```
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
│ File-based context │ selection) │ Hook wiring │
|
|
294
|
-
│ │ │ │
|
|
295
|
-
│ │ │ │
|
|
296
|
-
├──────────────────────┼──────────────────────┼──────────────────────┤
|
|
297
|
-
│ INTERFACES │ BILLING │ EXECUTION │
|
|
298
|
-
│ │ │ │
|
|
299
|
-
│ MCP stdio │ Stripe │ Railway │
|
|
300
|
-
│ HTTP API │ │ Cloudflare Workers │
|
|
301
|
-
│ CLI │ │ Docker Sandboxes │
|
|
302
|
-
│ Node.js >=18 │ │ │
|
|
303
|
-
└──────────────────────┴──────────────────────┴──────────────────────┘
|
|
331
|
+
👎 thumbs down
|
|
332
|
+
└─► open_feedback_session
|
|
333
|
+
└─► "you lied about deployment" (append_feedback_context)
|
|
334
|
+
└─► "tests were actually failing" (append_feedback_context)
|
|
335
|
+
└─► finalize_feedback_session
|
|
336
|
+
└─► lesson inferred from full conversation
|
|
304
337
|
```
|
|
305
338
|
|
|
339
|
+
Free and self-hosted users can invoke `search_lessons` directly through MCP, and via the CLI with `npx thumbgate lessons`. History-aware feedback sessions give the agent full context for each lesson.
|
|
340
|
+
|
|
306
341
|
---
|
|
307
342
|
|
|
308
343
|
## FAQ
|
|
309
344
|
|
|
310
345
|
**Is ThumbGate a model fine-tuning tool?**
|
|
311
|
-
No. ThumbGate does not update model weights
|
|
346
|
+
No. ThumbGate does not update model weights. It captures feedback, stores lessons, injects context at runtime, and blocks bad actions before they execute.
|
|
312
347
|
|
|
313
348
|
**How is this different from CLAUDE.md or .cursorrules?**
|
|
314
349
|
Those are suggestions the agent can ignore. ThumbGate gates are enforced — they physically block the action before it runs. They also auto-generate from feedback instead of requiring manual writing.
|
|
315
350
|
|
|
316
351
|
**Does it work with my agent?**
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
**What's self-improvement mode?**
|
|
320
|
-
ThumbGate can watch for failure signals (test failures, reverted edits, error patterns) and auto-generate prevention rules — no thumbs-down required. Your agent gets smarter every session.
|
|
352
|
+
If it supports MCP or pre-action hooks, yes. Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, Amp, OpenCode all work out of the box.
|
|
321
353
|
|
|
322
354
|
**Is it free?**
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
---
|
|
326
|
-
|
|
327
|
-
## Enterprise Story
|
|
328
|
-
|
|
329
|
-
ThumbGate is the control plane for AI coding agents:
|
|
330
|
-
|
|
331
|
-
- Feedback becomes enforcement — repeated failures stop at the gate instead of reappearing in review.
|
|
332
|
-
- **Workflow Sentinel** scores blast radius before execution, so risky PR, release, and publish flows are visible early.
|
|
333
|
-
- High-risk local actions route into **Docker Sandboxes**; hosted team automations use a signed isolated sandbox lane.
|
|
334
|
-
- Team rollout stays tied to [Verification Evidence](docs/VERIFICATION_EVIDENCE.md) instead of trust-me operator claims.
|
|
335
|
-
|
|
336
|
-
## Release Confidence
|
|
337
|
-
|
|
338
|
-
- Every PR must carry a **Changeset** entry — each shipped version has a customer-readable explanation before publish.
|
|
339
|
-
- Version-sync checks keep `package.json`, `CHANGELOG.md`, plugin manifests, and installer metadata aligned.
|
|
340
|
-
- Final close-out requires verifying the exact `main` merge commit, with proof anchored in [Verification Evidence](docs/VERIFICATION_EVIDENCE.md).
|
|
341
|
-
|
|
342
|
-
See [Release Confidence](docs/RELEASE_CONFIDENCE.md) for the full trust chain.
|
|
355
|
+
The free tier gives you 3 captures/day, 1 rule, and 1 agent — enough to prove the enforcement loop works. Pro is $19/mo or $149/yr for unlimited everything plus a dashboard. Team is $49/seat/mo with shared hosted lesson DB, org dashboard, and shared enforcement.
|
|
343
356
|
|
|
344
357
|
---
|
|
345
358
|
|
|
346
359
|
## Docs
|
|
347
360
|
|
|
348
|
-
- [Commercial Truth](docs/COMMERCIAL_TRUTH.md) — pricing, claims, what we don't say
|
|
349
|
-
- [Changeset Strategy](docs/CHANGESET_STRATEGY.md) — how release notes and version bumps are enforced
|
|
350
361
|
- [First Dollar Playbook](docs/FIRST_DOLLAR_PLAYBOOK.md) — turning one painful workflow into the next booked pilot
|
|
351
|
-
- [
|
|
352
|
-
- [
|
|
362
|
+
- [Commercial Truth](docs/COMMERCIAL_TRUTH.md) — pricing, claims, what we don't say
|
|
363
|
+
- [Changeset Strategy](docs/CHANGESET_STRATEGY.md) — release notes and version bump enforcement
|
|
364
|
+
- [Release Confidence](docs/RELEASE_CONFIDENCE.md) — changesets, version checks, proof lanes
|
|
353
365
|
- [Verification Evidence](docs/VERIFICATION_EVIDENCE.md) — proof artifacts
|
|
354
|
-
- [
|
|
355
|
-
- [
|
|
356
|
-
|
|
357
|
-
|
|
366
|
+
- [Claude Desktop Extension Guide](docs/CLAUDE_DESKTOP_EXTENSION.md)
|
|
367
|
+
- [Agent Workflow Contract](WORKFLOW.md) — the agent-run contract for all ThumbGate operations
|
|
368
|
+
- [Ready for Agent Intake](https://github.com/IgorGanapolsky/ThumbGate/issues/new?template=ready-for-agent.yml) — ready-for-agent intake template
|
|
369
|
+
- [SEO Guide: Claude Code Guardrails](docs/learn/claude-code-guardrails.md)
|
|
370
|
+
- [Pro Overlay Repository](https://github.com/IgorGanapolsky/thumbgate-pro) — paid overlay code in the separate `thumbgate-pro` repo/package
|
|
358
371
|
|
|
359
372
|
---
|
|
360
373
|
|
package/adapters/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
- `chatgpt/openapi.yaml`: import into GPT Actions.
|
|
4
4
|
- `gemini/function-declarations.json`: Gemini function-calling definitions.
|
|
5
5
|
- `mcp/server-stdio.js`: underlying local MCP stdio server implementation.
|
|
6
|
-
- `claude/.mcp.json`: example Claude Code MCP config using `npx --yes --package thumbgate@1.
|
|
6
|
+
- `claude/.mcp.json`: example Claude Code MCP config using `npx --yes --package thumbgate@1.5.1 thumbgate serve`.
|
|
7
7
|
- `codex/config.toml`: example Codex MCP profile section using the same version-pinned portable launcher.
|
|
8
8
|
- `amp/skills/thumbgate-feedback/SKILL.md`: Amp skill template.
|
|
9
9
|
- `opencode/opencode.json`: portable OpenCode MCP profile using the same version-pinned portable launcher.
|