Introduction

Get started with Bilt in under 5 minutes. No account creation or telemetry setup is required.

Step 1: Install Bilt

Install bilt-toolkit locally into your project repository or globally:

npm install -D bilt-toolkit

Step 2: Initialize Configuration

Run initialization to scaffold a .biltrc.json configuration file and set up guidelines for coding agents:

npx bilt init

To write instruction files specifically for AI agents (Cursor, Claude Code), use npx bilt init --agent default.

Step 3: Run First Health Scan

Execute the production-readiness check across your codebase:

# Evaluate full project repository
npx bilt check

# Evaluate only uncommitted edits in working tree
npx bilt check --changed

Step 4: Understand Gate Decisions

Bilt uses standardized exit codes designed for both human terminal review and automated pipelines:

Step 5: Enforce in CI / Pull Requests

Add a GitHub Actions workflow to run strict verification on pull requests against your default branch:

name: Bilt Verification Gate
on: [pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Verify PR Diff
        run: npx bilt-toolkit verify --base origin/${{ github.base_ref }} --format agent

Bilt is engineered to run entirely on your local machine and in isolated CI runners with zero network egress.

1. Zero-Telemetry Offline Guarantee

Bilt contains no telemetry, analytics beacons, or remote tracking. Source code, secrets, and environment configurations never leave your machine during check, verify, or scan operations.

2. High-Performance AST Analysis

Bilt parses JavaScript, TypeScript, Python, and configuration files into Abstract Syntax Trees (ASTs). Rather than relying on fragile keyword regexes, Bilt performs semantic tree analysis to identify:

• Direct database client instantiation inside client-side components.
• Route parameter extraction for IDOR verification (/api/users/:id).
• String concatenation inside database query calls (SQL injection).
• Server environment variables referenced in client bundles (NEXT_PUBLIC_).

3. Atomic Snapshot Engine

When executing automated repairs via bilt fix, Bilt captures an atomic file system snapshot in .bilt/snapshots/ before modifying any file. Running bilt undo restores the prior state in sub-2ms with complete transaction isolation.

Bilt provides deterministic, application-level security analysis specifically engineered for software built with AI coding assistants (Claude Code, Cursor, Windsurf, Devin, Codex, Antigravity) and human development teams.

1. Security Philosophy & Authority

Bilt's analysis model is governed by two uncompromising principles:

• Deterministic Analysis as the Security Authority: AI never decides whether code passes, fails, or meets production gates. All security evaluations are driven by mathematical AST traversal (Babel parser), Shannon entropy algorithms (H > 4.5 bits/char), cryptographic provider specifications, and taint-style data-flow tracing from route inputs to database sinks. Optional AI assistance (via bilt explain or downstream agent loops) only generates natural language explanations or suggested patches—it has zero authority over the gate status.
• Honest Scope Without Vanity Metrics: Bilt does not claim complete OWASP compliance, nor does it generate arbitrary security scores (e.g. “98% secure”) or vague marketing claims like “enterprise-grade security.” Where a security property can be proven deterministically, Bilt enforces it with an automated pass or fail. Where an issue depends on multi-tenant business intent or external cloud configuration, Bilt flags it as needs-review with concrete evidence and verification procedures.

2. Superficial Scanners vs. Bilt

Traditional linters and superficial scanners rely on simple keyword matches that trigger excessive false alarms on legitimate code while missing real structural flaws. Bilt traces execution context, data flow, and authorization boundaries.

3. Implemented Security Checks & Rule Matrix

Bilt implements concrete static rules and guided verification routines covering critical application security domains, mapped to corresponding OWASP Top 10 and CWE categories:

Hardcoded Secrets & Credentials

What Bilt looks for: Hardcoded API tokens, private keys, cloud credentials, and connection strings across 31+ cryptographic providers (AWS, Stripe, OpenAI, GitHub, Supabase, Anthropic, Slack, Twilio, SendGrid, database URIs).
Evidence analyzed: Pattern matching on provider key prefixes (e.g. AKIA, sk_live_), Shannon entropy (H > 4.5), and scanner checks on committed .env files.
Why it matters: Leaked credentials grant immediate administrative access to databases, third-party APIs, and cloud infrastructure.
Mode & Remediation: Fully Automated. bilt fix --safe moves secrets to .env, updates source references to process.env, updates .gitignore, and generates .env.example placeholders.

Environment & Configuration Security

What Bilt looks for: Server secrets prepended with client public prefixes (NEXT_PUBLIC_, VITE_, REACT_APP_ containing keywords like SECRET, SERVICE_ROLE, or DATABASE_URL); duplicate env entries; missing .env.example; and unmapped env references.
Evidence analyzed: AST property evaluation of process.env cross-referenced against all .env* files in the workspace.
Why it matters: Client public prefixes cause build bundlers to inline backend secrets into client JavaScript bundles accessible to any browser visitor.
Mode & Remediation: Fully Automated. Removes public prefixes from backend secrets and synchronizes missing keys into .env.example.

Authentication Weaknesses

What Bilt looks for: jwt.decode() without cryptographic verify, plaintext password comparison (password === user.password), weak hashes (MD5, SHA1), auth bypass stubs (return true in auth filters), hardcoded admin credentials, and JWTs issued without expiry.
Evidence analyzed: AST call expressions, binary expression operators, and route handler middleware chains.
Why it matters: Unverified tokens allow attackers to forge arbitrary claims. Plaintext password comparisons lead to total credential compromise upon database exposure.
Mode & Remediation: Automated checks for structural flaws; Guided review for overall authentication flow. Automatically upgrades jwt.decode() to jwt.verify() when signing secret references are present.

Authorization & Privilege Escalation

What Bilt looks for: Privileges, user roles, or administrator flags read directly from client-controlled request inputs (req.body.isAdmin, req.body.role, req.query.role, or localStorage) without server session validation.
Evidence analyzed: AST member expressions on request parameters inside API mutation handlers.
Why it matters: Attackers forge HTTP payloads to elevate themselves to administrator privileges without administrative rights.
Mode & Remediation: Automated detection with hard FAIL (AUTHZ-AUTO-002). Guided code update: derive user roles exclusively from verified server sessions or signed JWT claims.

Broken Object-Level Authorization (IDOR / BOLA)

What Bilt looks for: Endpoints with dynamic route parameters (/api/orders/:id, /documents/[id]) querying database records without checking resource ownership against the authenticated user.
Evidence analyzed: RouteMap dynamic path parameters cross-referenced with database lookup parameters (findById, findUnique, where: { id }) lacking userId: session.user.id filters.
Why it matters: Any authenticated user can modify the ID parameter in the URL to view, modify, or delete another user's records.
Mode & Remediation: Guided (needs-review). Non-negotiable architectural invariant: IDOR emits needs-review rather than fail because ownership models frequently involve multi-table tenant checks. Bilt provides query scoping guidance.

Mass Assignment Vulnerabilities

What Bilt looks for: Request bodies passed directly into persistence operations (prisma.user.update({ data: req.body }), Model.create(req.body)) where the target model contains sensitive columns (role, isAdmin, balance, tenant_id).
Evidence analyzed: Data-flow paths connecting req.body to ORM mutations without schema allowlisting or field destructuring.
Why it matters: Callers can inject extra fields into request payloads to overwrite protected database properties.
Mode & Remediation: Automated (High severity). Guided code remediation: explicitly destructure permitted fields (const { name, bio } = req.body) or validate through a strict Zod schema.

Input Validation & Injection (SQLi, Command, XSS)

What Bilt looks for:

• SQL Injection (CHECK-INPUT-001): Template literal interpolation or string concatenation in queries (query(`SELECT * FROM users WHERE id = ${id}`), $queryRawUnsafe).
• Command Injection (CHECK-INPUT-002): Dynamic arguments in exec(), spawn(), or child_process.
• Path Traversal (CHECK-INPUT-003): User parameters passed directly to filesystem read/write routines.
• Unsafe HTML Rendering (CHECK-INPUT-004): Raw dangerouslySetInnerHTML without DOMPurify sanitization.
• Missing Schema Validation (CHECK-INPUT-005): Mutating POST/PUT/PATCH endpoints without schema libraries (zod, joi, yup).

Mode & Remediation: Automated. SEC-INP-004 safely wraps HTML in DOMPurify. Injection findings escalate with exact line numbers and parameterized query guidance.

API Method Restrictions & Catch-Alls

What Bilt looks for: Catch-all or wildcard HTTP method handlers (app.all(), router.all(), Next.js export async function ALL()).
Evidence analyzed: AST route declaration scanning across all API files.
Why it matters: Catch-all matchers accept unexpected HTTP methods (TRACE, HEAD, SEARCH) that can bypass method-specific middleware and trigger unintended code execution.
Mode & Remediation: Automated. bilt fix safely restricts wildcard handlers to explicit HTTP verbs (GET, POST).

Unsafe API Exposure & Documentation

What Bilt looks for: Interactive API documentation endpoints (Swagger UI, GraphQL Playground, OpenAPI schema specs) mounted in production builds without environment guards.
Evidence analyzed: Dependency and middleware inspection for packages like swagger-ui-express, apollo-server, and graphql-playground.
Why it matters: Publicly exposed Swagger/Playground endpoints assist external attackers with automated endpoint enumeration and schema reconnaissance.
Mode & Remediation: Automated. bilt fix wraps doc routes in if (process.env.NODE_ENV !== 'production') conditions.

Sensitive Response Data Exposure

What Bilt looks for: API handlers serializing database entities directly into HTTP responses where attributes contain sensitive fields (passwordHash, secretKey, apiToken, ssn).
Evidence analyzed: AST property inspection of response objects and OpenAPI response schemas.
Why it matters: Leaking password hashes or internal secret keys compromises user credentials and violates privacy regulations even when network transit is encrypted.
Mode & Remediation: Automated (Critical severity). Guided remediation: use explicit response DTOs or Prisma select / omit clauses.

Database Security & Client Driver Leakage

What Bilt looks for: Direct backend database driver imports (@prisma/client, pg, mysql2, mongoose, drizzle-orm) inside client components; database connection strings lacking TLS/SSL enforcement (sslmode=require); multi-step mutations without database transactions.
Evidence analyzed: File-path import boundaries, database connection URL query strings, and state mutation AST patterns.
Why it matters: Bundling database drivers into client-side code exposes database schemas and connection credentials to browsers. Unencrypted connections risk network interception. Non-transactional mutations allow race-condition tampering.
Mode & Remediation: Automated for driver imports and SSL strings; Guided for backup/PITR procedures.

Unsafe File Uploads

What Bilt looks for: File upload handlers (multer, formidable, uploadthing, S3 clients) lacking file size caps, MIME allowlist verification, or path traversal safeguards.
Evidence analyzed: Multipart file upload libraries and filesystem storage paths.
Why it matters: Unrestricted uploads allow remote code execution via executable scripts (.php, .exe, .html), storage exhaustion (DoS), or server file overwrites.
Mode & Remediation: Guided (needs-review). Enforce strict MIME allowlists, a 5MB size ceiling, and isolated cloud object storage.

Dependency Integrity & Lockfiles

What Bilt looks for: Repositories missing package lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock); Dockerfiles copying .env files or running as root; Terraform configurations without .gitignore for .tfvars.
Evidence analyzed: File existence, package manifests, Dockerfile instructions, and Infrastructure-as-Code files.
Why it matters: Deploying without lockfiles results in non-deterministic builds where compromised upstream packages can enter production without detection.
Mode & Remediation: Automated. Auto-generates .dockerignore, removes COPY .env from Dockerfiles, and adds .gitignore entries.

