Ruminer Browser Agent

Sync your AI conversations from 5+ platforms into your second brain — quick search, agent-ready, yours forever.

• Continuously export conversations to local Markdown files across AI chat platforms: ChatGPT, Gemini, Claude, DeepSeek, and Grok.

• Your user credentials on these platforms stay secure in your own browser, never uploaded to cloud.

• Freely choose your AI agent backend: OpenClaw, Claude Code, or Codex.

• Make your agent understand you deeply via RAG from your local Markdown conversation archive.

• Seamlessly integrated into your Chrome browser with beautiful UI and powerful automation.

Visit Our Landing Page!

Watch Our Demo Video!

https://github.com/user-attachments/assets/fb49d045-3d43-49b6-b51a-3ee8ff9ed508

System Architecture

flowchart TB
    subgraph MCP_Clients[MCP Clients]
        Codex[Codex CLI]
        ClaudeCode[Claude Code]
        OpenClawPlugin[OpenClaw]
    end

    subgraph OpenClaw[OpenClaw Gateway]
        Gateway[ws://127.0.0.1:18789]
    end

    subgraph Ruminer[Ruminer Stack]
        NativeServer[Messaging Server]
        McpServer[MCP Server<br/>http://127.0.0.1:12306/mcp]
        Extension[Chrome Extension<br/>Service Worker]
        Sidepanel[Side Panel UI]
        Workflows[Ingestion Workflows]
    end

    subgraph Chrome[Chrome Browser Session]
        APIs[Chrome APIs<br/>tabs, read page, scrolling, click]
    end

    subgraph Memory[Local Memory]
        LocalMD[Markdown Files<br/>~/your-memory-dir/]
    end

    subgraph AIPlatforms[AI Chat Platforms]
        ChatPlatforms[ChatGPT, Gemini, Claude, DeepSeek, Grok]
    end

    MCP_Clients <-->|"Streamable HTTP"| McpServer
    APIs <-->|"Browser Tools"| McpServer
    LocalMD -->|"RAG Tools"| McpServer

    NativeServer <-->|"Native Messaging"| Extension
    Extension <--> APIs

    Sidepanel <-->|"Chat"| NativeServer
    NativeServer <-->|"WebSocket"| Gateway

    Workflows -->|"Write Markdown"| LocalMD
    LocalMD -->|"Memory Search"| Sidepanel

    AIPlatforms -->|"Conversation Data"| Workflows

The Ruminer UI has three major pillars in one Chrome extension:

1. Chat tab: communicate with your CLI agents via native server, providing MCP tools for browser operations and local RAG.

   • You can toggle tool groups (Memory / Observe / Navigate / Interact / Execute / Workflow) in the message input box to control which ones the agent can use.

2. Memory tab: browse/search/manage your local memory directory.

   • Conversations are organized by AI chat platform and stored as plain Markdown files you own.

3. Workflows tab: create, edit, and schedule automation workflows to export conversations to your local Markdown directory or accomplish other tasks in browser.

   • Coming soon: agent-driven workflow development by autonomously interacting with the browser and editing the workflow graph!

Glossary

• OpenClaw Gateway: local control plane for chat + tool runtime (Ruminer sidepanel chat talks to it).

• MCP: Model Context Protocol; here it’s the standard interface your clients use to call browser tools.

• Local Markdown memory: plain .md files written to a directory you configure — compatible with Obsidian, Logseq, and any agent that can read files (OpenClaw, Hermes, GBrain, Claude Code, Codex).

Getting Started (local dev)

Prerequisites

• Node.js >= 22.5.0

• pnpm (see package.json)

• Chrome/Chromium (MV3 + sidepanel enabled)

• Optional but recommended:

  • openclaw CLI (for sidepanel chat + plugin routing)

  • A local Markdown directory path (for memory storage + RAG ingestion)

1) Quick setup

From the repo root, run:

pnpm install
pnpm -C app/chrome-extension build

Then open the extension Welcome page (it opens automatically on install) and run the one‑shot installer to set up Native Messaging + MCP clients:

curl -fsSL https://raw.githubusercontent.com/casterkay/ruminer-browser-agent/refs/heads/main/scripts/setup.sh | \
  bash -s -- --extension-id <your-extension-id>

This installer (best-effort):

• Installs chrome-mcp-server and registers the Native Messaging host (allowlisted to your extension ID)

• Adds Ruminer MCP endpoint to Claude Code and Codex (ruminer-chrome)

• Installs + enables the OpenClaw plugin (openclaw-mcp-plugin) and points it to Ruminer MCP URL

2) Load the extension

Chrome does not allow “Load unpacked” via script.

1. Open chrome://extensions

2. Enable Developer mode

3. Click Load unpacked

4. Select:

   • app/chrome-extension/.output/chrome-mv3

3) Configure the extension

In the Settings tab in Ruminer side panel:

• OpenClaw Gateway

  • WS URL: ws://127.0.0.1:18789

  • Token: your Gateway token

• Memory Directory

  • Local path to your Markdown memory folder (e.g. ~/Documents/my-second-brain)

Hosted auth and billing URL

Workflow unlock now relies on the hosted Ruminer web app in landing-page for Better Auth + Stripe. The extension opens that app for sign-in, checkout, and account management, then receives a browser-bound access snapshot back through the background service worker.

• Set WXT_PUBLIC_RUMINER_WEB_URL to your hosted web app origin when building or running the extension.

• VITE_RUMINER_WEB_URL is also accepted as a fallback alias if you already use that naming in local env files.

• If neither env var is set, the extension defaults to http://localhost:3000.

Local dev example:

cd landing-page
pnpm install
pnpm dev

cd ../app/chrome-extension
WXT_PUBLIC_RUMINER_WEB_URL=http://localhost:3000 pnpm dev

Verify It Works

1. MCP tool check:

   • Ask the agent to call a tool (e.g. "List the current tab titles in my browser") in CLI.

2. Side panel chat:

   • Open Ruminer side panel → Chat → send a message → see tool calls render inline

3. Memory suggestions (requires memory directory configured):

   • Type ≥ 3 characters in message input box → see debounced suggestions from your local Markdown files

4. Workflows (requires memory directory configured):

   • Open Workflows tab → run a built‑in workflow → re-run should not duplicate (ledger + stable IDs)

Developer Notes

This is a pnpm workspace with key packages:

• app/chrome-extension: MV3 extension (Vue 3 + WXT + Tailwind)

• app/native-server: Fastify server + Native Messaging host + MCP transport

• packages/shared: shared types + tool schemas

License

AGPL-3.0 (see LICENSE).