Developer Preview

Local-first protection for AI coding assistants

Evaluate prompts, generated code, and proposed tool actions close to the developer. Keep latency-critical decisions local, then add remote analysis only where the risk justifies it.

Start setup Back to documentation

Local enforcement first

Fast decisions without making the cloud a dependency

Every supported path runs deterministic local checks first. Remote analysis can be disabled, run asynchronously, added as a second synchronous opinion, or required for a narrowly scoped workflow.

Assistant interaction

Prompt, held output, or proposed action

Local protection

Detectors, cached policy, and immediate enforcement

Optional remote analysis

Organization context and deeper checks when enabled

Three protection surfaces

The same decision model covers data leaving the workstation, content entering the repository, and actions an agent wants to execute.

Endpoint integrated

Prompt input protection

Inspect supported system prompts and message text before provider egress. High-confidence findings can warn, redact, block, or require approval.

View setup

Adapter library

Generated output scanning

Scan held code, diffs, commands, packages, and URLs before insertion. The library is ready; an editor adapter must hold and enforce the result.

View setup

Adapter library

Tool-action governance

Classify proposed shell, file, Git, deployment, credential, and infrastructure actions before execution. The adapter owns approval UI and final enforcement.

View setup

Choose latency and assurance per feature

Modes are explicit so a background classifier cannot silently become a blocking dependency. When local and remote decisions both complete synchronously, the more restrictive decision wins.

Mode	Behavior	Remote latency on path	Remote failure
`local_only`	Run local detectors and local or cached policy. The remote evaluator is never called.	No	Not applicable
`local_and_shadow`	Return the local result immediately, then run remote analysis asynchronously for comparison and telemetry.	No	Use local result
`local_then_remote`	Run local first, wait up to the configured deadline, and enforce whichever completed decision is more restrictive.	Yes	Use local result
`remote_required`	Run local first, then require a remote decision. Missing, failed, or timed-out remote analysis blocks the interaction.	Yes	Block

Source deployment guide

Set up each protection surface

The endpoint agent and editor helpers are currently private source deployments. Generated-output protection remains a reusable library that requires an adapter before content is delivered or inserted.

Use this guide for development and controlled evaluation

The public installer and editor extensions are not released. This source setup uses documented local hooks for Cursor and Claude Code, plus a documented localhost provider route for Codex.

Endpoint integrated

1. Protect prompt input at the endpoint

Build and run the local agent from this repository. It inspects supported JSON traffic before forwarding through a direct localhost provider route or the selective HTTPS proxy.

1Use macOS with Node.js 20 or newer, then install the repository dependencies.
2Use the paste-once helper below for Cursor, Codex, or Claude Code. For other proxy-aware clients, run pnpm agent:setup to create the local CA and PAC route with administrator approval.
3Start with --mode protect and local_only. Audit mode records a decision but forwards the original request.
4Confirm a [LOCAL PROTECTION] event for the exact workflow before claiming coverage. Proxy-routed clients should also show [INTERCEPT].

Terminal

pnpm install
pnpm --filter @promptective/agent build
node packages/agent/dist/index.js start \
  --mode protect \
  --input-protection local_only

Adapter library

2. Scan generated output before insertion

Call the local protection library while output is still held. Prevention claims are valid only when the adapter enforces the result before delivery or insertion.

1Create a code-assistant output interaction using the canonical protocol envelope.
2Pass the raw assistant text, target file, language hint, and delivered: false to the local engine.
3Hold critical findings; show warnings or request approval according to organization policy.
4Record hashes and finding metadata by default. Avoid retaining raw generated source unless policy explicitly allows it.

TypeScript

import { createLocalProtectionEngine } from '@promptective/local-protection';

const engine = createLocalProtectionEngine({
  modes: { generated_output: 'local_only' },
});

const result = await engine.evaluate({
  feature: 'generated_output',
  interaction: outputInteraction,
  generatedOutput: {
    text: assistantText,
    targetFile: 'src/server.ts',
    language: 'typescript',
    delivered: false,
  },
});