Insecure Transport & Security Headers

What Bilt looks for: Wildcard CORS origin (* or true) configured with credentials: true; disabled TLS verification (rejectUnauthorized: false); cookies missing httpOnly, secure, or sameSite; Express/Fastify apps running without helmet.
Evidence analyzed: CORS options, HTTPS agent settings, res.cookie() options, and middleware stacks.
Why it matters: Wildcard CORS with credentials allows third-party sites to steal authenticated user data. Insecure cookies allow XSS credential theft. Missing TLS verification permits man-in-the-middle attacks.
Mode & Remediation: Automated. SEC-STO-002 adds secure cookie flags. SEC-NET-001 removes rejectUnauthorized: false. SEC-CFG-002 mounts Helmet.

Deployment & Container Misconfiguration

What Bilt looks for: Browser source maps enabled for production builds (productionBrowserSourceMaps: true in next.config.js); production Docker containers running with ENV NODE_ENV=development.
Evidence analyzed: Framework configuration exports and Dockerfile environment instructions.
Why it matters: Production source maps reveal unminified original source code, internal logic, and comments to anyone in browser DevTools. Development mode disables performance optimizations and exposes verbose debug traces.
Mode & Remediation: Automated. bilt fix --safe toggles productionBrowserSourceMaps to false and sets NODE_ENV=production.

