Skip to main content

​
Overview

ContextFort is a Chrome extension that provides visibility and control over browser-based AI agents. It operates through a multi-layered architecture consisting of background services, content scripts, and a dashboard interface.

​
Core Components

​
Background Service Worker

The background service (background.js) acts as the central orchestrator, managing:
  • Session tracking - Monitors agent activity across tab groups
  • Cookie management - Handles session isolation between human and agent contexts
  • Event coordination - Routes messages between content scripts and the dashboard
  • Storage operations - Queues and persists screenshots and session data

​
Content Script

The content script (content.js) runs on every webpage and:
  • Detects agent activity - Monitors DOM interactions to identify AI agent behavior
  • Captures events - Records clicks, inputs, and navigation events
  • Enforces blocks - Prevents agents from interacting with restricted elements
  • Displays notifications - Shows in-page alerts for blocked actions or login requirements

​
Dashboard Interface

A React-based dashboard provides:
  • Session visualization - View all agent sessions and their activity
  • Screenshot timeline - Browse captured screenshots with event details
  • Control panels - Configure blocking rules and governance policies
  • Analytics - Track agent usage patterns and blocked actions

​
Key Features

ContextFort detects agent activity through tab group monitoring. When a tab is added to a group with the ⌛ emoji:
  1. The background service creates or retrieves a session for that tab group
  2. The content script begins listening for DOM events (clicks, inputs, navigation)
  3. Event listeners capture every interaction the agent makes
  4. Each event triggers a screenshot capture for the visibility timeline
The extension tracks active agent tabs in a Map structure, associating each tab with its session ID and group ID.
Session isolation ensures that human and agent sessions remain separate:Cookie Swapping Process:
  1. When an agent is detected, ContextFort captures all current cookies (human session)
  2. Human cookies are saved to chrome.storage.local under the domain profile
  3. The extension clears all cookies for that domain
  4. If an agent session exists for that domain, those cookies are restored
  5. If no agent session exists, a login prompt is shown
Session Profiles:
sessionProfiles: {
  "example.com": {
    "human": { cookies: [...], capturedAt: "..." },
    "agent": { cookies: [...], capturedAt: "..." }
  }
}
When the agent stops (⌛ → ✅), all domains are swapped back to human sessions.
Screenshots are captured automatically for key events:Captured Events:
  • Click events - Captures before-click and 300ms after-click screenshots
  • Input events - Debounced by 1 second, captures 500ms after last keystroke
  • Navigation - Captures on page load when navigating to new URLs
  • Right-click - Captures context menu interactions
Storage Strategy:
  • Screenshots are queued to prevent storage conflicts
  • Each screenshot includes metadata: timestamp, URL, event type, element details
  • Maximum 100 screenshots retained (FIFO buffer)
  • Each session tracks its screenshot count
Data Structure:
{
  id: timestamp + random,
  sessionId: "...",
  tabId: 123,
  url: "https://...",
  title: "Page Title",
  timestamp: "2024-02-28T...",
  dataUrl: "data:image/png;base64,...",
  eventType: "click",
  eventDetails: {
    element: { tag: "BUTTON", id: "...", ... },
    coordinates: { x: 100, y: 200 },
    actionType: "click"
  }
}
ContextFort provides multiple layers of protection:1. Action Blocks
  • Block specific elements from being clicked or modified
  • Matches elements by tag, id, class, text, type, and name
  • Traverses parent elements to catch delegated events
  • Shows visual feedback (red border) when blocked
2. URL Mixing Prevention
  • Prevents agents from mixing context across domains
  • Blocks navigation based on visited URL history
  • Supports domain-level blocking rules
  • Example: Prevent agent from visiting banking site after visiting shopping site
3. URL Pair Blocking
  • Block specific URL combinations
  • Works with full URLs, not just domains
  • Bidirectional blocking (A→B and B→A)
4. Governance Rules (DNR)
  • disallow_clickable_urls - Blocks all hyperlink navigation
  • disallow_query_params - Blocks URLs containing query parameters
  • Uses Chrome’s Declarative Net Request API for high performance

​
Data Flow

1

Agent Starts

User adds ⌛ emoji to tab group title → Tab group update detected → onMessageAgentDetected creates session → Content script starts event listeners
2

Agent Acts

Agent clicks button → Content script captures click event → Sends SCREENSHOT_TRIGGER message to background → Background captures tab screenshot via chrome.tabs.captureVisibleTab → Screenshot data queued for storage
3

Storage Write

Background processes storage queue → Retrieves current screenshots array → Appends new screenshot → Updates session screenshot count → Writes to chrome.storage.local
4

Agent Stops

User changes ⌛ to ✅ → swapAllDomainsToHuman executes → Agent cookies saved for each domain → Human cookies restored → Tab reloaded with human session → Session marked as ended

​
Storage Structure

All data is stored locally in Chrome using chrome.storage.local. No data is sent to external servers.
Storage Keys:
  • sessions - Array of all sessions (active and ended)
  • screenshots - Array of up to 100 recent screenshots
  • sessionProfiles - Cookie snapshots for human/agent isolation
  • urlBlockingRules - Domain-level blocking rules
  • urlPairBlockingRules - URL pair blocking rules
  • blockedActions - Element-level action blocks
  • governanceRules - High-level governance policies

​
Performance Considerations

Screenshot capture uses the chrome.tabs.captureVisibleTab API, which captures the entire visible area of the tab. Rapid agent actions may create a large number of screenshots.
Optimizations:
  • Input debouncing - Groups rapid keystrokes into single screenshot (1s delay)
  • Queued writes - Prevents simultaneous storage writes that could cause conflicts
  • FIFO buffer - Maintains only 100 most recent screenshots
  • Lazy loading - Dashboard loads screenshots on-demand

​
Security Model

  • No network access - Extension operates entirely offline
  • Local storage only - All data stored in Chrome’s local storage
  • Content script isolation - Runs in isolated world, cannot access page JavaScript
  • Explicit permissions - Requires user approval for cookies, tabs, storage

​
Extension Lifecycle

​
Browser Compatibility

ContextFort requires Chrome 134+ due to:
  • Tab Groups API - Used for session organization
  • Declarative Net Request - Modern blocking API
  • Service Worker - Manifest V3 background execution
  • Cookie Partitioning - Advanced cookie management
The extension uses Manifest V3, which is the required standard for Chrome extensions as of 2024.

Build docs developers (and LLMs) love

Get started for freeTalk to us