SessionKeeper 🔐

Persistent browser sessions for AI agents. The missing piece that turns AI assistants from "helpful guides" to "actually gets shit done."

The Problem

Your AI agent can think, plan, and generate code. But when you ask it to:

• "Check my calendar and book that meeting"
• "Apply to those 5 jobs on LinkedIn"
• "Find apartments and schedule viewings"

It responds: "I can't actually log in to do that, but here's how you could..."

SessionKeeper fixes this. It maintains persistent, authenticated browser sessions that survive conversation restarts.

Features

• 🔐 Persistent Authentication - Stay logged in across AI conversations
• 🤖 Anti-Bot Evasion - Realistic browser fingerprints and behavior
• 🔒 Encrypted Storage - Session data encrypted at rest
• 🎯 MCP Integration - Works with Claude, OpenClaw, and any MCP-compatible AI
• 🌐 Complex Flows - Handle 2FA, CAPTCHAs, multi-step authentication
• 📸 Visual Feedback - Screenshots and content extraction
• 🛡️ Session Health - Auto-save and recovery mechanisms

Installation

npm install -g sessionkeeper
# or
pnpm install -g sessionkeeper

Quick Start

1. Start the MCP Server

sessionkeeper
# Server running on stdio, ready for MCP clients

2. Configure Your AI Client

Add to your MCP configuration:

{
  "mcpServers": {
    "sessionkeeper": {
      "command": "sessionkeeper",
      "args": []
    }
  }
}

3. Use From Your AI

AI: I'll help you check your Gmail. Let me establish a session first.

[session_navigate sessionId="gmail" url="https://gmail.com"]
[session_interact sessionId="gmail" action="click" selector="[data-action='sign-in']"]
[session_interact sessionId="gmail" action="type" selector="input[type='email']" text="[email protected]"]

Your Gmail session is now active and persistent!

MCP Tools

SessionKeeper provides these tools to AI agents:

session_navigate

Navigate to a URL in a persistent session.

{
  "sessionId": "gmail",
  "url": "https://gmail.com",
  "waitFor": ".inbox-selector" // optional
}

session_interact

Interact with page elements.

{
  "sessionId": "gmail", 
  "action": "click", // click, type, select, hover, wait
  "selector": "button[data-action='compose']",
  "text": "Hello world" // for type action
}

session_screenshot

Capture visual state.

{
  "sessionId": "gmail",
  "element": ".compose-window" // optional, full page if omitted
}

session_content

Extract page content.

{
  "sessionId": "gmail",
  "type": "text", // text, html, title, url
  "selector": ".email-subject" // optional
}

session_save / session_list / session_delete

Manage stored sessions.

Configuration

Environment Variables

• SESSIONKEEPER_KEY - Encryption key for session data (auto-generated if not set)
• SESSIONKEEPER_DATA_DIR - Storage directory (default: ./session-data)
• SESSIONKEEPER_HEADLESS - Run headless browser (default: true, set false for debugging)

Advanced Usage

# Custom data directory
SESSIONKEEPER_DATA_DIR=/secure/sessions sessionkeeper

# Visible browser for debugging
SESSIONKEEPER_HEADLESS=false sessionkeeper

# Custom encryption key
SESSIONKEEPER_KEY=your-32-char-key sessionkeeper

Use Cases

🗓️ Calendar Management

"Check my calendar for next week and reschedule the Tuesday meeting to Thursday"

The AI maintains your Google Calendar session, can view events, create new ones, and handle conflicts.

💼 Job Applications

"Apply to 10 frontend jobs on LinkedIn with customized cover letters"

Stay logged into LinkedIn, Indeed, etc. Apply to jobs with personalized applications.

🏠 Apartment Hunting

"Find 5 apartments under €1200 in Berlin and schedule viewings"

Search Zillow, Apartments.com, local sites. Fill out application forms automatically.

📧 Email Management

"Send a follow-up email to everyone I met at the conference last week"

Access Gmail, Outlook. Search conversations, compose contextual messages.

💰 Financial Tasks

"Check my bank balance and pay the utility bills"

Login to banking, utilities. Navigate complex multi-step payment flows.

Security

• Encrypted Storage: All session data encrypted with AES-256
• Local Only: Sessions stored locally, never transmitted
• Scoped Access: Each sessionId is isolated
• Auto-Cleanup: Old sessions can be set to auto-expire
• Audit Trail: All interactions logged for debugging

Anti-Bot Measures

SessionKeeper includes several techniques to appear human-like:

• Realistic User-Agent: Matches common browser signatures
• Mouse Movements: Simulated human-like cursor behavior
• Timing Delays: Realistic pauses between actions
• Browser Fingerprint: Proper navigator, plugins, screen size
• Cookie Management: Maintains realistic cookie patterns

Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│     AI      │───▶│ SessionKeeper │───▶│  Website    │
│   Agent     │    │  MCP Server   │    │ (Gmail,     │
│  (Claude)   │◀───│               │◀───│ LinkedIn)   │
└─────────────┘    └──────────────┘    └─────────────┘
                           │
                           ▼
                   ┌──────────────┐
                   │   Encrypted  │
                   │   Session    │
                   │   Storage    │
                   └──────────────┘

Development

git clone https://github.com/hal-crackbot/sessionkeeper
cd sessionkeeper
pnpm install
pnpm dev

Roadmap

• [ ] Session Sharing - Share sessions between AI agents safely
• [ ] CAPTCHA Solving - Automatic solving of common CAPTCHAs
• [ ] Mobile Sessions - Support for mobile web interfaces
• [ ] Session Templates - Pre-configured flows for common sites
• [ ] Proxy Support - Route sessions through proxies
• [ ] Session Analytics - Health monitoring and success metrics

Contributing

Built following the steipete philosophy: focused tools that solve real problems AI agents face every day.

1. Fork the repo
2. Create a feature branch
3. Add tests for new functionality
4. Submit a PR with clear description

License

MIT © 2026 Hal Crackbot

Why This Matters

AI agents are powerful but limited by their inability to maintain state across conversations. SessionKeeper removes this fundamental constraint.

Before: "I can tell you how to book that flight, but I can't actually do it."

After: "Flight booked! Confirmation number XY123. Receipt sent to your email."

This is infrastructure for the AI agent future. When agents can persist context and maintain authenticated sessions, they become genuinely useful assistants rather than expensive search engines.

Building the tools that make AI agents actually work. 🚀