Error Stacks & Credential Log Leaks

What Bilt looks for: Raw stack traces returned in HTTP responses (res.json(err.stack), NextResponse.json({ error: err.stack })); sensitive credentials, tokens, or passwords printed to stdout via console.log().
Evidence analyzed: AST matching of response serialization arguments and console call expressions.
Why it matters: Stack traces leak internal filesystem paths, dependencies, and database schemas. Plaintext credential logging stores secrets in central log aggregators.
Mode & Remediation: Automated. SEC-CFG-001 sanitizes API error response structures.

Privacy & PII Handling

What Bilt looks for: Government identifiers (SSN, national ID, passport), birthdates, or driver's licenses stored in schema models without field-level encryption, access auditing, or account deletion flows.
Evidence analyzed: Schema and data model attribute inspection for PII naming tokens.
Why it matters: PII exposure violates GDPR/CCPA regulations and risks identity theft.
Mode & Remediation: Guided (needs-review, evidence required).

Payments & Webhook Signatures

What Bilt looks for: Payment webhook handlers (Stripe, PayPal, Razorpay) lacking cryptographic signature verification (stripe.webhooks.constructEvent); backend handling of raw credit card fields (cardNumber, cvv, cardExp).
Evidence analyzed: Webhook handler routes, signature verification calls, and card attribute identifiers.
Why it matters: Unverified webhooks allow attackers to simulate checkout completions and claim goods without paying. Handling raw card numbers violates PCI-DSS.
Mode & Remediation: Guided for webhook verification; Automated for raw credit card fields (fail).

