# 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](GAP.md) and [measured test evidence](docs/TEST-EVIDENCE.md).

- 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](https://github.com/scottconverse/wagalo/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](http://127.0.0.1:8787/console). 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](windows/cordis.patch.yml.example) for DSH, or [windows/mcp.json.example](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](docs/WINDOWS-DELIVERY.md).

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.

## 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:

```json
{"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](USER-MANUAL.md) · [Architecture](docs/ARCHITECTURE.md) · [Research benchmark](docs/RESEARCH-BENCHMARK.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [License: AGPL-3.0-or-later](LICENSE)