bloomfilter-plugins

Bloomfilter Agent Miner plugins for Claude Code, VS Code Copilot, and Cursor. The plugins capture agent events such as sessions, prompts, tool calls, responses, and session stops, then send them to Bloomfilter for observability and analysis.

Available Plugins

Each runtime now has one cross-platform plugin that runs on Windows, macOS, Linux, and WSL from a single install. Install that one. The separate Windows plugins are deprecated and kept only so existing installs keep working — new users should not install them.

Plugin	Platform	Status	Marketplace
bloomfilter-agent-miner-claude-code	Claude Code CLI on Windows, macOS, Linux, WSL	✅ Recommended	.claude-plugin/marketplace.json
bloomfilter-agent-miner-claude-code-windows	Claude Code CLI on Windows	⚠️ Deprecated	.claude-plugin/marketplace.json
agent-miner-codex	Codex on Windows, macOS, Linux, WSL	✅ Recommended	.agents/plugins/marketplace.json
agent-miner-codex-windows	Codex on Windows	⚠️ Deprecated	.agents/plugins/marketplace.json
bloomfilter-agent-miner-cursor	Cursor on Windows, macOS, Linux, WSL	✅ Recommended	.cursor-plugin/marketplace.json
bloomfilter-agent-miner-cursor-unified	Cursor on Windows, macOS, Linux, WSL	♻️ Alias of -cursor	.cursor-plugin/marketplace.json
bloomfilter-agent-miner-cursor-windows	Cursor on Windows	⚠️ Deprecated	.cursor-plugin/marketplace.json
bloomfilter-agent-miner-copilot	VS Code Copilot and Copilot CLI on Windows, macOS, Linux, WSL	✅ Recommended	.github/plugin/marketplace.json

Setup

Do this once on each machine before installing a plugin.

Dependencies

• Python 3.13 or newer. The hook scripts use only Python standard library modules, so there are no Python packages to install.
• A Bloomfilter API key.
• Git, if you want Git branch metadata captured. The plugins still work without Git.
• The host application for the plugin you want to use:
  • Claude Code CLI for bloomfilter-agent-miner-claude-code (Windows, macOS, Linux, WSL).
  • Codex CLI or Codex desktop app for agent-miner-codex (Windows, macOS, Linux, WSL).
  • Cursor 3.2.16+ with Plugins support for bloomfilter-agent-miner-cursor (Windows, macOS, Linux, WSL).
  • VS Code 1.115+ (Copilot extension), or the GitHub Copilot CLI, for bloomfilter-agent-miner-copilot (Windows, macOS, Linux, WSL).
• On Windows, the Claude Code and Codex plugins run their hooks through Git Bash when it is installed (falling back to PowerShell otherwise), so installing Git is recommended there. This does not apply to the Copilot plugin: VS Code and the Copilot CLI always run hooks through PowerShell on Windows, so Git Bash is never involved there.

macOS Dependencies

Check whether Python is already installed:

python3 --version || python --version

If Python is missing, install it with Homebrew:

brew install python

If you do not have Homebrew, install Python from https://www.python.org/downloads/macos/.

Check whether Git is already installed:

git --version

If Git is missing, install Apple's command line tools:

xcode-select --install

You can also install Git with Homebrew:

brew install git

Windows Dependencies

Check whether Python is already installed:

python3 --version
python --version

If either command prints Python 3.13 or newer, you are set. If Python is missing, install it with winget:

winget install Python.Python.3.13

You can also install Python from https://www.python.org/downloads/windows/. During installation, enable Add python.exe to PATH.

Check whether Git is already installed:

git --version

If Git is missing, install it with winget:

winget install Git.Git

You can also install Git from https://git-scm.com/download/win. Restart PowerShell, Cursor, VS Code, or Claude Code after installing Python or Git so the updated PATH is available.

Configure Your API Key

All Bloomfilter Agent Miner plugins share the same user-level config file. You only need to create it once per machine.

macOS

mkdir -p ~/.config/bloomfilter
cat > ~/.config/bloomfilter/config.json << 'EOF'
{
  "api_key": "YOUR_API_KEY"
}
EOF
chmod 600 ~/.config/bloomfilter/config.json

Windows

New-Item -ItemType Directory -Force "$env:APPDATA\bloomfilter"
@'
{
  "api_key": "YOUR_API_KEY"
}
'@ | Set-Content -Encoding UTF8 "$env:APPDATA\bloomfilter\config.json"

You can also provide the API key with an environment variable.

macOS:

export BLOOMFILTER_API_KEY="YOUR_API_KEY"

Windows PowerShell:

$env:BLOOMFILTER_API_KEY = "YOUR_API_KEY"

To make the Windows environment variable persistent:

[Environment]::SetEnvironmentVariable("BLOOMFILTER_API_KEY", "YOUR_API_KEY", "User")

Restart your agent application after changing persistent environment variables.

Install Plugins

Choose the plugin for the agent platform you use.

Claude Code

Install the single cross-platform plugin bloomfilter-agent-miner-claude-code — it runs on Windows, macOS, Linux, and WSL. The -windows plugin is deprecated; keep it only if you already have it installed.

Add the Bloomfilter plugin marketplace:

claude plugin marketplace add Bloomfilter-Engineering/bloomfilter-plugins

Or add it manually to your Claude Code settings:

{
  "plugins": {
    "marketplaces": ["Bloomfilter-Engineering/bloomfilter-plugins"]
  }
}

Install the plugin (same command on every OS):

claude plugin install bloomfilter-agent-miner-claude-code

Open any project in Claude Code. The plugin creates the config file automatically on first run if it does not exist, but you still need to add your API key.

Codex