Abuse, Cloud Cost & Resource Exhaustion

What Bilt looks for: Paid AI or external APIs (OpenAI, Anthropic, Replicate, ElevenLabs, Twilio, SendGrid) invoked from API routes without authentication or rate limiting (@upstash/ratelimit, express-rate-limit); absence of global rate limiting on public API suites.
Evidence analyzed: Cross-referencing third-party SDK calls against route authentication middleware and rate limiter decorators.
Why it matters: Un-throttled paid endpoints allow attackers to flood APIs, exhausting account balances within minutes and generating huge cloud bills (Denial of Wallet).
Mode & Remediation: Guided (needs-review, mandatory category).

AI Integrations & LLM Output Execution

What Bilt looks for: Dynamic execution of untrusted AI model outputs (eval(completion), exec(), new Function()); unrestricted AI agent tool execution; system prompt concatenation with untrusted user input without structural boundary separation or secrets embedded in prompts.
Evidence analyzed: AST tracing of LLM completion variables into dynamic execution sinks.
Why it matters: Prompt injection attacks can manipulate the LLM into generating malicious code that the server executes, granting attackers remote code execution (RCE).
Mode & Remediation: Automated (Critical severity). Guided refactoring: parse model outputs as structured JSON validated against strict Zod schemas.

4. Bilt's Internal Security Engineering

