Parallel AI Research

Research Skill

Description

Conduct open-ended research on a topic, building a living markdown document. The conversation is ephemeral; the document is what matters.

Trigger

Activate when the user wants to:

• Research a topic, idea, or question
• Explore something before committing to building it
• Investigate options, patterns, or approaches
• Create a "research doc" or "investigation"
• Run deep async research on a complex topic

Research Directory

Each research topic gets its own folder:

~/.openclaw/workspace/research/<topic-slug>/
├── prompt.md          # Original research question/prompt
├── research.md        # Main findings (Parallel output or interactive notes)
├── research.pdf       # PDF export (when generated)
└── ...                # Any other related files (data, images, etc.)

Two Research Modes

1. Interactive Research (default)

For topics you explore together in conversation. You search, synthesize, and update the doc in real-time.

2. Deep Research (async)

For complex topics that need comprehensive investigation. Uses the Parallel AI API via parallel-research CLI. Takes minutes to hours, returns detailed markdown reports.

When to use deep research:

• Market analysis, competitive landscape
• Technical deep-dives requiring extensive source gathering
• Multi-faceted questions that benefit from parallel exploration
• When user says "deep research" or wants comprehensive coverage

Interactive Research Workflow

1. Initialize Research

1. Create the research folder at ~/.openclaw/workspace/research/<topic-slug>/

2. Create prompt.md with the original question:

   # <Topic Title>
   
   > <The core question or curiosity>
   
   **Started:** <date>
   

3. Create research.md with the working structure:

   # <Topic Title>
   
   **Status:** Active Research
   **Started:** <date>
   **Last Updated:** <date>
   
   ---
   
   ## Open Questions
   - <initial questions to explore>
   
   ## Findings
   <!-- Populated as we research -->
   
   ## Options / Approaches
   <!-- If comparing solutions -->
   
   ## Resources
   <!-- Links, references, sources -->
   
   ## Next Steps
   <!-- What to explore next, or "graduate to project" -->
   

4. Confirm with user - Show the folder was created and ask what to explore first.

2. Research Loop

For each exchange:

1. Do the research - Web search, fetch docs, explore code
2. Update the document - Add findings, move answered questions, add sources
3. Show progress - Note what was added (don't repeat everything)
4. Prompt next direction - End with a question or suggestion

Key behaviors:

• Update existing sections over creating new ones
• Use bullet points for findings; prose for summaries
• Note uncertainty ("seems like", "according to X", "unverified")
• Link to sources whenever possible

3. Synthesis Checkpoints

Every 5-10 exchanges, offer to:

• Write a "Current Understanding" summary
• Prune redundant findings
• Reorganize if unwieldy
• Check blind spots

4. Completion

When research is complete, update the status in research.md:

• "Status: Complete" — Done, stays in place as reference
• "Status: Ongoing" — Living doc, will be updated over time

If the research is specifically for building a project:

• Graduate to ~/specs/<project-name>.md as a project spec
• Or create a project directly based on findings
• Update status to "Status: Graduated → ~/specs/..."

Most research is just research — it doesn't need to become a spec. Only graduate if you're actually building something from it.

Deep Research Workflow

1. Start Deep Research

parallel-research create "Your research question" --processor ultra --wait

Processor options:

• lite, base, core, pro, ultra (default), ultra2x, ultra4x, ultra8x
• Add -fast suffix for speed over depth: ultra-fast, pro-fast, etc.

Options:

• -w, --wait — Wait for completion and show result
• -p, --processor — Choose processor tier
• -j, --json — Raw JSON output

2. Schedule Auto-Check (OpenClaw)

After creating a task, set up a cron job to check results and deliver them back to the user. Use deleteAfterRun: true so it cleans up automatically.

⚠️ CRITICAL: Always calculate atMs correctly!

# Get current timestamp in ms and add 15 minutes (900000 ms)
date +%s%3N  # Current time in epoch ms
# Example: 1770087600000 + 900000 = 1770088500000

Always verify the scheduled time is in the future and has the correct year:

date -d @$((1770088500000/1000))  # Should show a time ~15 min from now, correct year

{
  "action": "add",
  "job": {
    "name": "Check research: <topic>",
    "schedule": {"kind": "at", "atMs": <VERIFY: must be current epoch ms + delay>},
    "sessionTarget": "isolated",
    "payload": {
      "kind": "agentTurn",
      "message": "Check research task <run_id>. Run: parallel-research result <run_id>. If complete, summarize key findings. If still running, reschedule another check in 10 min.",
      "deliver": true,
      "channel": "<source channel, e.g. telegram>",
      "to": "<source chat/topic, e.g. -1001234567890:topic:123>"
    },
    "deleteAfterRun": true
  }
}

Key points:

• Use the cron tool with action: "add"
• ALWAYS verify atMs is correct — run date -d @$((atMs/1000)) to confirm year and time
• atMs should be ~10-15 min from now (ultra processor) or ~5 min (fast processors)
• deleteAfterRun: true removes the job after successful completion
• Deliver back to the same channel/topic that requested the research
• If still running, the cron job can create another check
• PARALLEL_API_KEY is available as env var — no need to inline it

3. Manual Check (if needed)

parallel-research status <run_id>
parallel-research result <run_id>

4. Save to Research Folder

Create the research folder and save results:

~/.openclaw/workspace/research/<topic-slug>/
├── prompt.md          # Original question + run metadata
├── research.md        # Full Parallel output

prompt.md should include:

# <Topic Title>

> <Original research question>

**Run ID:** <run_id>
**Processor:** <processor>
**Started:** <date>
**Completed:** <date>

research.md contains the full Parallel output, plus any follow-up notes.

PDF Export

Use the export-pdf script to convert research docs to PDF:

export-pdf ~/.openclaw/workspace/research/<topic-slug>/research.md
# Creates: ~/.openclaw/workspace/research/<topic-slug>/research.pdf

Or specify a custom output path:

export-pdf research.md ~/Desktop/output.pdf

Note: Tables render as stacked rows (PyMuPDF limitation). Acceptable for research docs.

Commands

• "new research: " - Start interactive research doc
• "deep research: " - Start async deep research
• "show doc" / "show research" - Display current research file
• "summarize" - Synthesis checkpoint
• "graduate" - Move research to next phase
• "archive" - Mark as complete reference
• "export pdf" - Export to PDF
• "check research" - Check status of pending deep research tasks

Document Principles

• Atomic findings - One insight per bullet
• Link everything - Sources, docs, repos
• Capture context - Why did we look at this?
• Note confidence - Use qualifiers when uncertain
• Date important findings - Especially for fast-moving topics

Setup

See SETUP.md for first-time installation of:

• parallel-research CLI
• PDF export tools (pandoc, PyMuPDF)