roam-research

Roam Research Skill

Overview

Claude can manage your Roam Research database to capture thoughts, create bidirectional links, build a networked knowledge base, and query your notes. A tool for networked thought.

Quick Install

curl -sSL https://canifi.com/skills/roam-research/install.sh | bash

Or manually:

cp -r skills/​roam-research ~/​.canifi/​skills/

Setup

Configure via canifi-env:

# First, ensure canifi-env is installed:
# curl -sSL https://canifi.com/install.sh | bash

canifi-env set ROAM_EMAIL "[email protected]"

Privacy & Authentication

Your credentials, your choice. Canifi LifeOS respects your privacy.

Option 1: Manual Browser Login (Recommended)

If you prefer not to share credentials with Claude Code:

1. Complete the Browser Automation Setup using CDP mode
2. Login to the service manually in the Playwright-controlled Chrome window
3. Claude will use your authenticated session without ever seeing your password

Option 2: Environment Variables

If you're comfortable sharing credentials, you can store them locally:

canifi-env set SERVICE_EMAIL "your-email"
canifi-env set SERVICE_PASSWORD "your-password"

Note: Credentials stored in canifi-env are only accessible locally on your machine and are never transmitted.

Capabilities

• Create daily notes and pages
• Build bidirectional links
• Create block references
• Query with Roam queries
• Use templates and workflows
• Create TODO items
• Add page references
• Use attributes and metadata
• Create tables
• Embed blocks and pages
• View graph overview
• Use keyboard shortcuts

Usage Examples

Example 1: Add to Daily Note

User: "Add 'Met with John about the project' to today's Roam note"
Claude: Opens daily note, adds block with content.
        Confirms: "Added to today's daily note"

Example 2: Create Page

User: "Create a page for Project Alpha with key details"
Claude: Creates [[Project Alpha]] page, adds initial content.
        Returns: "Created Project Alpha page"

Example 3: Search Links

User: "Find all pages linking to Machine Learning"
Claude: Checks backlinks for [[Machine Learning]].
        Reports: "12 pages reference Machine Learning: Neural Networks, Deep Learning..."

Example 4: Query Notes

User: "Find all my TODOs from this week"
Claude: Runs query for TODO items with date filter.
        Reports: "8 TODOs this week: Review proposal, Update docs..."

Authentication Flow

1. Claude navigates to roamresearch.com via Playwright MCP
2. Enters ROAM_EMAIL for authentication
3. Handles 2FA if required (notifies user via iMessage)
4. Maintains session for graph operations

Selectors Reference

// Daily notes
'.roam-article'

// Block
'.rm-block'

// Block content
'.rm-block__input'

// Page title
'.rm-title-display'

// Sidebar
'.roam-sidebar'

// Search
'.bp3-input'

// Linked references
'.rm-reference-container'

// Block reference
'.rm-block-ref'

// Page reference
'.rm-page-ref'

// TODO checkbox
'.check-container'

Roam Syntax

[[Page Link]]          // Link to page
((block-id))           // Block reference
#tag                   // Tag
{{TODO}}               // TODO item
{{[[TODO]]}}           // TODO with page link
**bold**               // Bold text
__italics__            // Italic text
^^highlight^^          // Highlight
{{embed: [[page]]}}    // Embed page
{{query: {and:...}}}   // Roam query

Error Handling

• Login Failed: Retry 3 times, notify user via iMessage
• Session Expired: Re-authenticate automatically
• Page Not Found: Create page or ask user
• Block Failed: Retry, check graph sync
• Query Error: Check query syntax, suggest fix
• Sync Issues: Wait and retry

Self-Improvement Instructions

When you learn a better way to accomplish a task with Roam:

1. Document the improvement in your response
2. Suggest updating this skill file with the new approach
3. Include specific linking strategies
4. Note useful query patterns

Notes

• Bidirectional links are automatic
• Block references for reusable content
• Daily notes as capture inbox
• Graph view shows connections
• Roam queries for dynamic content
• Keyboard-driven interface
• Version history available
• JSON export for backup