Because Bilt evaluates untrusted code generated by autonomous AI agents, the security engine itself implements defense-in-depth protections:

5. Safe Remediation & Escalation

When an automated fix is safe, Bilt repairs it without guessing. When automated remediation cannot safely make progress, Bilt breaks the cycle and escalates:

• Atomic Snapshots & Instant Rollback: Every bilt fix run records a complete file snapshot in .bilt/snapshots/ before writing changes. Running bilt undo instantly rolls back the entire transaction in sub-2ms.
• Loop Termination Guarantee (Exit Code 4): Tracked iteration state in .bilt/loop-state.json halts execution with status: "escalate" (exit code 4) if an AI agent repeats identical findings across 3 consecutive iterations, enters oscillation thrashing ($A \rightarrow B \rightarrow A \rightarrow B$), or exceeds its maximum iteration budget (default: 15).

# 1. Evaluate your repository against the complete security taxonomy
npx bilt check

# 2. Run static security and secret analysis
npx bilt scan

# 3. Inspect API routes for mass assignment, method allowlists, and schema leaks
npx bilt api-scan

# 4. Strict PR diff verification with anti-tamper and loop protection in CI
npx bilt verify --base origin/main --format agent

# 5. Apply safe automated security remediations
npx bilt fix --safe

# 6. Instant atomic rollback if needed
npx bilt undo

The production readiness guide covers how to execute comprehensive repository evaluations before launching applications to production users.

The Main Gate: bilt check

bilt check evaluates your project against the 14-category readiness taxonomy. It separates deterministic static checks from guided human reviews:

# Run full check
npx bilt check

# Run on specific directory
npx bilt check ./services/api

# Scope to specific categories
npx bilt check --categories secrets-and-env,auth,authorization

Diff Verification: bilt verify

Designed specifically for pull requests and CI pipelines, bilt verify evaluates only the changes introduced in the current git branch against the base ref:

npx bilt verify --base origin/main --format agent

Automated Remediation & Undo

Safe automated fixes can be applied with bilt fix --safe. To reverse any automated changes:

# Apply safe fixes
npx bilt fix --safe

# Revert the last fix transaction
npx bilt undo

AI coding agents are extremely good at producing interfaces that are technically functional but visually interchangeable. Bilt helps developer teams and AI coding agents build intentional frontend interfaces that reflect specific product logic rather than generic SaaS template conventions.

The Problem: Generic UI

When building user interfaces, agents often converge on the exact same set of visual choices:

• purple/blue gradients
• giant centered hero sections
• bento cards
• excessive rounded corners
• sparkle icons
• radial gradient orbs
• fake terminal windows
• glassmorphism
• generic SaaS copy
• decorative animations
• fake testimonials
• placeholder dashboards
• excessive cards
• missing loading/error/empty states

These patterns are not inherently bad. The problem is the accumulation of recognizable patterns without product-specific reasoning.

Beyond the Purple Gradient

1. The common pattern

A familiar AI/SaaS visual language

The palette itself is not bad. The issue is the combination:

When many of these appear together, the result feels interchangeable.

2. Intentional alternatives

State clearly: these are examples, not recommendations.

3. Philosophy callout (most important concept)

One pattern is not a problem.

But:

Design Check looks for combinations, repetition, and context — not individual design decisions.

4. Make the palette belong to the product