if (result.decision.outcome === 'block') {
  holdOutput();
}

Adapter library

3. Govern tool actions before execution

Place the local evaluator between an assistant's proposed action and the executor. The library never executes the command itself.

1Normalize the tool name, command, path, URL, and bounded arguments before any side effect occurs.
2Evaluate with feature: tool_action; local_only is the default for this latency-sensitive boundary.
3Map allow, warn, require_approval, and block to explicit adapter behavior.
4Keep the editor sandbox and native permission system enabled; this classifier is an additional control, not an OS sandbox.

TypeScript

const result = await engine.evaluate({
  feature: 'tool_action',
  interaction: actionInteraction,
  toolAction: {
    toolName: 'terminal',
    command: proposedCommand,
    path: workspacePath,
  },
});

switch (result.decision.outcome) {
  case 'allow': executeAction(); break;
  case 'warn': showWarning(); break;
  case 'require_approval': requestApproval(); break;
  case 'block': denyAction(); break;
}

Configure every execution mode

Start locally, then opt individual features into remote analysis. Remote modes send normalized interaction content to the configured control endpoint.

local_only

Recommended for prompt input and tool actions when predictable low latency and offline enforcement matter most.

Terminal

promptective-agent start --mode protect --input-protection local_only

local_and_shadow

Use to compare a remote classifier with production local decisions without adding remote latency or changing enforcement.

Required environment

export PROMPTECTIVE_API_KEY="pa_your_agent_key"
export PROMPTECTIVE_CLOUD="https://api.promptective.ai"

Terminal

promptective-agent start --mode protect --input-protection local_and_shadow

local_then_remote

Use for sensitive interactions where a deeper remote decision is worth a bounded delay. Remote failure falls back to local.

Required environment

export PROMPTECTIVE_API_KEY="pa_your_agent_key"
export PROMPTECTIVE_CLOUD="https://api.promptective.ai"

Terminal

promptective-agent start --mode protect --input-protection local_then_remote

remote_required

Reserve for workflows whose policy explicitly requires a remote control. It fails closed when that control is unavailable.

Required environment

export PROMPTECTIVE_API_KEY="pa_your_agent_key"
export PROMPTECTIVE_CLOUD="https://api.promptective.ai"

Terminal

promptective-agent start --mode protect --input-protection remote_required --remote-timeout 1500

Current editor coverage

Coverage depends on the enforcement point and an exact-version live canary: Cursor and Claude Code use local user hooks, while Codex uses a direct localhost provider route. Cursor file-read and Windows launcher caveats apply. Claude can optionally layer a provider route after a credential canary.

Cursor

Conditional

Local user hooks can block prompt submission and selected shell, MCP, file, and Tab events when Cursor emits and launches them, without rerouting provider traffic. File-read coverage is conditional: Cursor has a confirmed beforeReadFile bypass for files already open in the editor. Generated responses are not held before delivery.

Current setup: Install the fail-closed hooks and verify prompt plus action canaries on the exact Cursor version. For sensitive paths, add a Cursor-native deny such as .cursorignore and require both closed-file and open-buffer canaries; treat it as defense in depth, not a hard boundary. On Windows, require a successful Hooks-log launcher canary before claiming any coverage. Keep strict secrets outside the mounted Cursor workspace in an isolated workspace, VM, or container.

Paste this block once. It builds the agent, creates one backup, and safely merges five local hooks into ~/.cursor/hooks.json; no Promptective daemon or local CA is needed. Configuration alone does not prove enforcement: live file-read canaries are required, and Windows hook launching remains conditional on the exact shell and Cursor build.

Terminal — paste from the repository root

pnpm install
pnpm --filter @promptective/agent build
node packages/agent/dist/index.js configure-cursor

See the Cursor hooks written by the helper

~/.cursor/hooks.json

