@mantra-hq/privacy-hook

Privacy protection hook for AI coding tools - integrates with Mantra client for real-time sensitive information detection.

Overview

This package provides a hook that integrates with AI coding tools (like Claude Code) to detect and block sensitive information before it's sent to AI services. The hook communicates with the Mantra client running locally to perform privacy checks.

Architecture

┌─────────────────┐     HTTP POST      ┌──────────────────────┐
│  Claude Code    │ ───────────────▶   │   Mantra Client      │
│  Hook (thin)    │  /api/privacy/check │  ┌────────────────┐  │
│                 │                    │  │ Detection      │  │
│  - Intercept    │ ◀───────────────   │  │ Engine         │  │
│    prompt       │   {allow/block}    │  │ Rules Manager  │  │
│  - Forward to   │                    │  │ Records        │  │
│    client       │                    │  └────────────────┘  │
└─────────────────┘                    └──────────────────────┘

Installation

npm install -g @mantra-hq/privacy-hook
# or
pnpm add -g @mantra-hq/privacy-hook

Usage

Install Hook to Claude Code

mantra-privacy-hook install

This will register the hook in ~/.claude/settings.json to intercept prompts before they're sent.

Check Status

mantra-privacy-hook status

Shows:

• Hook installation status
• Mantra client connection status
• API endpoint configuration

Uninstall Hook

mantra-privacy-hook uninstall

Removes the hook from Claude Code settings.

How It Works

1. Claude Code Hook Trigger: When you submit a prompt in Claude Code, the UserPromptSubmit hook is triggered.

2. Privacy Check: The hook sends your prompt to the Mantra client's local API (http://127.0.0.1:19836/api/privacy/check).

3. Detection: The Mantra client scans the prompt using its privacy detection engine.

4. Response:

   • If no sensitive information is found: exit 0 (allow)
   • If sensitive information is detected: exit 2 (block) + warning message

5. Client Offline Handling: If the Mantra client is not running, the hook shows a warning and allows the prompt to proceed.

Configuration

The hook reads the Mantra client's port configuration from the settings file:

• macOS: ~/Library/Application Support/com.gonewx.mantra/settings.yaml
• Linux: ~/.local/share/com.gonewx.mantra/settings.yaml
• Windows: %APPDATA%\com.gonewx.mantra\settings.yaml

Default port: 19836

You can change the port in the Mantra client's Settings page.

API Reference

Types

interface PrivacyCheckRequest {
  prompt: string;
  context?: {
    tool: string;
    timestamp?: string;
  };
}

interface PrivacyCheckResponse {
  action: "allow" | "block";
  matches?: MatchInfo[];
  message?: string;
}

interface MatchInfo {
  rule_id: string;
  severity: string;
  preview: string;
}

Programmatic Usage

import {
  checkPrivacy,
  checkClientRunning,
  registerHook,
  unregisterHook,
} from "@mantra-hq/privacy-hook";

// Check if Mantra client is running
const isRunning = await checkClientRunning();

// Perform privacy check
const result = await checkPrivacy("Your text to check");
if (result?.action === "block") {
  console.log("Sensitive information detected:", result.matches);
}

// Register/unregister hook programmatically
registerHook();
unregisterHook();

Requirements

• Node.js >= 18.0.0
• Mantra client installed and running for privacy protection

License

MIT