Cookie Extraction from Browsers with the `--from-browser` Flag in Agent-Reach

The --from-browser flag triggers an automated workflow that extracts authentication cookies from Chrome, Firefox, or Edge by copying their SQLite databases, querying the cookies table, and injecting the normalized session data into the agent's YAML configuration.

Agent-Reach is an open-source automation framework that streamlines authenticated interactions with web platforms like Twitter and Xiaohongshu. When you use the --from-browser option, the tool programmatically harvests session cookies directly from your local browser storage, eliminating manual copy-pasting and reducing credential exposure in command-line arguments.

CLI Argument Parsing and Browser Detection

The process begins in agent_reach/cli.py, where the --from-browser argument is parsed and validated. The flag accepts specific browser identifiers such as chrome, firefox, or edge. Once specified, the CLI forwards the browser name to the extraction engine, which determines the appropriate file system paths based on the host operating system.

Locating and Accessing Cookie Stores

The core extraction logic resides in agent_reach/cookie_extract.py. This module maintains a mapping of platform-specific paths to browser cookie databases. For instance, on Linux systems, Chrome stores cookies in ~/.config/google-chrome/Default/Cookies, while macOS and Windows utilize their respective proprietary paths under the user profile directory.

Safe Database Copying with shutil.copy2

Because running browsers lock their cookie files to prevent corruption, Agent-Reach cannot read the database directly. Instead, the code creates a temporary snapshot using shutil.copy2 before opening the file. This approach prevents file contention errors while ensuring the original data remains untouched.

SQLite Querying and Data Normalization

Using Python's built-in sqlite3 module, the extractor connects to the copied database and executes queries against the cookies table. It filters entries by domain—such as twitter.com or xhs.com—and extracts critical fields including name, value, expires_utc, and secure flags. The routine then normalizes this data into a dictionary format that Agent-Reach channels consume for authenticated requests.

Handling macOS Full Disk Access Permissions

On macOS, accessing browser data requires "Full Disk Access" permissions. The test suite in tests/test_cookie_extract_perms.py validates that the extractor gracefully detects permission failures. Rather than crashing with cryptic SQLite errors, the system surfaces clear messages instructing users to grant the necessary permissions in System Preferences.

Configuration Injection

After extraction, the cookies are merged into config.yaml via the configuration management layer. This persistence step ensures that subsequent read or search operations automatically include the authentication data without requiring repeated extraction or exposing raw cookie values in shell history.

Practical Usage Examples

Extract cookies from Chrome and store them for immediate use:

python -m agent_reach.cli install --from-browser=chrome

Programmatically extract cookies for a specific domain using the Python API:

from agent_reach.cookie_extract import extract_cookies
from agent_reach.channels.twitter import TwitterChannel

# Extract cookies for Twitter from Chrome

twitter_cookies = extract_cookies(browser="chrome", domain="twitter.com")

# Initialize the channel with extracted session data

channel = TwitterChannel(cookies=twitter_cookies)
tweets = channel.search("AI agents")

View available browser options via the help flag:

python -m agent_reach.cli --help

Supported Browsers and Storage Locations

Agent-Reach currently supports Chrome, Firefox, and Edge. The cookie_extract.py module automatically resolves the correct SQLite database paths across Linux, macOS, and Windows environments, handling variations in directory structures and file naming conventions without user intervention.

Summary

• The --from-browser flag initiates automated cookie extraction from Chrome, Firefox, or Edge through agent_reach/cli.py
• agent_reach/cookie_extract.py resolves platform-specific paths and manages SQLite database connections
• shutil.copy2 creates temporary database copies to circumvent browser file locks during extraction
• The system queries the cookies table and normalizes attributes for domain-specific authentication
• tests/test_cookie_extract_perms.py ensures robust handling of macOS Full Disk Access requirements
• Extracted sessions are persisted to config.yaml for seamless integration with Agent-Reach channels

Frequently Asked Questions

Which browsers are compatible with the --from-browser flag?

The flag supports Chrome, Firefox, and Edge. The implementation in agent_reach/cookie_extract.py contains platform-specific mappings to each browser's SQLite cookie storage location across Linux, macOS, and Windows operating systems.

Why does Agent-Reach copy the cookie file before reading it?

Running browsers maintain exclusive locks on their cookie databases to prevent corruption. By using shutil.copy2 to create a temporary snapshot, Agent-Reach avoids file contention errors while maintaining read-only access to the original data store.

How does the tool handle missing permissions on macOS?

When Full Disk Access is not granted, the extraction routine detects the permission failure and returns a clear error message. The test coverage in tests/test_cookie_extract_perms.py validates this behavior, ensuring users receive actionable instructions rather than cryptic database errors.

Where does Agent-Reach store cookies after extraction?

The extracted cookies are merged into the config.yaml configuration file through the configuration management layer. This allows all subsequent channel operations to automatically include authentication data without requiring manual cookie entry or repeated extractions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}