Wagalo

Wagalo is a local research tool for AI assistants. It searches independent sources, reads pages and documents, keeps the evidence, and exposes the same capabilities through MCP or a local research desk.

Version 0.2.0 adds restartable research jobs, persistent change watches, PDF OCR, retained evidence and exports, a Windows launcher, and standard MCP Streamable HTTP. All 29 existing tools and aliases remain. See capabilities and limits and measured test evidence.

• Search with RRF fusion and ColBERTv2 ranking; provider failures and fallbacks remain visible.

• Read through HTTP, TLS impersonation, Chromium, stealth and challenge-wait steps.

• Keep full extracted text with unique evidence IDs, SHA-256 hashes, retrieval times, signed pagination and PDF page references.

• Pause/resume/cancel research jobs; monitor page changes with durable baselines and history.

• Use the local research desk for jobs, watches, evidence, exports and health. The existing detailed search console remains available.

• Keep research as the default. Explicit action mode, auth vault, named local targets, optional providers and model choices remain supported.

Windows quick start

1. Download the Windows x64 setup ZIP from Releases, or clone this repository.

2. In the extracted folder, run powershell -ExecutionPolicy Bypass -File windows/Install.ps1. A setup ZIP includes Node LTS; source installation bootstraps it when missing. The online installer runs locked npm ci, Chromium installation and a real ColBERT check.

3. Run windows/Start.ps1, then open the research desk. The compiled Wagalo.exe launcher is included in Windows packages.

4. Attach your assistant using the absolute-path stdio example in windows/cordis.patch.yml.example for DSH, or windows/mcp.json.example for compatible hosts.

5. Run windows/Doctor.ps1 to check identity and both MCP transports. Stop with windows/Stop.ps1.

Requirements: Windows x64, PowerShell 5.1+, Node 24 LTS recommended (minimum 22.19.0 when supplying your own). Online installation downloads dependencies, Chromium and about 400 MB of model weights. First scan OCR also downloads English language data. An offline package includes those assets; install it using windows/Install.ps1 -Offline. See Windows delivery.

Operator data defaults to %LOCALAPPDATA%\Wagalo, outside the source folder. Repair, uninstall-startup and rollback retain that data. Do not delete master.key or the vault when upgrading.

Related MCP server: Web Search MCP Server

MCP and usage

The daemon must already be running. Stdio uses node C:/absolute/path/wagalo/bin/wagalo-mcp.mjs. Keep absolute executable, proxy and cwd paths in DSH's Cordis overlay; DSH does not read mcp.json.

• Legacy JSON-RPC bridge: http://127.0.0.1:8787/mcp.

• Genuine Streamable HTTP: http://127.0.0.1:8787/mcp/stream.

• Health: http://127.0.0.1:8787/api/health.

Examples of tool arguments:

{"tool":"web_search","arguments":{"query":"Longmont city council meeting agenda"}}
{"tool":"web_fetch","arguments":{"url":"https://example.com"}}
{"tool":"research_job","arguments":{"action":"create","question":"What changed in the city budget?"}}
{"tool":"watch","arguments":{"url":"https://example.com/agenda","intervalMin":60}}

These show tool names and arguments; an MCP client supplies the surrounding protocol. Use returned evidence IDs and pagination; snippets alone are not full-page evidence.

Configuration

WAGALO_HOME selects operator data. WAGALO_PROFILE=research is the default; action enables explicit click/type. WAGALO_RERANK_MODEL selects a model and WAGALO_RERANK=off keeps lexical ranking available. Brave, Exa and GitHub code search need their respective optional credentials. WAGALO_TOKEN protects HTTP access; binding beyond loopback requires it. Keep credentials in environment/private configuration, never committed YAML.

Optional synthesis is explicitly requested with deep_research / research synthesize:true and requires WAGALO_SYNTHESIS_URL plus WAGALO_SYNTHESIS_MODEL. Original evidence remains available if synthesis fails. References are checked; model claims are not automatically fact-checked.

Linux and macOS

Use Node 22.19+ / 24 LTS, npm ci, npx playwright install chromium, then npm start. In another terminal, npm run mcp starts the stdio proxy. The detailed TanStack console is still available with npm run dev. Windows native containment is tested separately; other platforms use their own process cleanup path.

User manual · Architecture · Research benchmark · Changelog · Contributing · License: AGPL-3.0-or-later