# Builtbyecho Research

> Use when a user asks an agent to do web research, source discovery, citation-backed reporting, page extraction, crawling, or browser-rendered research using the BuiltByEcho Research npm package. Also use when installing, verifying, or demonstrating @builtbyecho/research.

- Skill: `lord1egypt/builtbyecho-research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lord1egypt/builtbyecho-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/builtbyecho-research/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Lord1Egypt (https://skillmd.com/u/lord1egypt)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/lord1egypt/builtbyecho-research

---


# BuiltByEcho Research

Use `@builtbyecho/research` for local-first web research workflows: search, fetch, render JavaScript-heavy pages, crawl sites, extract structured fields, audit sources, save traces, and produce citation-backed reports.

## Install or run

Prefer `npx` when you only need a one-off run:

```bash
npx @builtbyecho/research --help
```

For repeated use, install globally:

```bash
npm install -g @builtbyecho/research
builtbyecho-research --help
```

Alias:

```bash
echo-research --help
```

Requires Node.js 20+.

## Optional browser setup

The package uses Playwright for render/browser escalation. If Playwright browsers are missing, install Chromium:

```bash
npx playwright install chromium
```

## Optional search key

No API key is required. For better search discovery, set a Brave API key:

```bash
export BRAVE_API_KEY="..."
```

Without `BRAVE_API_KEY`, search falls back to DuckDuckGo HTML scraping.

## Common commands

Search:

```bash
npx @builtbyecho/research search "open source deep research agents" -n 8
```

Fetch a page:

```bash
npx @builtbyecho/research fetch https://example.com --max-chars 5000
```

Render a JavaScript-heavy page:

```bash
npx @builtbyecho/research render https://example.com
```

Run a research pipeline:

```bash
npx @builtbyecho/research pipeline "research agent architecture" --expand --rounds 2 -n 8 --format markdown --trace
```

Generate a citation-backed report:

```bash
npx @builtbyecho/research report "Playwright browser automation best practices" -n 6 --rounds 2 --trace
```

Extract structured fields:

```bash
npx @builtbyecho/research extract https://example.com --schema links,headings
npx @builtbyecho/research extract https://company.example --schema emails,phones,pricing,contact_links,socials
```

Crawl a site:

```bash
npx @builtbyecho/research crawl https://docs.example.com --depth 2 --max-pages 25 --chunk
```

## Workflow guidance

1. Start with `search`, `pipeline`, or `report` depending on the user’s goal.
2. Use `--trace` for research that may need auditability or follow-up.
3. Prefer `render` or browser escalation for pages with low text, heavy JavaScript, “enable JavaScript” messages, or bot-wall/CAPTCHA-like content.
4. Treat generated prose as a first draft. Verify citations before high-stakes use.
5. Do not bypass CAPTCHA, login walls, paywalls, robots/ToS restrictions, or other access controls.

## Library API

For Node.js code:

```js
import {
  researchPipeline,
  iterativeResearchPipeline,
  toResearchReport,
  extractSchemaFromUrl,
} from '@builtbyecho/research';

const result = await iterativeResearchPipeline('Playwright MCP best practices', {
  expand: true,
  count: 6,
  rounds: 2,
});

console.log(toResearchReport(result));
```

## Vaultline integration

For research that needs durable handoff, upload the final report or trace bundle to Vaultline instead of leaving it in transient chat history.

```bash
node -e '
const fs = require("node:fs");
const { Vaultline } = require("@builtbyecho/vaultline-sdk");
const reportPath = "report.md";
const content = fs.readFileSync(reportPath, "utf8");
const vault = new Vaultline({ apiKey: process.env.VAULTLINE_API_KEY });
vault.files.upload({
  path: `research/${Date.now()}-report.md`,
  content,
  contentType: "text/markdown"
}).then(r => console.log("Vaultline fileId:", r.fileId));
'
```

Use this pattern when multiple agents or human reviewers need the same source-backed artifact.