A strong color system usually comes from the product itself (domain, existing brand, audience, real data, interaction states, etc.).

5. Bilt does not prescribe palettes

These examples must not become a new generic “Bilt look.” Bilt should never replace one template with another.

6. Optional Design Brief

Developers can optionally run:

bilt design-brief

and give the agent direction (product type, visual feeling, brand colors, or simply “Surprise me”). If no preference is given, Bilt must not invent one.

7. How Design Check uses the information

If a clear preference was given and the implementation objectively contradicts it, Bilt can surface an advisory finding. Subjective taste differences stay advisory and must not create endless agent loops.

8. Concrete example

Developer: “Use a warm orange as the primary brand color.”

Implementation: Primary UI is blue/purple; orange only appears on a tiny icon.

DESIGN-BRIEF-001
Potential mismatch with developer preference.
Requested: Warm orange as primary brand color.
Observed: Primary interface uses blue/purple.
Review whether this was intentional.

This is evidence-based, not an aesthetic judgment.

9. Don't overthink it

You don't need a full design system. A short instruction is enough:

• “Make it feel editorial and cinematic.”
• “Use our existing orange brand color.”
• “Surprise me. Make it distinctive.”

10. Closing takeaway

Running Design Check

Run design checks across your repository using the CLI:

bilt design-check
bilt design-check .
bilt design-check --format agent

bilt check can include design-readiness findings as part of the broader production-readiness workflow.

What Bilt Checks

Example Finding

A realistic finding emitted by Bilt during a design check:

DESIGN-GENERIC-001

High concentration of recognizable SaaS template patterns

Evidence:
- purple/blue gradients
- radial background orbs
- repeated three-column cards
- sparkle icons
- excessive rounded containers

Why:
Individually these patterns are normal. Combined, they create a
highly recognizable template-driven visual language.

Recommendation:
Replace some decorative patterns with visuals derived from the
actual product, workflow, data, or domain.

Agent Workflow

AI agent builds UI
        ↓
Bilt design-check
        ↓
Findings + evidence
        ↓
Agent improves implementation
        ↓
Bilt runs again

Bilt can detect repeated iterations with the same fingerprint set and escalate instead of allowing an agent to endlessly make random changes. This is designed to prevent token exhaustion and destructive “keep changing things until something works” loops.

Agent Mode (--format agent)

bilt design-check --format agent outputs machine-readable output intended for Claude Code, Codex, Cursor, ChatGPT agents, and other coding agents.

Important Limitations

Before You Ship Checklist

• Does the UI actually represent the product?
• Are decorative elements serving a purpose?
• Are there real product states?
• Are loading/error/empty states handled?
• Are interactions accessible?
• Is the visual language specific to this product?
• Are we stacking recognizable template-driven patterns?
• Did the agent run bilt design-check?
• Did the final design change meaningfully after findings?

Whether you are vibecoding a new app or hardening an existing codebase, you can configure your AI coding agent (Claude Code, Cursor, Windsurf, Codex, Devin, ChatGPT, or Antigravity) to install Bilt and enforce production-readiness verification with a single prompt.

1. The Setup Prompt

Copy and paste this exact prompt into your AI assistant or agent chat window:

2. Step-by-Step Breakdown

When given this prompt, the AI assistant executes six distinct steps to lock in production readiness:

1. Installs bilt-toolkit as a development dependency (npm install -D bilt-toolkit) so the CLI is immediately available in the workspace.
2. Initializes Bilt & Baselines Legacy Debt by running npx bilt init and npx bilt baseline create to snapshot existing debt into .bilt/baseline.json.
3. Configures Agent Guidelines via npx bilt prompt, appending instructions to AGENTS.md (and .cursorrules / .windsurfrules if present).
4. Adds helper npm scripts to package.json:
   package.json

   Copy

   {
     "scripts": {
       "bilt": "bilt scan",
       "check:readiness": "bilt check"
     }
   }

