npm package: @mantra-hq/privacy-hook
Description: Privacy protection hook for AI coding tools - Claude Code, etc.
Author: Mantra Team
Latest version: 0.1.5

# @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

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

## Usage

### Install Hook to Claude Code

```bash
mantra-privacy-hook install
```

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

### Check Status

```bash
mantra-privacy-hook status
```

Shows:
- Hook installation status
- Mantra client connection status
- API endpoint configuration

### Uninstall Hook

```bash
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

```typescript
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

```typescript
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