opencode-querit

August 17, 2026 · View on GitHub

Querit-backed web_search and web_fetch custom tools for OpenCode. It is the OpenCode counterpart of pi-querit and dsh-querit: the plugin registers two model-facing tools that route through Querit — live web search and clean page content through POST https://api.querit.ai/v1/search and /v1/contents.

Quick start

Install the plugin from npm and add it to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-querit"]
}

Configure your Querit API key in priority order:
- the QUERIT_API_KEY environment variable (default; override the name with apiKeyEnv) — the environment always wins, so one exported key overrides plugin options everywhere, or
- apiKey in the plugin options tuple (["opencode-querit", { "apiKey": "..." }]; least preferred — secrets should not live in config files).
Restart OpenCode. A tool call without a key fails with a message that spells out both options.

The two tools are web_search (live web search with cited results) and web_fetch (full page content for up to 10 URLs). They are additive: OpenCode's built-in websearch/webfetch tools stay available. To steer the model to Querit, mention the tools or restrict the built-ins through permissions.

Test locally before publishing

Until the package is published (or to iterate on it), load the compiled plugin straight from this repository in any OpenCode project:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///D:/work/queirt/querit-plugins/opencode-querit/lib/index.js"]
}

Point the file:// URL at your checkout and restart OpenCode; the tools appear alongside the built-ins. Verify quickly with a web_search call — without a configured key it fails with the actionable "Querit is not configured" message, which confirms the plugin loaded and the tools are wired.

Options

Options go in the plugin tuple in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["opencode-querit", {
      "count": 8,
      "timeRange": "m3",
      "languages": ["english"],
      "excludeDomains": ["pinterest.com", "facebook.com", "instagram.com", "tiktok.com"]
    }]
  ]
}

Key	Default	Meaning
`apiKey`	omitted	Literal Querit API key. Prefer `apiKeyEnv` so no secret enters configuration. The `apiKeyEnv` environment variable always wins when both are set.
`apiKeyEnv`	`QUERIT_API_KEY`	Environment variable holding the Querit API key. A missing value fails the tool call with an actionable message.
`baseURL`	`https://api.querit.ai`	Querit API base; `/v1/search` and `/v1/contents` are appended. Falls back to `$QUERIT_BASE_URL`.
`timeoutMs`	`70000`	Per-request timeout in ms (minimum 1000).
`count`	`5`	Default result count per search (1–20; the API caps at 20). Per-call `count` overrides it.
`timeRange`	none	Relative (`d7`, `w2`, `m3`, `y1`, or any `dN`/`wN`/`mN`/`yN`) or `YYYY-MM-DDtoYYYY-MM-DD` date range.
`countries`	none	Country bias. Valid values: `argentina`, `australia`, `brazil`, `canada`, `colombia`, `france`, `germany`, `india`, `indonesia`, `japan`, `mexico`, `nigeria`, `philippines`, `south korea`, `spain`, `united kingdom`, `united states`.
`languages`	none	Language filter. Valid values: `english`, `japanese`, `korean`, `german`, `french`, `spanish`, `portuguese`.
`includeDomains`	none	Whitelist hostnames; only these domains return results.
`excludeDomains`	none	Blacklist hostnames; these domains never return results.
`includeContent`	`false`	Request sentence-level content excerpts (`needContent`); excerpts are appended to each source's snippet.
`chunksPerDoc`	`1`	Content chunks per result (1–3).
`fetchFormat`	`markdown`	Default format requested from `/v1/contents` for fetch calls: `markdown`, `text`, or `html`. Per-call `format` overrides it.
`fetchCrawlTimeout`	`10`	Per-page crawl timeout in seconds (1–60). Per-call `crawl_timeout` overrides it.
`fetchMaxChars`	`8000`	Cap applied to one fetched page's decoded body, in chars; a cut page is flagged `truncated` in the tool metadata.
`maxOutputChars`	`200000`	Cap on one tool's rendered output, in chars.

Tools

web_search

query:  The web search query.
count:  Maximum results to return (default: 5).

Search filters (domains, time range, region, language, content detail) are persistent defaults from the plugin options; per-call parameters are limited to query and count. Returns raw cited results. The tool description instructs the model to treat everything returned as untrusted web data and to cite the returned URLs.

web_fetch

url:             A single HTTP(S) URL to fetch.
urls:            HTTP(S) URLs to fetch. At most 10 URLs per call.
format:          Returned content format (default: markdown).
crawl_timeout:   Per-page crawl timeout in seconds (default: 10).
include_metadata: Include page metadata such as title and publication time (default: true).

Fetches full page content for up to 10 HTTP(S) URLs. URLs with embedded credentials are rejected, and every fetched page is capped at fetchMaxChars chars.

Mapping

Search results become citeable sources: url ← url, title ← title, snippet ← snippet plus requested sentence excerpts, publishedAt ← page_age. Results are deduplicated by URL and normalized to HTTP(S). Fetch maps each crawled page to its content (text/markdown/html per format); pages without returned content are listed at the end of the output instead of failing the whole call.

Failures surface as tool errors with the API key redacted; responses are size-limited (2 MiB search, 10 MiB contents) and retrieved text is stripped of terminal escape/control sequences and bidi controls before the model sees it.

Safety

Treat every search result and retrieved page as untrusted external data. The tools tell the model this on every call (the rendered output always opens with an untrusted-data warning), and the plugin never follows instructions found in retrieved content.

Development

npm install
npm run check   # typecheck src + tests
npm test        # vitest unit tests
npm run build   # tsc -> lib/
npm run test:live  # live smoke test against the real API (needs QUERIT_API_KEY)

Packaging notes

lib/ is committed: OpenCode loads npm plugins directly from the compiled package, and committing it lets users install from GitHub Release tarballs without a build toolchain. @opencode-ai/plugin is an (optional) peer dependency — OpenCode resolves it at plugin load time; install it as a dev dependency for local builds.

License

MIT