{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [{
      "command": "… cursor-hook prompt PROMPTECTIVE_CURSOR_HOOK=1",
      "timeout": 5,
      "failClosed": true
    }],
    "beforeShellExecution": [{
      "command": "… cursor-hook shell PROMPTECTIVE_CURSOR_HOOK=1",
      "timeout": 5,
      "failClosed": true
    }],
    "beforeMCPExecution": [{
      "command": "… cursor-hook mcp PROMPTECTIVE_CURSOR_HOOK=1",
      "timeout": 5,
      "failClosed": true
    }],
    "beforeReadFile": [{
      "command": "… cursor-hook file PROMPTECTIVE_CURSOR_HOOK=1",
      "timeout": 5,
      "failClosed": true
    }],
    "beforeTabFileRead": [{
      "command": "… cursor-hook tab_file PROMPTECTIVE_CURSOR_HOOK=1",
      "timeout": 5,
      "failClosed": true
    }]
  }
}

Codex

Conditional

The local engine can protect inspectable provider traffic, but a native Codex hook adapter is not yet released. Keep Codex sandboxing and approvals enabled.

Current setup: Override the built-in OpenAI provider with the localhost route, preserving Codex's provider identity and task-history partition. Disable request compression and verify a local protection event before enforcement. Keep Codex's native sandbox and approval controls enabled.

Paste this block once. It builds the agent, backs up and safely updates ~/.codex/config.toml, then leaves Promptective running in local-only audit mode. Fully quit and reopen Codex after the agent starts.

Terminal — paste from the repository root

pnpm install
pnpm --filter @promptective/agent build
node packages/agent/dist/index.js configure-codex
node packages/agent/dist/index.js start --mode audit --input-protection local_only

See the Codex settings written by the helper

~/.codex/config.toml

model_provider = "openai"
openai_base_url = "http://127.0.0.1:9888"

[features]
enable_request_compression = false

Claude Code

Conditional

UserPromptSubmit and PreToolUse hooks locally block unsafe prompts and gate shell, file, MCP, and other tool actions. They preserve Claude's normal authentication and native permission flow; generated output is not held.

Current setup: Install the user hooks and open a new Claude Code session; no daemon or local CA is required. The optional --provider-route is limited to direct Anthropic credentials and refuses to redirect an existing gateway.

Paste this block once. It builds the agent, creates one backup, and safely merges local prompt and pre-tool hooks into ~/.claude/settings.json without changing authentication. The hooks run the local detector directly.

Terminal — paste from the repository root

pnpm install
pnpm --filter @promptective/agent build
node packages/agent/dist/index.js configure-claude

See the Claude Code hooks written by the helper

~/.claude/settings.json

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "/absolute/path/to/node",
        "args": [
          "/absolute/path/to/promptective/packages/agent/dist/index.js",
          "claude-hook",
          "prompt",
          "PROMPTECTIVE_CLAUDE_HOOK=1"
        ],
        "timeout": 5
      }]
    }],
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/absolute/path/to/node",
        "args": [
          "/absolute/path/to/promptective/packages/agent/dist/index.js",
          "claude-hook",
          "tool",
          "PROMPTECTIVE_CLAUDE_HOOK=1"
        ],
        "timeout": 5
      }]
    }]
  }
}

Security and compatibility boundaries

A precise coverage statement is part of the security control. These constraints should remain visible during every evaluation and rollout.

Pinned TLS, QUIC, proprietary protocols, proxy bypasses, and non-proxy-aware clients are outside the current endpoint boundary.
Codex protects inspectable prompt requests. Cursor and Claude hooks gate only selected emitted context or tool events; Cursor's beforeReadFile can be bypassed by an already-open editor buffer. Generated-output prevention still requires a pre-delivery product adapter.
Local checks are narrow, deterministic rules—not comprehensive PII discovery, full SAST, malware analysis, or package reputation.
String message content can be redacted. Structured content fails closed when an exact safe rewrite cannot be mapped back to the provider payload.
Remote modes transmit normalized content to the configured control endpoint. Apply data residency, retention, and access policy before enabling them.

Evaluate the local-first path with your real workflow

Start in local-only mode, verify exact coverage, then introduce shadow or synchronous remote analysis one feature at a time.

Create a workspace Browse all documentation