Cynos Tools

Language: English · 简体中文

Search, vision, and browser tools for the pi coding agent.

Requirements

• Node.js 22 or newer
• pi installed and available as pi
• Exa or Tavily API keys are optional; search has a free Exa MCP fallback
• A vision-capable model configured before using cynos_vision

What it gives you

Four capabilities, exposed as pi tools the agent can call directly:

• Web search — cynos_search finds current documentation and references.
• Web fetch — cynos_fetch pulls the full text of public pages.
• Vision — cynos_vision analyzes local image files (screenshots, UI, charts, diagrams) with a vision-capable model.
• Browser automation — cynos_browser_* drives an isolated browser: navigate, interact, capture snapshot/screenshot/console/network evidence, and close.

Install once at the user level and every project gets these tools.

Install

pi install npm:@cynos-ai/tools

Or project-locally (writes to .pi/settings.json, shareable with your team):

pi install npm:@cynos-ai/tools -l

Update or remove:

pi update --extensions       # upgrade all installed packages
pi remove npm:@cynos-ai/tools

Tools

Tool	Purpose
cynos_search	Search the web. Exa REST / Tavily REST (API key), free Exa MCP fallback.
cynos_fetch	Fetch full page content for one or more public http/https URLs.
cynos_vision	Analyze local image files with the configured vision model (describe / ocr / compare / ui).
cynos_browser_navigate	Open a URL in an isolated browser session (localhost allowed for dev servers).
cynos_browser_interact	click / fill / press / select / hover / scroll / wait on the current page.
cynos_browser_inspect	snapshot (element refs) / screenshot / console / requests / eval.
cynos_browser_close	Close the current session's browser.

Commands

• /cynos-tools-config — edit search API keys, vision model, and browser launch options.
• /cynos-tools-browser-setup — probe system browsers; optionally install Chromium.

Configuration

Config lives at ~/.pi/agent/cynos-tools.json:

{
  "schemaVersion": 1,
  "exaApiKey": "optional",
  "tavilyApiKey": "optional",
  "visionModel": "provider/model-id",
  "browser": {
    "channel": "chrome",
    "executablePath": null,
    "headless": true,
    "timeoutMs": 30000
  }
}

exaApiKey / tavilyApiKey may also come from the EXA_API_KEY / TAVILY_API_KEY environment variables; the config file wins. Edit interactively with /cynos-tools-config — no need to touch JSON by hand.

Search providers

Order: user-preferred REST → other configured REST → free Exa MCP. Search works out of the box via MCP even without an API key; configuring Exa or Tavily improves quality and quota.

Vision

cynos_vision runs the configured visionModel in an isolated child process. Configure a vision-capable model via /cynos-tools-config. When the main agent's model does not support image input, Tools reminds the agent to use cynos_vision instead of read (which would fail).

Images are sent to the configured model provider. Don't pass images you cannot send to that provider.

Browser

Browser support is optional so ordinary search/vision installs do not pull in the Playwright runtime. To enable browser tools in a host project, install the optional peer explicitly:

npm install --save-dev playwright-core

Without it, search, vision, and configuration still work; browser calls return a clear setup error instead of failing during Tools startup. Once installed, Tools uses playwright-core and does not bundle a browser. On first use:

1. If a system Chrome / Chromium / Edge is detected, Tools launches it directly.
2. Otherwise Tools returns a clear setup pointer. Run /cynos-tools-browser-setup to probe, or to install Chromium via playwright-core (explicit confirmation required — ~150 MB download).

Each pi session gets an isolated, ephemeral browser context — no persistent profile, no user cookies, no login state.

URL policy:

• Allowed: public http/https, and localhost / 127.0.0.1 / [::1] (for local dev verification).
• Blocked: file:, data:, javascript:, chrome:, devtools:, about:, link-local and cloud-metadata addresses.

Workflow: cynos_browser_navigate → cynos_browser_inspect(action="snapshot") to get element refs → cynos_browser_interact using those refs → cynos_browser_inspect(action="screenshot"|"console"|"requests"|"eval") to capture evidence → cynos_browser_close. Refs are invalidated by navigation, so re-snapshot after navigating.

Security notes

• Browser tools run with your full system permissions and can drive a real browser on your machine. Review what you ask the agent to do.
• eval runs arbitrary JavaScript in the page context and can change page state — treat it as the same trust level as bash.
• API-key config files are written 0600. Never commit them.
• Browser console/network buffers drop request/response bodies and sensitive headers (authorization, cookie, etc.).

Documentation and maintenance

• Contributing
• Security policy
• Changelog
• Third-party notices

License

Cynos Tools is licensed under the MIT License. See THIRD_PARTY_NOTICES.md for upstream notices.