psearch

Web search for terminals and agents. Parallel Search finds initial pages. Local Chromium fetches pages concurrently. Jev scores the evidence and selects links for a breadth-first queue.

One command provides readable results, JSON output, and an MCP server. The distribution name is jev-psearch. The installed command is psearch. For the Wikipedia game, use jev-bfs.

Install

Use Python 3.11 or later and uv. Install from GitHub:

uv tool install git+https://github.com/komikat/psearch.git
psearch --install-browser

If the shell cannot find psearch, run uv tool update-shell. Then restart the shell. Run psearch --install-browser again after an upgrade. On Linux, install the Playwright system dependencies if needed.

Set the TypeSafe API key:

export JEVON_KEY="your-typesafe-api-key"

You can also put JEVON_KEY=your-typesafe-api-key in a dotenv file. The tool checks these sources in order:

1. The process environment.
2. .env in the current directory.
3. ~/.config/psearch/.env.

The tool also accepts TYPESAFE_API_KEY in these locations. Within one source, JEVON_KEY takes precedence. The global file is useful for MCP clients that do not inherit shell variables.

Parallel Search MCP provides discovery through its free anonymous endpoint. It needs no additional API key, but rate limits apply. Jev calls use your TypeSafe account.

Search from the terminal

Run a search:

psearch "Python asyncio TaskGroup cancellation"

The default output shows titles, URLs, scores, and short source excerpts. Use JSON for full page text, errors, and measurements:

psearch "Python asyncio TaskGroup cancellation" --json

Run independent queries concurrently:

psearch "Python asyncio.gather" "Python asyncio.TaskGroup" --json

A single query returns one JSON object. Multiple queries return an array in input order.

Follow more links with a larger page budget:

psearch "Cloudflare D1 read replication and batch transactions" --depth 3 --max-pages 36

Give Jev up to five pages in each request:

psearch "Cloudflare D1 read replication" --batch-size 5

The browser fetches those pages concurrently. Jev receives one shared context with separate questions for each page and link. The existing --width option is an alias for --batch-size.

Start from known pages:

psearch "How does KV cache missing keys?" \
  --seed https://developers.cloudflare.com/kv/concepts/how-kv-works/

Use psearch --help for all options. Use psearch --version to check the installed version.

Add to an MCP client

The MCP server uses stdio and exposes one tool: search. It starts Chromium on the first search and reuses it until the server stops. Concurrent calls share the browser and API limits.

Add this entry to your client's MCP configuration:

{
  "mcpServers": {
    "psearch": {
      "command": "psearch",
      "args": ["--mcp"]
    }
  }
}

For desktop clients, replace psearch with the absolute executable path if necessary. Find that path with command -v psearch. Configure the key through the global dotenv file or the client's environment settings.

For Claude Code, run:

claude mcp add --scope user --transport stdio psearch -- psearch --mcp

The tool accepts these arguments:

{
  "query": "Cloudflare D1 read replication and batch transactions",
  "depth": 2,
  "max_pages": 24,
  "batch_size": 5
}

Only query is required. The defaults are depth=1, max_pages=12, and batch_size=6. The optional seeds argument accepts an array of starting URLs. The result contains ranked sources, page text, errors, and usage measurements. The server sends protocol messages on stdout and logs on stderr.

Search behavior

The queue completes each depth before it starts a deeper depth. The default batch size and shared concurrency limit are six. Depth zero reads only the initial results. Depth one also follows their links. The page budget counts failed attempts. Increasing the depth does not increase that budget.

Jev evaluates each fetched batch in one request. The state contains all successful pages and their outgoing links. Independent questions refer to each page and link by index. The code ranks the returned scores and adds relevant links to the queue. Failed fetches do not discard the other pages in a batch. Candidates remain queued until visited or the budget is exhausted. The output reports the deepest attempted depth and the remaining candidate count.

Larger batches reduce HTTP requests, but do not guarantee lower latency or token use. The jev_ms value is shared by all pages in one batch. Do not sum those page values to measure total Jev time.

The default probability threshold is 0.5. A relevance score does not establish factual accuracy. The tool returns evidence without generating an answer.

The status is ok, partial, no_results, or error. The CLI returns exit code 1 for error and 2 for invalid arguments or startup failures. Other statuses return exit code 0. Check status and errors when using JSON or MCP.

Limits and data use

The extractor supports HTML pages. It reads the first 8,000 text characters and considers up to 24 links per page. Markdown pages can supply text, but their links are not extracted. Login pages, browser challenges, and delayed rendering can prevent retrieval. Two redirects in the same batch can fetch the same destination.

The query goes to Parallel unless you supply seeds. Page text, the query, and link metadata go to TypeSafe for classification. Chromium runs locally and blocks images, fonts, and media. Keep private URLs out of seeds unless you intend to send their content to TypeSafe.

Develop and build

Install the development environment:

uv sync --locked
uv run psearch --install-browser

Run the tests:

uv run python -m unittest -v test_psearch test_interfaces

The tests use local browser fixtures and simulated API responses. They need no API key or remote API calls. The MCP tests cover stdio discovery, structured results, browser reuse, and shutdown.

Build and validate release files:

uv build
uvx twine check dist/*

The archives exclude credentials, local environments, diagnostics, and comparison artifacts. The version is defined once in psearch.py. Publishing the files to PyPI is a separate step.

License

MIT. See LICENSE.