English · 简体中文

onesearch is a CLI-first research and evidence tool for AI agents, scripts, and terminal users. It unifies answer search, source discovery, documentation lookup, page fetching, site mapping and crawling, repository wiki access, offline research planning, configuration diagnostics, and built-in Skill distribution.

Use explicit CLI workflows with skills show, or connect a host to the local stdio MCP server with onesearch mcp. MCP is implemented in source; npm manifest version 1.0.6 does not contain it. See the MCP guide for local-binary setup before release and npx -y onesearch mcp after a release containing the feature.

Why onesearch

• Explicit routing: task → capability route → provider selection / fallback → normalized result.
• Agent and script contracts: versioned command manifests, strict parsing, compact JSON, and bundled Skills.
• Discovery is not evidence: fetch important sources before treating candidate URLs as verified content.
• Credential redaction: dynamic output and output files are redacted; deep plans locally without provider calls.

Quick start

Examples use PowerShell. npm ships Windows x64, Linux x64, and macOS arm64 binaries; additional builds are available from GitHub Releases.

npm install -g onesearch
onesearch --version
onesearch schema search --format json
onesearch status --format json --pretty

schema is offline and does not create configuration; status initializes missing configuration. A fresh ready: false is not an installation failure. Full search needs answer, documentation, and page-fetch capabilities, for example:

onesearch config setup openai-compatible
onesearch config setup exa
onesearch status --format json --pretty

Interactive prompts hide API keys. Once minimum_profile.ok == true, run:

onesearch search "Explain Go context cancellation patterns" --validation balanced --format json

For public repository research, the default-enabled DeepWiki capability can run independently once capabilities.repo_wiki.ok == true, without completing the full search profile. Readiness is local preflight, not proof of remote reachability. See the getting-started guide for the full path.

Capability map

See the CLI reference for research workflows, documentation, websites, repository commands, and the provider-direct catalog.

Configuration

Configuration defaults to ~/.config/onesearch/config.json; override its directory with ONESEARCH_CONFIG_DIR. See configuration and config.example.json for credentials, routes, profiles, and adapter limits.

Connect onesearch to an agent

Follow agent integration to install a thin host Skill that loads version-matched workflows from the actual binary instead of copying provider contracts.

For native MCP tools instead of CLI execution, follow MCP integration. The server exposes five tools over stdio; configure providers outside MCP and inspect per-operation readiness with onesearch_status. Release, real-host, and live-provider acceptance remain pending.

Development

Build and test with the Go version pinned by mise.toml and go.mod, from the repository root:

mise install
mise exec -- go test ./...
mise exec -- go build -o ./bin/onesearch.exe ./cmd/onesearch
./bin/onesearch.exe --version

On macOS/Linux use ./bin/onesearch as the output and executable path. See the development guide and architecture overview (Chinese) for module boundaries, cache behavior, and release verification.

Documentation

The documentation hub links current user guides in Chinese and English. Design decision records preserve rationale and superseded proposals separately; they are not the current operating manual.

Relative documentation links target a source checkout. Release archives include only this README and the license alongside the executable; visit the GitHub repository for the full documentation.

License

Licensed under the Apache License 2.0.