Adapter Lab: advanced capture rules for supported platforms

0. When you actually need Adapter Lab

Adapter Lab is designed for fixing and customizing capture on already-supported platforms:

• You DON'T need it if:
  • Automatic capture is working correctly on supported platforms
  • You're not familiar with web development (DOM, CSS selectors, HTML)
  • You just want to use ChatEngram's core features (search, sync, export)
• You DO need it if:
  • A supported platform (ChatGPT, Claude, etc.) updated their UI and capture broke
  • You want to customize message extraction rules for your workflow

Remember: Adapter Lab works only on the 6 platforms listed above. It's a repair and customization tool, not a way to add new public platforms. For new platform support, please contact us at support@chatengram.com.

1. Open Adapter Lab in the dashboard

1. Install and activate the ChatEngram extension in your browser.
2. Open the ChatEngram web dashboard (the main UI you already use for search and export).
3. In the left navigation, click "Adapter Lab".
4. You will see a list of existing adapters (built-in ones for ChatGPT / DeepSeek / etc.) and controls to create a new adapter.

2. How adapters are structured

Each adapter tells ChatEngram how to read messages from a specific site:

• Target URL / domain: which pages this adapter should run on (must be one of the 6 supported platforms).
• Message container selector: how to find each message block in the DOM.
• Role selectors: how to distinguish between user messages and assistant messages.
• Content selectors: how to pick out the actual text (and code blocks) from inside each message.

Under the hood, Adapter Lab converts these rules into a deterministic extractor, so capture is stable and testable instead of relying on brittle heuristics.

3. Recommended workflow for creating a new adapter

1. Open a real AI conversation page on one of the supported platforms (with a few back-and-forth turns so you can test user/assistant detection).
2. Open your browser dev tools (F12), switch to the Elements / Inspector panel, hover a user message and inspect its DOM structure and class names.
3. Do the same for an assistant message and note any class or data attributes that clearly distinguish it from user messages.
4. Back in ChatEngram's Adapter Lab, in the "New adapter" section, fill in:
   • Match URL: must be one of the supported platforms, e.g. https://chatgpt.com/*.
   • Message selector: the CSS selector for the outer container of each message, e.g. .chat-message.
   • User selector / Assistant selector: rules that determine the role of each message, for example based on extra class names .from-user / .from-ai.
   • Content selector: the element containing the actual message body, e.g. .message-body or .markdown.
5. Click the "Preview / Test" button in Adapter Lab. ChatEngram will run the current rules on the active page and show you the extracted conversation in the preview area.
6. If user/assistant roles are wrong or content is missing, tweak the selectors above and repeat the test until the preview looks correct.
7. Save the adapter; from now on, any page matching the URL pattern will use this rule automatically.

4. Selector tips

• Prefer stable class or data- attributes such as .message or[data-role="assistant"], and avoid depending on long hash-like class names that look auto-generated.
• For nested structures, use descendant selectors such as .chat-message .markdown-body.
• Avoid index-based selectors like :nth-child(3), which tend to break as soon as the layout changes.
• If user and assistant messages share almost the same DOM structure but use different wrapper classes, you can point the user / assistant selectors at those wrapper differences instead.

5. Updating adapters when the UI changes

When a supported platform ships a new UI and capture stops working, you can recover by:

1. Opening an older conversation in the dashboard to confirm historical data is still present (to rule out local database issues).
2. Opening a conversation in the new UI, using dev tools to inspect the DOM, and noting new class names or structural changes.
3. Editing the relevant adapter in Adapter Lab and updating the message / content / role selectors.
4. Using the preview feature on the new UI to re-run extraction until user/assistant roles and content look correct again.
5. Saving the changes; new conversations will then be captured using the updated rules.

6. Troubleshooting checklist

• No messages are captured at all: confirm the Match URL is one of the 6 supported platforms, and verify in dev tools that the message selector matches at least one DOM element.
• Everything is classified as user or everything as assistant:check whether the role selectors are too broad, or whether you forgot to distinguish the different wrapper classes for user vs assistant.
• Code blocks or rich text are missing: make sure the content selector points at the container that holds the full markdown / rich text, not just a title or truncated preview.
• You want to temporarily disable an adapter: you can disable the rule in Adapter Lab instead of deleting it, so it's easy to re-enable later.