ad, and persists it to local storage. The architecture separates ingestion, classification, storage, and retrieval.
Architecture Decisions
- Ingestion via
copy Event: The extension listens for standard browser copy events. This captures prompts from any source: LLM interfaces, documentation, Slack, or local files.
- Content Classification: Raw clipboard data is noisy. The system runs the text against a set of heuristics to assign a content type. ClipGate implements 13 distinct types:
secret, error, url, path, json, command, sha, diff, sql, env, docker, ip, and text.
- Rationale: Prompts are unstructured natural language. They do not match structured patterns like JSON or SQL. Consequently, prompts land in the
text category. This is intentional. The text stream becomes the prompt library, isolated from code snippets, URLs, and secrets.
- Local Storage: Data persists in the browser's local storage. No network requests are made for storage. This ensures compliance with strict data residency requirements.
- Metadata Tagging via Convention: Since there is no native
prompt content type, the system relies on user-side conventions. Prefixing prompts with [prompt] or [claude] during drafting allows for precise filtering during retrieval. This convention requires no configuration and works immediately.
Implementation Workflow
The workflow integrates with the existing copy-paste loop. No new actions are required to save; retrieval is the primary interaction.
Ingestion:
When you copy a prompt, the extension captures the text. If the text matches a structured pattern, it is tagged accordingly. If not, it is stored as text with metadata including the source URL and a timestamp.
Retrieval via CLI:
For power users, a command-line interface provides scriptable access to the local store. This enables integration with shell scripts, IDEs, and automation pipelines.
Example: Querying the local prompt store.
# List recent items classified as generic text
$ pg query --category generic --limit 5
# Output:
# ID | Type | Source | Preview
# --- | ------ | --------------- | ----------------------------------
# 104 | text | claude.ai | [prompt] Analyze the diff for secu...
# 103 | text | chatgpt.com | [claude] Summarize the meeting tra...
# 102 | json | api-docs.local | {"status": "ok", "version": "2.1"}
# 101 | text | slack.com | [prompt] Rewrite this email in a p...
# 100 | secret | terminal | sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxx
Example: Searching with metadata filters.
# Search for prompts tagged with 'code-review'
$ pg grep --tag "ai-instruction" --match "code-review"
# Output:
# Found 3 matches:
# [prompt] You are a senior code reviewer. Focus on security vulns...
# [prompt] Review this diff for our codebase conventions...
# [claude] Analyze the following PR description for clarity...
Example: Injecting a prompt back into the clipboard.
# Copy item ID 104 to the system clipboard
$ pg inject --id 104 --target clipboard
# Output:
# Item 104 injected to clipboard. Ready to paste.
Example: Bundling for secure sharing.
# Export a bundle of prompts as Markdown
$ pg bundle --format markdown --output stdout
# Output:
# ### Prompt Bundle
# - **ID 104**: [prompt] Analyze the diff for security...
# - Source: claude.ai
# - Date: 2023-10-27
# - **ID 101**: [prompt] Rewrite this email in a professional...
# - Source: slack.com
# - Date: 2023-10-26
Retrieval via Browser Popup:
The extension popup provides a visual interface. Users can filter by type, view previews, and click to copy. Clicking the source URL opens the original context in a new tab. This allows visual selection without leaving the browser.
Rationale for Design Choices
- Why
text classification? Structured classification prevents prompt clutter. If every copy was stored as text, the library would be polluted with code snippets and URLs. By relying on the classifier to separate json, sql, and command from text, the prompt library remains clean.
- Why prefix convention? Programmatic tagging requires configuration overhead. A text prefix is zero-config, version-control friendly, and searchable via simple string matching. It shifts the burden slightly to the user during drafting but pays dividends during retrieval.
- Why CLI and Popup? Different workflows require different interfaces. The popup supports quick, visual retrieval during active browsing. The CLI supports automation, batch operations, and integration with developer tools. Both access the same local store.
Pitfall Guide
-
The "Auto-Capture" Secret Leak
- Explanation: Auto-capture mode records every copy event. If you copy a password, API key, or private token, it is stored locally. While local storage is safer than cloud, it still increases the risk of accidental exposure if the device is compromised or shared.
- Fix: Use selective capture mode for sensitive workflows. Alternatively, configure exclusion patterns in the tool settings to ignore strings matching regex for common secret formats.
-
Context Drift Across Models
- Explanation: A prompt optimized for Claude may underperform in ChatGPT due to differences in system instructions, context window handling, or formatting preferences. Reusing a prompt without model-specific adjustments can degrade output quality.
- Fix: Use model-specific prefixes like
[claude] or [gpt]. When retrieving, filter by the target model to ensure you use the variant tuned for that interface.
-
The "Text" Trap
- Explanation: Relying solely on the
text classification without tagging makes retrieval difficult as the library grows. Searching for generic keywords may return irrelevant natural language text copied from articles or emails.
- Fix: Enforce the prefix convention. Always start prompts with
[prompt] or a custom tag. This ensures that pg grep --tag "ai-instruction" returns only relevant assets.
-
Source Attribution Loss
- Explanation: Copying from a local file or a non-browser application may not attach a source URL. This makes it harder to trace the origin of a prompt or understand the context in which it was created.
- Fix: When copying from local sources, manually add a comment or tag indicating the origin. For example:
[prompt] [local-draft] Review architecture for....
-
Sharing via Raw Copy-Paste
- Explanation: Sending a prompt to a teammate by copying raw text loses metadata like the source URL, date, and tags. The recipient receives an unstructured blob that is harder to manage.
- Fix: Use the bundling command (
pg bundle) to generate a structured Markdown block. This preserves metadata and allows the recipient to import the prompt with full context.
-
Timestamp Reliance
- Explanation: Users may rely on the timestamp to find recent prompts. However, if you copy multiple items in quick succession, the order may not reflect the logical sequence of your work.
- Fix: Use content search and tags rather than timestamps for retrieval. Timestamps are useful for auditing but unreliable for finding specific assets.
-
Ignoring the Classifier Output
- Explanation: The classifier may misidentify a prompt as
json if it contains a JSON block, or as command if it includes shell instructions. This removes the prompt from the text stream.
- Fix: Review the classification of complex prompts. If a prompt is miscategorized, manually re-tag it or adjust the prefix to ensure it lands in the correct category.
Production Bundle
Action Checklist
Decision Matrix
| Scenario | Recommended Approach | Why | Cost Impact |
|---|
| High Security/Compliance | Selective Mode + Local Only | Prevents accidental capture of secrets. Ensures data never leaves the device. | Zero (Free tool). |
| High Velocity/Research | Auto Mode + CLI | Maximizes throughput. Captures all context for later filtering. | Zero (Free tool). |
| Team Collaboration | pg bundle + Secure Channel | Structured export preserves metadata. No vendor lock-in. | Zero (Free tool). |
| Multi-Model Workflows | Model-Specific Prefixes | Ensures prompts are optimized for the target LLM. | Zero (Free tool). |
Configuration Template
For advanced users, the CLI tool supports a configuration file to customize behavior. This template defines capture rules, exclusion patterns, and default tags.
{
"capture": {
"mode": "selective",
"exclude_patterns": [
"sk-proj-[a-zA-Z0-9]+",
"ghp_[a-zA-Z0-9]+"
]
},
"classification": {
"default_type": "text",
"custom_tags": ["prompt", "claude", "gpt", "research"]
},
"retrieval": {
"default_limit": 10,
"output_format": "markdown"
},
"sharing": {
"bundle_format": "markdown",
"include_metadata": true
}
}
Quick Start Guide
- Install: Add ClipGate to Chrome/Edge/Brave. Pin the extension icon.
- Draft: Create a prompt in your notes or LLM interface. Prefix it with
[prompt].
- Capture: Select the text and press
Cmd-C (or Ctrl-C). The extension captures it silently.
- Retrieve: Click the extension icon to view the popup. Filter by
text type. Click the prompt to copy it back to the clipboard.
- Paste: Switch to your LLM tab and paste. The prompt is ready to use.
This workflow establishes a zero-trust, local-first prompt management system that scales with your usage, protects sensitive context, and integrates seamlessly into your existing development workflow.