5. Enforces Autonomous Remediation Protocol as a mandatory gate before declaring any task complete (running npx bilt design-check --fix && npx bilt fix --safe, checking machine verification with --format agent, and handling nextAction / exit code 4 loop escalation).
6. Reports Concise Summary detailing auto-fixed items, manually remediated findings, and any NEEDS REVIEW items requiring human decision with concrete evidence.

3. Supported AI Agents

This prompt works out of the box with:

AI coding agents (such as Claude Code, Cursor, Codex, Devin, and Antigravity) use Bilt Toolkit as an automated, deterministic security and production-readiness gate.

Because agents often introduce hardcoded API keys, unvalidated endpoints, or missing authorization checks—and can easily get stuck in repair loops or cheat by disabling checks—Bilt provides dedicated agent contracts designed specifically for agentic workflows:

1. The Agent Lifecycle with Bilt

Figure 1: The Agent Lifecycle with Bilt verification loop and deterministic exit codes.

2. Primary Integration Interfaces

A. Structured JSON Contract (--format agent)

Standard CLI tools output colorful ASCII tables that LLMs struggle to parse reliably. With --format agent, Bilt outputs machine-readable JSON validated against a schema:

{
  "schemaVersion": 1,
  "toolVersion": "1.1.0",
  "status": "fail",
  "summary": { "critical": 1, "high": 0, "needsReview": 0 },
  "findings": [
    {
      "ruleId": "RULE-SEC-001",
      "category": "secrets-and-env",
      "severity": "critical",
      "title": "Hardcoded Stripe Secret Key Detected",
      "whyItMatters": "Exposing live API keys in code risks credential theft and unauthorized billing.",
      "agentAction": "Remove key from src/billing.ts. Read from process.env.STRIPE_SECRET_KEY and update .env.example.",
      "introduced_by_change": true,
      "fixable": false,
      "fingerprint": "a3f81c9..."
    }
  ]
}

Key agent-specific fields:

• introduced_by_change: true: Tells the agent only to fix code it just wrote, preventing it from spiraling into legacy repository refactors.
• agentAction: Explicit, unambiguous instructions describing exactly how to remedy the violation.
• fingerprint: A stable identifier allowing agents to track whether a specific issue was resolved across iterations.

B. Deterministic Exit Code Contract

Agents act directly on process return codes:

C. Native MCP (Model Context Protocol) Server

For IDE agents like Cursor, Claude Desktop, and Antigravity, Bilt runs as an MCP tool provider:

npx bilt mcp

This exposes native tool calls directly to the model:

• bilt_scan: Run incremental or full codebase scans.
• bilt_check: Verify the 14-category production readiness taxonomy.
• bilt_verify: Verify working branch diff against origin/main.
• bilt_fix: Safely apply automated remediations.

3. Loop Escalation & Anti-Tamper Protections

Bilt includes guardrails built specifically to prevent common autonomous agent failure modes:

