bouncer-feed-filter

# Bouncer Feed Filter > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. Bouncer is a browser extension (Chrome/Edge/iOS) that uses AI to filter unwanted posts from Twitter/X feeds in real time. Users define filters in plain language ("crypto", "engagement bait", "rage politics"), and Bouncer classifies and hides matching posts using AI models — local (WebGPU via WebLLM) or cloud (OpenAI, Gemini, Anthropic, OpenRouter, Imbue). ## Repository Structure ``` Bouncer/ # Main extension source src/ background/ # Service worker / background scripts content/ # Content scripts (Twitter DOM interaction) popup/ # Extension popup UI adapters/ # Site adapters (Twitter/X) models/ # AI backend integrations utils/ # Shared utilities icons/ # Extension icons manifest.json # Chrome extension manifest package.json tsconfig.json ``` ## Installation & Build ### From Source (Chrome/Edge) ```bash git clone https://github.com/imbue-ai/bouncer.git cd bouncer/Bouncer npm install npm run build ``` Load in Chrome: 1. Go to `chrome://extensions` 2. Enable **Developer mode** 3. Click **Load unpacked** → select `Bouncer/` folder 4. Navigate to `twitter.com` or `x.com` ### Development Build (watch mode) ```bash cd Bouncer npm run dev # watch mode with hot rebuild ``` ### Production Build ```bash npm run build # outputs to Bouncer/dist or inline ``` ## AI Backend Configuration Bouncer supports multiple providers. Configure via the extension popup Settings panel. ### Provider / Model Matrix | Provider | Model IDs | Auth | |----------|-----------|------| | Local WebGPU | `Qwen3-4B`, `Qwen3.5-4B`, `Qwen3.5-4B Vision` | None | | OpenAI | `GPT-5 Nano`, `gpt-oss-20b` | API key | | Google Gemini | `2.5 Flash Lite`, `2.5 Flash`, `3 Flash Preview` | API key | | Anthropic | `Claude Haiku 4.5` | API key | | OpenRouter | `Nemotron Nano 12B VL`, `Ministral 3B` | Account token | | Imbue | Default | None (built-in) | API keys are stored in Chrome's `chrome.storage.local` — never hardcoded. ## Core Architecture ### 1. MutationObserver — Content Script The content script watches the Twitter feed for new posts: ```typescript // src/content/feedObserver.ts const observer = new MutationObserver((mutations) => { for (const mutation of mutations) { for (const node of mutation.addedNodes) { if (node instanceof HTMLElement) { const post = extractPost(node); if (post) classifyAndFilter(post); } } } }); observer.observe(document.body, { childList: true, subtree: true }); ``` ### 2. Post Extraction — Twitter Adapter ```typescript // src/adapters/twitter.ts export interface ExtractedPost { id: string; text: string; authorHandle: string; imageUrls: string[]; element: HTMLElement; } export function extractPost(element: HTMLElement): ExtractedPost | null { const article = element.querySelector('article[data-testid="tweet"]'); if (!article) return null; const tweetText = article.querySelector('[data-testid="tweetText"]')?.textContent ?? ''; const handle = article.querySelector('[data-testid="User-Name"] a')?.getAttribute('href') ?? ''; const images = [...article.querySelectorAll('img[src*="pbs.twimg.com/media"]')] .map(img => (img as HTMLImageElement).src); return { id: article.closest('[data-testid]')?.getAttribute('data-testid') ?? crypto.randomUUID(), text: tweetText, authorHandle: handle.replace('/', ''), imageUrls: images, element: article as HTMLElement, }; } ``` ### 3. Classification Request ```typescript // src/models/classify.ts export interface ClassificationResult { filtered: boolean; matchedCategory: string | null; reasoning: string; } export async function classifyPost( post: ExtractedPost, filters: string[], model: ModelConfig ): Promise<ClassificationResult> { const prompt = buildClassificationPrompt(post.text, filters, post.imageUrls); const response = await model.provider.complete(prompt); return parseClassificationResponse(response); } function buildClassificationPrompt( text: string, filters: string[], imageUrls: string[] ): string { return `You are a content filter. Given a social media post, determine if it matches any of the user's filter categories. Filter categories: ${filters.map(f => `"${f}"`).join(', ')} Post text: ${text} ${imageUrls.length > 0 ? `The post contains ${imageUrls.length} image(s).` : ''} Respond with JSON: { "filtered": boolean, "matchedCategory": "category name or null", "reasoning": "brief explanation" }`; } ``` ### 4. Hiding Filtered Posts ```typescript // src/content/filterUI.ts export function hidePost(element: HTMLElement, reason: string): void { element.style.transition = 'opacity 0.3s ease-out'; element.style.opacity = '0'; setTimeout(() => { element.style.display = 'none'; element.dataset.bouncerFiltered = 'true'; element.dataset.bouncerReason = reason; }, 300); } export function showFilteredIndicator(count: number): void { const indicator = document.getElementById('bouncer-filtered-count'); if (indicator) indicator.textContent = `${count} filtered`; } ``` ## Adding a New AI Provider ```typescript // src/models/providers/myProvider.ts import type { ModelProvider, CompletionRequest, CompletionResponse } from '../types'; export class MyProvider implements ModelProvider { private apiKey: string; private endpoint = 'https://api.myprovider.com/v1/chat/completions'; constructor(apiKey: string) { this.apiKey = apiKey; } async complete(request: CompletionRequest): Promise<CompletionResponse> { const response = await fetch(this.endpoint, { method: 'POST', headers: { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: request.model, messages: [{ role: 'user', content: request.prompt }], max_tokens: 256, }), }); const data = await response.json(); return { text: data.choices[0].message.content, usage: data.usage, }; } } ``` Register it in the provider registry: ```typescript // src/models/registry.ts import { MyProvider } from './providers/myProvider'; export function createProvider(config: StoredConfig): ModelProvider { switch (config.provider) { case 'my-provider': return new MyProvider(config.apiKey); // ... other cases } } ``` ## Result Caching Bouncer caches classification results so repeated posts don't trigger new inference calls: ```typescript // src/utils/cache.ts const CACHE_KEY = 'bouncer-post-cache'; export async function getCachedResult(postId: string): Promise<ClassificationResult | null> { const stored = await chrome.storage.local.get(CACHE_KEY); const cache = stored[CACHE_KEY] ?? {}; return cache[postId] ?? null; } export async function cacheResult(postId: string, result: ClassificationResult): Promise<void> { const stored = await chrome.storage.local.get(CACHE_KEY); const cache = stored[CACHE_KEY] ?? {}; cache[postId] = result; // Limit cache size const keys = Object.keys(cache); if (keys.length > 1000) delete cache[keys[0]]; await chrome.storage.local.set({ [CACHE_KEY]: cache }); } ``` ## Filter Management Filters are stored and retrieved via `chrome.storage.sync`: ```typescript // src/utils/filters.ts export async function getFilters(): Promise<string[]> { const result = await chrome.storage.sync.get('bouncerFilters'); return result.bouncerFilters ?? []; } export async function addFilter(topic: string): Promise<void> { const filters = await getFilters(); if (!filters.includes(topic)) { await chrome.storage.sync.set({ bouncerFilters: [...filters, topic] }); } } export async function removeFilter(topic: string): Promise<void> { const filters = await getFilters(); await chrome.storage.sync.set({ bouncerFilters: filters.filter(f => f !== topic), }); } ``` ## Local WebGPU Models (WebLLM) Local models run entirely in-browser via WebGPU — zero data sent externally: ```typescript // src/models/providers/webllm.ts import { CreateMLCEngine, type MLCEngine } from '@mlc-ai/web-llm'; let engine: MLCEngine | null = null; export async function loadLocalModel(modelId: string, onProgress?: (p: number) => void): Promise<void> { engine = await CreateMLCEngine(modelId, { initProgressCallback: (report) => onProgress?.(report.progress), }); } export async function localComplete(prompt: string): Promise<string> { if (!engine) throw new Error('Local model not loaded'); const response = await engine.chat.completions.create({ messages: [{ role: 'user', content: prompt }], max_tokens: 256, }); return response.choices[0].message.content ?? ''; } ``` ## Chrome Extension Manifest Key Points ```json { "manifest_version": 3, "permissions": ["storage", "activeTab", "scripting"], "host_permissions": ["https://twitter.com/*", "https://x.com/*"], "background": { "service_worker": "background.js" }, "content_scripts": [{ "matches": ["https://twitter.com/*", "https://x.com/*"], "js": ["content.js"], "run_at": "document_idle" }] } ``` ## Troubleshooting | Problem | Fix | |---------|-----| | Extension not loading | Ensure `npm run build` completed without errors; reload unpacked extension | | Posts not being filtered | Check that filters are saved in popup; open DevTools on x.com and check console for errors | | API key errors | Verify key is stored via Settings panel, not hardcoded; check provider dashboard for quota | | Local model not loading | Browser must support WebGPU (`chrome://flags/#enable-unsafe-webgpu`); first load downloads model (~2-4GB) | | Filtered count not updating | MutationObserver may have detached; reload the page | | TypeScript errors on build | Run `npm install` to ensure all types are present; check `tsconfig.json` target is `ES2020+` | ## Common Patterns **Check if a post should be processed (before API call):** ```typescript async function classifyAndFilter(post: ExtractedPost): Promise<void> { // Skip if already processed if (post.element.dataset.bouncerProcessed) return; post.element.dataset.bouncerProcessed = 'true'; // Check cache first const cached = await getCachedResult(post.id); if (cached) { if (cached.filtered) hidePost(post.element, cached.reasoning); return; } const filters = await getFilters(); if (filters.length === 0) return; const config = await getModelConfig(); const result = await classifyPost(post, filters, config); await cacheResult(post.id, result); if (result.filtered) hidePost(post.element, result.reasoning); } ``` **Storing API key securely (popup UI):** ```typescript // Never log or expose the key — store only via chrome.storage.local async function saveApiKey(provider: string, key: string): Promise<void> { await chrome.storage.local.set({ [`${provider}_api_key`]: key }); } async function getApiKey(provider: string): Promise<string> { const result = await chrome.storage.local.get(`${provider}_api_key`); return result[`${provider}_api_key`] ?? ''; } ```