prompt-scrub

Built by the Nano Collective — a community collective building AI tooling not for profit, but for the community.

prompt-scrub is a local-first utility designed to strip identifying content out of prompts and messages before they hit any cloud LLM.

It maps sensitive data (emails, secrets, paths, URLs, phone numbers) to stable placeholders locally, allowing you to rehydrate the model's responses back to their original forms securely.

What it is / What it is not

prompt-scrub reduces identity leakage at the content layer. It is partial defence, not anonymity.

What it does:

• Detects and replaces common identifying content (emails, paths, phone numbers, secrets, URLs) before your prompt leaves your machine.
• Maps each value to a stable placeholder so the model's response can be rehydrated locally.
• Gives you an inspect command so you can see exactly what was detected and what was missed before you commit to sending.

What it does not do:

• It does not make you anonymous. A semantically identifying question (a niche bug only you have, your private codebase, your financial situation) remains identifying after scrubbing.
• It does not address stylistic fingerprinting — the way you phrase things goes out unchanged.
• It does not operate at the network or key layer. Your IP address, request timing, and headers are outside its scope.
• Detectors can and do miss things. Always review the output before sending.

Important

A user who believes this tool makes them anonymous is worse off than one who never used it — they stop reading their prompts and trust the defaults. Always use inspect first to see what the tool actually found.

Read the full Threat Model for a complete breakdown of what is and is not defended.

Quick Start

Install globally to use the CLI:

npm install -g @nanocollective/prompt-scrub

Or install as a dependency in your Node.js project:

npm install @nanocollective/prompt-scrub

Recommended: Inspect first

Before scrubbing, run inspect on a real prompt to review what the tool detected before sending your prompt:

echo "My email is alice@acme.com and I work at /Users/alice/projects. My phone is +44-7700-900999." \
  | prompt-scrub inspect

Detected entities:
  [Email]    alice@acme.com                   → Email_1    (chars 12-26)
  [Path]     /Users/alice/projects.           → Path_1     (chars 41-63)
  [Phone]    +44-7700-900999                  → Phone_1    (chars 76-91)

No session written.
Hash: 41beda4af0b83488fdf6eea9347775450a1c7c887a6ef377212340f36c445132

The hash is deterministic — the same prompt always produces the same hash, so you can verify cache stability across runs. Once you are satisfied with what inspect shows, proceed with scrub.

Usage Examples

CLI: Scrubbing text

echo "My email is user@example.com" | prompt-scrub scrub
# stdout: My email is Email_1
# stderr: Session ID: 6f1c2b90-...
# stderr: Scrubbed: 1 entity (1 Email)   — pass -q/--quiet to suppress the summary

CLI: Watch clipboard

# Monitor clipboard and automatically scrub sensitive data
prompt-scrub watch --clipboard

# Watch a file
prompt-scrub watch --file prompt.txt --once

# Preview changes without writing anything
prompt-scrub watch --file prompt.txt --dry-run --once

See the CLI Reference for all watch options and platform requirements.

Node.js API: Scrubbing and Rehydrating

import { scrub, rehydrate } from '@nanocollective/prompt-scrub';

const prompt = "My key is sk-12345";
const { scrubbedContent, sessionId } = scrub({ content: prompt });
console.log(scrubbedContent); // "My key is Secret_1"

// ... send to LLM ... get response "I see your key is Secret_1"

const { content } = rehydrate({ 
  content: "I see your key is Secret_1", 
  sessionId 
});
console.log(content); // "I see your key is sk-12345"

Configuration

prompt-scrub reads an optional config file for extra rule packs and URL allowlisting. Create one pre-filled with the default schema:

prompt-scrub init
# Created config file at /home/alice/.config/prompt-scrub/config.json

Print the configuration that is actually active — JSON on stdout, the path it came from on stderr:

prompt-scrub config show

Entries that do not match the schema are reported and exit non-zero, so config show doubles as a config check in scripts. See the CLI reference for the full schema and options.

Session Management & Garbage Collection

prompt-scrub maps sensitive data to placeholders and stores these mappings in session files (by default in ~/.config/prompt-scrub/sessions/).

To protect your privacy and save disk space, session files have a Time-to-Live (TTL). By default, sessions that are older than 7 days are automatically deleted when you run the scrub or sessions list commands. Active sessions (ones you interact with) will naturally have their TTL reset.

You can also manually prune expired sessions:

prompt-scrub sessions gc

To configure the TTL, add sessionTtlDays to your ~/.config/prompt-scrub/config.json:

{
  "sessionTtlDays": 14
}

Documentation

Full user guides and architecture details are in the docs/ directory:

• Getting Started
• Threat Model
• Architecture

Read the full whitepaper at docs.nanocollective.org.

Community

• Discord: Join the Nano Collective Discord
• Contributing: Read our Contributing Guide to get started.
• Issues: Check the GitHub Issues for planned work or to report bugs.