ThumbGate — Pre-Action Checks for AI Agents

ThumbGate turns thumbs-up/down feedback into hard enforcement checks that block
known-bad agent actions before they execute. Think of it as an immune system
for your AI agent.

npm package: thumbgate
Docs: https://github.com/IgorGanapolsky/ThumbGate

Quick Start

If ThumbGate is not yet installed in this project:

npx thumbgate init

This bootstraps .thumbgate/ data directory and .mcp.json config. Works with
Codex, Cursor, Codex, Gemini CLI, Amp, OpenCode, and any MCP-compatible agent.

Core Commands

Capture feedback

When an agent action succeeds or fails, capture it:

# Thumbs down — something went wrong
node .Codex/scripts/feedback/capture-feedback.js \
  --feedback=down \
  --context="what happened" \
  --what-went-wrong="specific failure" \
  --what-to-change="specific fix" \
  --tags="tag1,tag2"

# Thumbs up — something worked
node .Codex/scripts/feedback/capture-feedback.js \
  --feedback=up \
  --context="what happened" \
  --what-worked="specific thing that worked" \
  --tags="tag1,tag2"

View active gates and rules

npm run feedback:rules       # Show prevention rules generated from feedback
npm run feedback:stats       # Feedback counts by signal, domain, importance
npm run feedback:summary     # Aggregated summary of all feedback

Check system health

npm run self-heal:check      # Verify 4/4 subsystems healthy

Export training data (Pro)

npm run feedback:export:dpo  # Export DPO preference pairs for fine-tuning

How Gates Work

1. Feedback — You give thumbs-up or thumbs-down on agent actions
2. Rules — Repeated failures auto-promote into prevention rules via Thompson Sampling
3. Gates — Rules become PreToolUse hooks that block the agent before it repeats the mistake

Gates are enforced via MCP PreToolUse hooks — the agent literally cannot execute
a blocked action. This is hard enforcement, not a soft suggestion.

Architecture

Component	What it does
SQLite+FTS5 lesson DB	Fast full-text search across all feedback
Thompson Sampling	Adaptive gate sensitivity per failure domain
LanceDB + HuggingFace	Local vector search for semantic similarity
ContextFS	Hierarchical context assembly with semantic caching
PreToolUse hooks	Hard enforcement — blocks before execution

MCP Tools Available

When the MCP server is running, these tools are available to your agent:

Tool	Purpose
capture_feedback	Record thumbs-up/down on an agent action
search_lessons	Search past feedback by keyword, tag, or domain
recall	Retrieve relevant memories for current context
prevention_rules	View active prevention rules
gate_stats	See which gates are firing and their block rates
feedback_stats	Feedback counts and trends
export_dpo_pairs	Export DPO training pairs (Pro)
construct_context_pack	Build bounded context from feedback history

Pro Features

Pro users ($19/mo or $149/yr) unlock:

• Visual gate debugger — see every blocked action and the gate that fired
• Multi-hop recall — chain related lessons across hops for deeper context
• Synthetic DPO augmentation — expand real feedback into larger training datasets
• Gate wiring support — help enforcing your riskiest flows in the first week

Team rollout ($49/seat/mo, 3-seat minimum after intake) adds the shared hosted lesson DB,
org dashboard, approval boundaries, and proof-backed workflow hardening sprint.

Upgrade: https://thumbgate-production.up.railway.app/go/pro?utm_source=skill

Detailed Reference

For setup guides per agent, see: <references/setup-guides.md>
For gate configuration, see: <references/gate-config.md>