1. Anti-Tampering & Evasion Detection:

   When agents encounter stubborn test failures, they often try to “cheat” by adding blanket ignores (// bilt-ignore), loosening regexes, or modifying .biltrc.json. Bilt's tamper engine detects configuration regressions and flags them with an unsuppressible hard failure.

2. Infinite Loop Prevention (Exit Code 4):

   If an agent attempts multiple edits that produce the exact same fingerprint set without progress, Bilt flags status escalate (exit code 4). The agent system prompt instructs it to halt immediately, preventing token exhaustion and destructive edits.

3. Domain Knowledge On Demand:

   If an agent doesn't understand a concept like IDOR or rate limiting, it runs:

   Terminal

   Copy

   npx bilt explain authorization

   Bilt returns actionable architecture guidelines showing what secure implementation patterns look like for that specific stack.

4. How to Configure an Agent to Use Bilt

• Automatic (AGENTS.md): The root AGENTS.md is auto-discovered by agentic tools.
• System Prompt Export: Run npx bilt prompt to print instructions ready to embed in .cursorrules, .windsurfrules, or Claude system prompts:
  Terminal

  Copy

  npx bilt prompt >> .cursorrules

Bilt classifies all repository checks into 14 distinct categories across deterministic verification and guided engineering reviews.

The 6 Mandatory Invariant Categories

A project cannot receive production-ready status until all 6 are passed. Risk acceptance cannot be used to bypass these 6 categories:

The 8 Secondary Categories

7. dependencies • 8. error-handling-logs • 9. transport-and-headers • 10. deploy-config • 11. file-uploads • 12. payments • 13. privacy-and-pii • 14. monitoring-rollback.

The Non-Negotiable Lock

Bilt maintains a clear, uncompromising distinction between false positive suppressions and formal operational risk acceptance.

Suppressions vs. Risk Acceptance

• Inline Suppression (// bilt-ignore): Used strictly when a static rule triggers on a verified false positive. Must include a rationale comment.
• Risk Acceptance (bilt accept-risk): Used when the finding is correct, but your organization consciously accepts the operational risk to ship.

Recording Accepted Risk

Record an accepted risk via CLI with required owner and justification:

bilt accept-risk rule-dep-audit-09 \
  --category dependencies \
  --reason "Worker runs in isolated private subnet" \
  --owner "secops@company.internal" \
  --expires 2026-12-31

.bilt/risk-acceptance.json Format

All accepted risks are persisted in an immutable audit ledger:

{
  "acceptedRisks": [
    {
      "ruleId": "rule-dep-audit-09",
      "category": "dependencies",
      "reason": "Worker runs in isolated private subnet",
      "owner": "secops@company.internal",
      "acceptedAt": "2026-09-01T08:00:00Z",
      "expires": "2026-12-31T00:00:00Z"
    }
  ]
}

Once an accepted risk passes its expiration date, Bilt automatically re-activates the finding as a blocking gate failure.

Bilt provides 18 commands covering gate evaluation, static analysis, atomic rollback remediation, background daemons, and developer governance.

18 Commands Matrix

Global Flags

• --format <text|json|sarif|agent|markdown>: Output format
• --json: Shorthand for --format json
• --verbose: Show detailed rule execution logs
• --quiet: Suppress banner output; show only errors and findings
• --timeout <ms>: Rule execution timeout (default: 30000ms)
• --dry-run: Simulate modifications without writing to disk
• --color / --no-color: Force enable or disable ANSI terminal colors

The bilt-toolkit package provides complete programmatic access for CI tools and build systems.

Installation

npm install bilt-toolkit

Programmatic Verification

import { checkReadiness, verifyDiff } from 'bilt-toolkit';

// 1. Run full readiness check
const result = await checkReadiness({
  targetDirectory: './src',
  format: 'agent',
});

if (result.status === 'fail') {
  console.error('Readiness gate failed:', result.summary);
  process.exit(1);
}

// 2. Run diff verification against main branch
const diffResult = await verifyDiff({
  baseRef: 'origin/main',
  maxIterations: 5,
});

console.log('Diff gate result:', diffResult.status);

Bilt implements the Model Context Protocol (MCP) over standard I/O, allowing coding agents in Cursor, Claude Desktop, and Windsurf to call readiness verification tools natively.

Overview

To start the local MCP server manually:

npx bilt mcp

Claude Desktop Config

Add Bilt to your claude_desktop_config.json:

{
  "mcpServers": {
    "bilt": {
      "command": "npx",
      "args": ["-y", "bilt-toolkit", "mcp"]
    }
  }
}

Cursor MCP Config

In Cursor settings, navigate to Features > MCP Servers > Add New MCP Server:

• Name: bilt
• Type: command
• Command: npx -y bilt-toolkit mcp

All notable changes to the Bilt Toolkit project are documented here. Bilt follows Semantic Versioning.