Install the single cross-platform plugin agent-miner-codex — it runs on Windows, macOS, Linux, and WSL. The -windows plugin is deprecated; keep it only if you already have it installed.

Codex hooks are behind feature flags. Enable them before installing the plugin:

codex features enable codex_hooks
codex features enable plugin_hooks

These commands update ~/.codex/config.toml. You can also edit the file manually:

[features]
codex_hooks = true
plugin_hooks = true

If your config already has a [features] table, add only the two keys inside the existing table when editing manually.

Add the Bloomfilter plugin marketplace with the Codex CLI:

codex plugin marketplace add Bloomfilter-Engineering/bloomfilter-plugins

Open Codex and install Bloomfilter Agent Miner for Codex (agent-miner-codex) from the marketplace — the same plugin on every OS.

Restart Codex after enabling the feature flags or installing the plugin so hook registration is reloaded.

Note: Codex thinking text is encrypted by Codex and is not readable by this plugin.

VS Code Copilot

Bloomfilter publishes these Copilot plugins:

• bloomfilter-agent-miner-copilot — Recommended. One install covers Windows, macOS, Linux, and WSL, in both VS Code and the GitHub Copilot CLI. It adapts to whichever shell Copilot runs the hook in (PowerShell on Windows, POSIX shell on macOS / Linux / WSL).

Install bloomfilter-agent-miner-copilot.

The setup steps below are identical on every OS.

Open your VS Code settings.json and add the Bloomfilter marketplace:

"chat.plugins.marketplaces": [
  "Bloomfilter-Engineering/bloomfilter-plugins"
]

Or open Settings, search for chat.plugins.marketplaces, and add Bloomfilter-Engineering/bloomfilter-plugins as an item.

Install the plugin:

1. Open the Extensions view with Cmd+Shift+X on macOS or Ctrl+Shift+X on Windows.
2. Type @agentPlugins in the search field.
3. Find bloomfilter-agent-miner-copilot and select Install.

Open any project in VS Code with GitHub Copilot. The plugin activates automatically.

The same plugin also works in the GitHub Copilot CLI:

copilot plugin marketplace add Bloomfilter-Engineering/bloomfilter-plugins
copilot plugin install bloomfilter-agent-miner-copilot@bloomfilter-plugins

Cursor

Cursor distributes third-party plugins through Team Marketplaces, a feature available on Teams and Enterprise plans. A Cursor org admin adds the Bloomfilter marketplace once, then users install from it.

Bloomfilter publishes these Cursor plugins:

• bloomfilter-agent-miner-cursor — Recommended. Works on Windows, macOS, Linux, and Windows hosts driving a WSL/SSH/dev-container remote. It adapts to whichever shell Cursor runs the hook in (PowerShell on Windows, POSIX shell on macOS / Linux / WSL), so a single install covers both your local and remote sessions.
• bloomfilter-agent-miner-cursor-unified — an alias of bloomfilter-agent-miner-cursor with identical behavior. Retained for existing installs; new users should install bloomfilter-agent-miner-cursor.
• bloomfilter-agent-miner-cursor-windows — deprecated, Windows only. Retained for existing installs.

Install only one. Do not mix these — installing more than one captures the same events multiple times, and the deprecated per-OS -cursor-windows plugin errors when Cursor runs its hooks in the other environment (for example, over a WSL remote, where hooks run in a POSIX shell).

Admin setup:

1. Open the Cursor Dashboard.
2. Go to Settings > Plugins > Team Marketplaces > Import.
3. Paste https://github.com/Bloomfilter-Engineering/bloomfilter-plugins.
4. Confirm that Cursor finds bloomfilter-agent-miner-cursor (and the retained bloomfilter-agent-miner-cursor-unified and bloomfilter-agent-miner-cursor-windows).
5. Save the marketplace.
6. Optional but recommended: mark bloomfilter-agent-miner-cursor as required so it installs automatically for selected Team Access groups.

User setup:

• If the plugin is required by your admin, it installs automatically.
• Otherwise, open Cursor's Plugins panel, find the plugin for your operating system in the Bloomfilter team marketplace, and click Install.

For local development, or for Cursor users on Free or Pro plans, copy the plugin into Cursor's local plugin directory.

macOS:

mkdir -p ~/.cursor/plugins/local
cp -R /path/to/bloomfilter-plugins/plugins/agent-miner-cursor \
  ~/.cursor/plugins/local/agent-miner-cursor

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.cursor\plugins\local"
Copy-Item -Recurse -Force `
  "C:\path\to\bloomfilter-plugins\plugins\agent-miner-cursor" `
  "$env:USERPROFILE\.cursor\plugins\local\agent-miner-cursor"

Reload Cursor after installing or copying the plugin by running Developer: Reload Window from the Command Palette.

Verify and Debug

Start a session in your agent application, send a prompt, let the agent respond, then stop or end the session. Confirm that data appears in Bloomfilter.

Local batch files are written before upload:

• macOS and Linux: ~/.config/bloomfilter/batches/
• Windows: %APPDATA%\bloomfilter\batches\

Every plugin also appends to a shared debug.log next to that batches/ directory, tagged with the plugin that wrote each line.

If data does not appear in Bloomfilter, check that:

• Python is available from the agent application's environment. Run python3 --version or python --version to confirm.
• Your user config contains a valid api_key.
• The plugin is installed and the agent application was restarted or reloaded after installation.
• Only one plugin per runtime is installed. A deprecated -windows plugin left alongside the cross-platform one captures every event twice.

Per-runtime hook diagnostics:

• VS Code Copilot — open the Output panel and select the GitHub Copilot Chat Hooks channel. It logs the exact command run for each hook, its input and output, and any timeout or error.
• Copilot CLI — run copilot --log-level debug and look for the hook execution lines.