research

Engineering Community

Skill notes

Quick Start

Install with brew tap willemave/researchbuddy and brew install researchbuddy unless the user explicitly wants a source checkout. Run researchbuddy --help to confirm the installed command surface.

Read These References As Needed

For every public command and option, read references/commands.md. For dependency failures and recovery steps, read references/troubleshooting.md.

Operating Rules

Prefer the Homebrew-installed researchbuddy command. Use scripts/researchbuddy only inside a source checkout. During first-time OpenClaw installs, prefer reusing the provider configured in ~/.openclaw/openclaw.json over asking the user for a fresh EXA_API_KEY, TAVILY_API_KEY, or FIRECRAWL_API_KEY. Do not copy OpenClaw secrets into skill files, chat logs, docs, command output, or ResearchBuddy .env. Let ResearchBuddy load them directly from OpenClaw or Hermes.

Public Commands

researchbuddy start researchbuddy followup researchbuddy status researchbuddy watch researchbuddy doctor

Config Model

ResearchBuddy is env-driven. It reads process environment variables, ~/.hermes/.env, ~/.openclaw/.env, ~/.openclaw/openclaw.json, and local .env. Shared agent configs are canonical for search-provider credentials; local .env is only for manual fallback config. researchbuddy doctor --fix validates detected search-provider config, prepares storage/database, installs Playwright browsers, and repairs stale runs. It does not copy provider credentials into .env.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@willemave · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Required · Firecrawl
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Env read
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

# Research

Use this skill when the task is about using ResearchBuddy for research, installing it with Homebrew, asking questions against saved sessions, or fixing a machine that fails runtime checks.

## Quick Start

1. Install with `brew tap willemave/researchbuddy` and `brew install researchbuddy` unless the user explicitly wants a source checkout.
2. Run `researchbuddy --help` to confirm the installed command surface.
3. For OpenClaw, install this skill with `researchbuddy skills install openclaw --scope shared`, or use `--scope workspace --workspace /path/to/workspace` for one workspace only.
4. In OpenClaw environments, inspect `~/.openclaw/openclaw.json` before asking for search-provider credentials. If it already has `plugins.entries.<provider>.config.webSearch.apiKey`, legacy `tools.web.search.<provider>.apiKey`, or `tools.web.search.apiKey` for `exa`, `tavily`, or `firecrawl`, ask once whether ResearchBuddy should reuse it.
5. If the user approves reuse, do not ask them to paste a duplicate API key. Run `researchbuddy doctor --fix`; ResearchBuddy auto-loads OpenClaw config and does not copy provider credentials into local `.env`.
6. If OpenClaw has no usable provider config, or the user declines reuse, ask for one provider key and set it through the runtime environment or local `.env`, then rerun `researchbuddy doctor --fix`.
7. Start long research jobs with `researchbuddy start "<prompt>" --json`; the command returns immediately with the run ID, PID, status command, watch command, and log path.
8. Use `researchbuddy status`, `researchbuddy watch`, and `researchbuddy followup "<question>"` against the current run by default.

## Read These References As Needed

- For every public command and option, read `references/commands.md`.
- For dependency failures and recovery steps, read `references/troubleshooting.md`.

## Operating Rules

- Prefer the Homebrew-installed `researchbuddy` command. Use `scripts/researchbuddy` only inside a source checkout.
- During first-time OpenClaw installs, prefer reusing the provider configured in `~/.openclaw/openclaw.json` over asking the user for a fresh `EXA_API_KEY`, `TAVILY_API_KEY`, or `FIRECRAWL_API_KEY`.
- Do not copy OpenClaw secrets into skill files, chat logs, docs, command output, or ResearchBuddy `.env`. Let ResearchBuddy load them directly from OpenClaw or Hermes.
- Before debugging a broken runtime, run `researchbuddy doctor`.
- For long research work, use `researchbuddy start "<prompt>" --json`; do not manually background a worker process.
- Use `researchbuddy status --json` when another agent or script needs machine-readable progress.
- Use `researchbuddy watch --timeout 900` when you need to stream the active worker log until completion.
- ResearchBuddy currently ships cleanly as a packaged CLI, not a hosted web service.
- The runtime depends on the external `codex` CLI. If `doctor` fails on `codex`, do not treat the environment as production-ready.
- If `doctor` fails on `ffmpeg`, follow the OS-specific install steps in `references/troubleshooting.md`, verify with `ffmpeg -version`, then rerun `researchbuddy doctor`.

## Public Commands

- `researchbuddy start`
- `researchbuddy followup`
- `researchbuddy status`
- `researchbuddy watch`
- `researchbuddy doctor`
- `researchbuddy skills install openclaw`
- `researchbuddy list`

Read `references/commands.md` before using less-common options such as `--prompt-file`, `--result-file`, `--output-dir`, model overrides, `--skip-playwright`, or JSON output.

## Config Model

- ResearchBuddy is env-driven. It reads process environment variables, `~/.hermes/.env`, `~/.openclaw/.env`, `~/.openclaw/openclaw.json`, and local `.env`.
- Shared agent configs are canonical for search-provider credentials; local `.env` is only for manual fallback config.
- `researchbuddy doctor --fix` validates detected search-provider config, prepares storage/database, installs Playwright browsers, and repairs stale runs. It does not copy provider credentials into `.env`.
- Homebrew installs should not edit files under the Homebrew prefix or uv cache for config.

## Outputs

- Run artifacts are written under `~/.researchbuddy/storage/<run_id>/` by default.
- Key files are `synthesis.md`, `worker.log`, `run.log`, and the `html/` / `markdown/` crawl artifacts.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.