ThumbGate

Self-improving pre-action firewall for AI coding agents
AI coding agents repeat mistakes — and one wrong tool call can wipe a directory, leak a key, or push broken code.

ThumbGate is the local-first Pre-Action Checks engine for AI coding agents. It runs in the PreToolUse hook to evaluate the proposed tool call before execution — so costly mistakes can be caught before they happen.

Lightweight visuals for how agents fail without a pre-action gate:

Meme	Meaning
	Unchecked tool calls ship destructive commands.
	A prompt is advice; a PreToolUse hook is enforcement.

It hard-blocks detected secret leaks and two direct self-disable command classes by default — commands that terminate the ThumbGate gate process or enable its bypass environment override. Other high-risk classes (rm -rf, force-push, fetch-and-run, direct guardrail edits) warn and log by default. Set THUMBGATE_STRICT_ENFORCEMENT=1 for strict enforcement (warnings become hard denies).

Accepted feedback is stored as local lessons. Repeated concrete failures can become prevention rules that promote from warnings to blocking gates. The firewall improves from operations without retraining the model. Prompt evaluation (npx thumbgate eval) turns accepted feedback into reusable eval cases and local proof reports.

Honest disclaimer: ThumbGate does not update model weights. It intercepts tool calls at runtime. Local-first — no cloud required for the enforcement path.

Works with Claude Code, Cursor, Codex, Gemini CLI, Amp, Cline, OpenCode, and other MCP agents.

  Agent tries:   rm -rf tests/
  ThumbGate:     👎 WARN + LOG — "Never delete test directories"
                 Pattern matched: rm.*-rf.*tests
                 Source: your thumbs-down from last Tuesday
                 Strict mode: ⛔ DENY before tool execution

Agentic development is becoming a loop: Guide → Generate → Verify → Solve. ThumbGate is the pre-action gate / pre-action boundary between generated intent and executed action.

Want a phased walkthrough with a verify step at every stage? Follow the Progressive Setup Guide.

Progressive wiring — prove the pipe before you turn matching on. Empty dashboard is success.

npx thumbgate init          # Phase 1: hooks only
npx thumbgate doctor        # verify: exits 0 only when PreToolUse hook is wired (hidden metric = hook install, not gate count)
npx thumbgate dashboard --open  # Phase 2: open local HTML; empty stats are OK
npx thumbgate capture --feedback=down --context="Never run DROP on production tables" --what-went-wrong="agent proposed DROP" --what-to-change="require review for DROP"

Later DROP attempts in the same scope surface the check:

⚠️ Check fired: "Never run DROP on production tables"
   Pattern: DROP.*production
   Verdict: 👎 WARN + LOG   (⛔ BLOCK when THUMBGATE_STRICT_ENFORCEMENT=1)

Numbered configs: config/progressive/. Guide: progressive wiring.

Directories and clients that install ThumbGate as an MCP server must start stdio MCP, not the HTTP API:

npx -y thumbgate serve

• Equivalent: npx -y thumbgate mcp
• Do not use npm start for MCP — that launches the hosted HTTP API (src/api/server.js), not the agent-facing stdio server.

▶ 90-second demo · GIF walkthrough

Per-agent guides: Claude/Codex bridge · Codex profile · Cursor · MCP setup

Both scopes write mcpServers.thumbgate plus PreToolUse / UserPromptSubmit / PostToolUse / SessionStart hooks. Machine-wide is the right default for most developers. Cross-repo blocking is not automatic: a lesson learned in one project only applies elsewhere when you share the store (machine-wide) or export/import lessons.

MCP tools (surface): gate_check (read/evaluate proposed tool call), feedback capture + session tools (write), dashboard/stats (read). Destructive agent actions stay blocked/warned by PreToolUse — ThumbGate does not execute user shell commands for you.

Spec-driven agent frameworks like GSD (get-shit-done) and GitHub Spec Kit plan and generate work. ThumbGate is the guardrail layer for spec-driven agents: it sits after the plan, on the boundary between a generated tool call and its execution — alongside GSD / Spec-Kit, not instead of them.

npx thumbgate init installs these into your agent palette:

Free tier: 2 feedback captures/day (10 total) and up to 3 active auto-promoted prevention rules. Pro ($19/mo or $149/yr) is the individual tier for unlimited rules, history-aware lessons, linked feedback session flow, personal dashboard, and DPO export. Enterprise is custom and scoped after intake; hosted team lesson sync and a hosted org dashboard are not general availability.

Enterprise intake path: the Workflow Hardening Sprint scopes one repeated failure before any broader rollout commitment. Start intake →

Local technical path: install the CLI and use init plus the documented setup so Pre-Action Checks evaluate tool calls where the agent actually runs.

First-dollar activation path: open the ThumbGate GPT, paste the risky action, capture typed feedback (thumbs down: / thumbs up:). Native ChatGPT rating buttons are not the ThumbGate capture path. Ask: what repeated AI mistake would be worth catching before the tool executes?

Paid path for individual operators: ThumbGate Pro is the self-serve side lane for a personal dashboard and export-ready evidence.

Start free · Pro $19/mo · Live Dashboard · Team Sprint intake · Workflow Hardening Sprint · First Dollar Playbook

Popular buyer questions: AI search topical presence · Relational knowledge and AI recommendations · AI Mode ads for agent governance · MCP tool governance · AI agent pre-action approval gates · Background agent governance · GPT-5.5 model evaluation · Stop repeated AI agent mistakes · Browser automation safety · Native messaging host security · Autoresearch agent safety · Cursor guardrails · Codex CLI guardrails · Gemini CLI memory + enforcement · Google Cloud MCP guardrails · Roo Code alternative: migrate to Cline

1. Capture 👍/👎 feedback (CLI, MCP, linked feedback session flow / open_feedback_session, or ThumbGate GPT)
2. Promote concrete lessons via history-aware lesson distillation into prevention rules
3. Evaluate the next proposed tool call against active rules (literal/AST + local vectors)
4. Allow / warn / deny before the tool runs

npx thumbgate brain --write   # → .thumbgate/BRAIN.md (lessons + gates in one artifact)

Pro operators can invoke search_lessons through MCP and use npx thumbgate lessons from the CLI. History-aware feedback sessions and lesson search are Pro capabilities; Free does not include recall or search.

flowchart LR
    A["Agent tool call"] --> B{"Rule match?"}
    B -- exact --> D["On-device gate"]
    B -- semantic --> C["Local LanceDB"]
    C --> D
    D -- secret/kill --> E["⛔ Hard-block"]
    D -- known-bad --> G["👎 Warn + log"]
    D -- safe --> F["👍 Allow"]

⛔ secret-exfiltration → hard-block (default)
⛔ self-protect-kill   → hard-block (default)
⛔ self-protect-env    → hard-block (default)
⚠️ force-push          → warn; hard-block under strict
⚠️ protected-branch    → warn; hard-block under strict
⚠️ unresolved-threads  → warn; hard-block under strict
⚠️ package-lock-reset  → warn; hard-block under strict

npx thumbgate init
npx thumbgate doctor
npx thumbgate capture up|down "<text>"
npx thumbgate lessons
npx thumbgate brain --write
npx thumbgate dashboard --open
npx thumbgate break-glass --reason="ThumbGate over-fired"   # 5-min recovery

# Portable lessons
curl -X POST http://localhost:3456/v1/lessons/export \
  -H "Authorization: Bearer $THUMBGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outputPath": "./lessons-export.json"}'

# DPO pairs for fine-tuning
curl -X POST http://localhost:3456/v1/dpo/export \
  -H "Authorization: Bearer $THUMBGATE_API_KEY" \
  -o dpo-pairs.jsonl

Every Changeset is tied to the exact main merge commit and generates Verification Evidence for Release Confidence.

Full index: docs/INDEX.md

FAQ (one-liners): Not a fine-tuner (runtime intercept only). Different from CLAUDE.md / .cursorrules (those are context; ThumbGate is an external allow/warn/deny before tools run).

Igor Ganapolsky — payments (Stripe/Connect), AI agent guardrails/MCP, Android + backends. Small number of contract slots: $120–150/hr, 1099, remote US. LinkedIn · thumbgate.ai

MIT — see LICENSE. Project policy: SECURITY.md · THREAT_MODEL.md.