PinnedAI

Pinned creates a local AI-coder safety net on install, writes repo-specific lessons, and blocks AI from weakening protected guards.

Free beta · Founder Pro waitlist open at pinnedai.dev.

The 5-step value loop

1. pinned init scans your repo and creates baseline guards on install (auth checks, lockfile integrity, secret prefixes, route registrations, webhook signatures, URL literals, exports, form error-handling, more).

2. Guard Integrity blocks any commit that tries to delete, skip, weaken, or --no-verify-bypass a guard.

3. AI Lessons file (.pinned/ai-lessons.md) captures repo-specific rules — read by Claude / Cursor / Devin / Copilot before they edit.

4. pinned audit --learned scans sibling code paths for the same mistake pattern.

5. Future AI edits must pass every guard. The output of every finding is an executable test, not a review comment.

Proof it works: see the /proof page for benchmark results, or jump to Status below for the headline numbers.

Quickstart

# See what Pinned does on a sample claim — no install, no signup
npx pinnedai

# Install in your repo (one command)
npx pinnedai init

# After init, on every commit Pinned blocks AI bypass attempts and
# auto-protects new admin/middleware/webhook/client-fetch code.

pinned init writes .github/workflows/pinned.yml, creates tests/pinned/ with PINS.md, installs pre-commit + pre-push hooks, auto-generates baseline pins from your current code, and seeds AI-coder rules into CLAUDE.md + .github/copilot-instructions.md (and any other AI rule file already in the repo). Each step prompts before writing in interactive mode; pass --auto to accept all.

If your repo already has .cursorrules, .clinerules, AGENTS.md, or .windsurfrules, init writes to those too — same marker-bounded block, identical uninstall flow (pinned uninstall-agent-rules).

Editor + AI-tool surfaces

Pinned ships across every major AI-coder surface:

Per-tool integration docs:

• docs/integrations/cursor-rules.md

• docs/integrations/windsurf-rules.md

• docs/integrations/claude-code.md

README badge

[![Pinned protected](https://pinnedai.dev/badge.svg)](https://pinnedai.dev)

What Pinned protects

Pinned focuses on AI-prone failure modes:

• Guard weakening — .skip(), .only(), xit(), .todo(), .skipIf(true), deleted tests, weakened assertions (toBe(401) → toBeTruthy()), || true, ?? true, catch(() => true), expect(true).toBe(true) tautologies, commented-out expect(), expect.assertions(0), early return; in test body.

• Pinned-infrastructure tampering — deletion of tests/pinned/*, .github/workflows/pinned.yml, tests/pinned/.registry.json, .pinned/ai-lessons.md, or sneaky rename-to-retired/ without the matching .audit.json.

• Client / API mistakes — missing authHeaders(), missing credentials: "include", lost if (!res.ok) gates, removed 401/402/403 handling. Detected statically per file via path + pattern heuristics.

• Auth / middleware regressions — requireAuth / requireAdmin / middleware matcher coverage; the middleware-aware pin uses middleware.ts's captured auth signature so removing the auth check fails the guard.

• Route / export / reference integrity — internal <Link href="/foo"> / navigate("/foo") / router.push("/foo") that resolve today are pinned; if a future commit removes the target page file, the pin fails.

• Webhook signature verification — stripe.webhooks.constructEvent, x-hub-signature-256, svix.verify, twilio.validateRequest, generic crypto.createHmac("sha256", ...). Pinned captures the verify call so removing it fails the guard.

• Public exposure no-fixture checks — .env committed without .gitignore coverage, .map files in dist//build/, debug routes (__debug, __test, debug.html, /admin/console).

AI lessons

Pinned writes repo-specific lessons to .pinned/ai-lessons.md (markdown for humans) and .pinned/lessons.json (structured for tools).

Each lesson is generated from a real event — a blocked bypass attempt, a replay-verified bug-fix guard, or a confirmed sibling audit. Dedupe is per guardId: repeat attempts append evidence to the existing entry, not duplicate sections.

Example:

## Don't weaken client-getReport-authHeaders

<!-- pinned:guard=client-getReport-authHeaders kind=guard-block -->

**Past mistake:**
weakened: src/api/getReport.ts — `headers: await authHeaders()` removed in PR #88

**Rule:**
Do not remove `authHeaders()` from `src/api/getReport.ts`. Fix the application code instead.

**Guard:** `client-getReport-authHeaders`

**Plain English:** don't drop authHeaders() from API calls

Point your AI coder at this file with pinned install-agent-rules so Claude/Cursor reads the rules before editing.

Commands

Setup

npx pinnedai init                    # one-time per repo
npx pinnedai install-agent-rules     # opt-in: wire CLAUDE.md/.cursorrules/etc. to read .pinned/ai-lessons.md
npx pinnedai uninstall-agent-rules   # undo the above
npx pinnedai agent-rules             # show which agent files are wired

Daily workflow

npx pinned test                      # run the pin suite
npx pinned status                    # see active pins + recent events
npx pinned context                   # print the AI-coder context (rules + lessons) for inline prompting

Discovery

npx pinned scan-diff                 # show what Pinned would auto-protect in the current diff
npx pinned audit --learned           # scan sibling code paths for risks matching learned patterns
npx pinned probe-admin               # enumerate admin/internal routes + their protection state
npx pinned list                      # list all active + retired pins

Lifecycle

npx pinned retire <claim-id> --reason="..."   # legitimate retirement (writes audit entry)

Internal (called by hooks)

npx pinned check-guard-removal       # pre-commit hook entry; blocks AI bypass attempts
npx pinned statusline                # statusline rendering for Claude Code
npx pinned backtest --mode=bug-fix   # replay a repo's git history (calibration tool)

Optional AI-assisted analysis (BYOK)

PINNEDAI_BYOK=openai PINNEDAI_OPENAI_KEY=sk-... npx pinned check

LLM-as-proposer fires on each commit's diff to suggest additional guards the deterministic detectors might miss. Customer pays their LLM vendor directly; Pinned doesn't proxy.

Statusline

Pinned surfaces protection events without becoming a noisy reviewer. Events decay back to a calm baseline:

◆ pinned · 34 pins · 7 lessons · ✓ 12 verified                  # baseline
◆ pinned · 34 pins · ⚠ 2 protected files in this commit          # editing guarded files
◆ pinned · 34 pins · ⛔ blocked: AI weakened pin sample.test.ts   # Guard Integrity refused
◆ pinned · 34 pins · +1 new guard                                # SAVED
◆ pinned · 34 pins · scanned 3 similar files                     # AUDIT
◆ pinned · 34 pins · 4 guards passed                             # COVERED
◆ pinned · 34 pins · learned: don't drop authHeaders() from API calls  # LEARNED
◆ pinned · 34 pins · ✗ 1 broken                                  # failing pin

The BLOCK / LEARNED / SAVED / AUDIT / COVERED transients fall back to baseline after 1-2 minutes. Persistent value = guard count + lesson count.

What Pinned is NOT

Pinned is not a generic code reviewer, SAST scanner, or AI bug-fixer.

CodeRabbit reviews PRs. Snyk / Semgrep scan for broad security issues. They run once and leave comments.

Pinned protects the repo-specific promises your AI coder must not forget: the bug fixes, guards, tests, and lessons that should survive future AI edits. The output of every finding is an executable guard, not a comment.

AI and privacy

Pinned works without an LLM. The core engine is deterministic: guards either pass, fail, or were weakened.

Optional AI-assisted mode (BYOK) can propose additional guards, sibling audits, and lessons from diff context. AI output never enforces anything by itself — deterministic guards + CI do the enforcement.

Principle:

LLM proposes. Guards prove. CI enforces.

Local-first. Free beta runs entirely on your machine + your CI. Pinned doesn't see your code unless you set BYOK env vars (in which case the calls go directly to your LLM vendor, not through Pinned infrastructure).

Free vs Founder Pro

Founder Pro is a waitlist today — no payment, no card. We collect interest to gauge demand for the paid features above. When paid opens, founder pricing locks for everyone on the list.

Join the waitlist →

Status

v0.1 (free beta) ships with:

• 8 Guard Integrity detectors (23 / 23 known AI bypass tactics blocked in our mutation-test suite)

• AI Lessons file + opt-in agent-config wiring (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, etc.)

• 6 P0 detector categories generating pins at init: Guard Integrity, client fetch / auth-headers / error-handling, auth/middleware, route/export/reference integrity, public exposure, webhook signature

• pinned audit --learned for sibling discovery

• pinned probe-admin for admin-route enumeration

• pinned context for runtime AI-coder briefing

• Statusline events for BLOCK / SAVED / AUDIT / COVERED / LEARNED / VERIFIED + baseline N pins · M lessons

Open beta. Bug reports + feature requests welcome at github.com/pinnedai/pinnedai/issues.

License

Apache 2.0. CLI source is public; the Cloudflare Worker that backs the (coming) hosted AI / cross-repo lessons / dashboard features stays private.