Skip to content

install.md

Latest commit

 

History

History
220 lines (173 loc) · 10.1 KB

install.md

File metadata and controls

220 lines (173 loc) · 10.1 KB
Raw

Install Wayfinder

Wayfinder finds and validates knowledge in an existing OKF bundle. Its complete native installation includes wayfinder with OKF and Profile validation, the embedding runtime, a verified embedding model and license notices. Indexes are plain files in per-user application data, so no database library is installed. It does not require Dart, GitHub credentials or administrator access.

The install scripts are the installation path. They install the current native release. Set WAYFINDER_VERSION to install another published release, for example 0.0.2.

Install the native runtime

For macOS Apple Silicon or Linux x64:

curl -fsSL https://raw.githubusercontent.com/btwld/wayfinder/main/tool/install.sh | sh

The script installs versioned runtimes under ~/.local/share/wayfinder-runtime and exposes wayfinder through ~/.local/bin. It reports if that command directory needs adding to PATH. Set WAYFINDER_INSTALL_ROOT and WAYFINDER_INSTALL_DIR to absolute paths to choose different locations. It refuses to overwrite commands belonging to another installation method.

For Windows x64, run in PowerShell:

irm https://raw.githubusercontent.com/btwld/wayfinder/main/tool/install.ps1 | iex

Windows runtimes live under %LOCALAPPDATA%\WayfinderRuntime; set WAYFINDER_INSTALL_ROOT to override that directory. The installer adds the new runtime's bin directory to your user PATH. Open a new terminal afterwards. Other operating system/CPU combinations require their own native verification before we provide a prebuilt release.

Each installer verifies the archive SHA-256 and all bundled file checksums before switching commands. Reinstalling repairs missing assets and preserves saved indexes. Previous runtime directories remain available for running processes; they may be deleted after those processes have stopped. These checksums detect corrupt downloads; they are not a claim of code signing or notarization.

Homebrew

Homebrew is not a supported channel. If you installed the old conceptadev/tap/wayfinder formula, run brew uninstall wayfinder so it does not shadow the script's wayfinder.

Use a knowledge bundle

From a project containing knowledge/:

wayfinder --version
wayfinder validate knowledge
wayfinder index
wayfinder search "How do I regain access to my account?"
wayfinder search "How do I regain access to my account?" --bundle knowledge

Validation derives the deterministic gate; contextual Profile judgment remains an agent/reviewer responsibility. Indexing and search require the full runtime bundle, so do not copy just the executable. The source repository's illustrative project is examples/bitwild, whose bundle is examples/bitwild/knowledge; the repository has no root knowledge/ directory. Run wayfinder get examples/bitwild first, because validation reads the Profile from the lock and never fetches it.

Project search/index use the bundle paths in the nearest wayfinder.json, or the conventional knowledge/ folder when no configuration exists. An explicit bundle path still selects one bundle. --bundle filters by its folder name.

Agent skills and MCP

The installer also installs the Wayfinder skill family. When the claude CLI is available it installs the wayfinder Claude Code plugin, which provides the skills and the MCP server; otherwise it copies the skills to ~/.claude/skills. It also copies them to ~/.agents/skills, read by Codex and other Agent Skills clients. Set WAYFINDER_SKILLS to claude, agents or none to narrow or skip this. Wayfinder replaces only skill copies it installed.

wayfinder skills status
wayfinder skills install --agent=agents
wayfinder setup

wayfinder setup adds the MCP server to the current project's .mcp.json as wayfinder mcp, searching all configured project bundles (--bundle=<path> instead binds it to one bundle). That is the command the plugin runs, so Claude Code connects once when both are present. Commit .mcp.json to share it; Claude Code asks for approval before starting project servers.

To change an existing single-bundle entry to project-wide search, run wayfinder setup --force, unset WAYFINDER_KNOWLEDGE_DIR, and restart the MCP host. Bundles still need to be listed in wayfinder.json's applies_to paths; you do not need to name them on each search.

To prompt agents to load use-wayfinder at session start:

wayfinder setup --session-hooks

This adds context-only SessionStart hooks to .claude/settings.json, .codex/hooks.json, and .gemini/settings.json, preserving existing settings and other hooks. Grok reads the same short pointer from a managed block in AGENTS.md; its SessionStart hook ignores stdout. The pointer routes writing, adoption, and audits through use-wayfinder to the other skills. Install the skill family first and review/trust the hooks in each client before use. Startup performs no indexing or update checks. Local hooks apply to local agent sessions; cloud-orchestrated Codex chats do not run project command hooks.

Host contracts: Claude, Codex, and Gemini. Grok's local user guide documents its passive hook output and startup AGENTS.md loading.

wayfinder setup --hooks refreshes the search index after git pulls, checkouts and rebases that change the bundle. Each git hook runs wayfinder index knowledge --detach, which returns at once and re-embeds only changed passages in the background. One background index runs per machine, for at most 30 minutes. Each clone enables the git hooks with git config core.hooksPath .githooks. Otherwise, search reports a stale index, and wayfinder index knowledge or the MCP index tool refreshes it; wayfinder index knowledge --force rebuilds an index from scratch. Both setup flags may be combined: wayfinder setup --session-hooks --hooks.

Install the Claude Code plugin

Install and verify the commands first. From the consuming project, in Claude Code:

/plugin marketplace add btwld/wayfinder
/plugin install wayfinder@wayfinder

The plugin includes the author, adopt, assess and use-wayfinder skill family and registers the Wayfinder MCP server. /mcp should list wayfinder. Its tools are validate, index, search and graph. By default it serves all configured project bundles. Set WAYFINDER_KNOWLEDGE_DIR only to restrict it to one explicit bundle, and WAYFINDER_EXECUTABLE when the executable is outside PATH.

If Claude Code reports that a wayfinder marketplace already exists from an older source, such as a private marketplace or wayfinder-dist, remove the old plugin and marketplace, then run the two commands above again:

/plugin uninstall concepta-knowledge@wayfinder
/plugin marketplace remove wayfinder

If the old plugin is named wayfinder@wayfinder, uninstall that instead. /mcp should then list one Wayfinder server.

wayfinder graph projects the ordinary OKF relationship graph, plus typed relationships edges beside it. Mermaid and DOT output are text for an external preview; Wayfinder does not render a picture. Upstream okf remains a separate optional tool for write and concept-authoring operations. Its Windows binary availability is tracked independently in okf#43.

Upgrade and troubleshoot

Run wayfinder update to install the newest release and refresh the skills and plugin; wayfinder update --check only reports. A Homebrew installation is told to reinstall with the script, and a Dart installation prints its upgrade command. Interactive commands mention a newer release at most once a day, using one GitHub Releases API request that sends no bundle content. It never runs for MCP, CI or non-terminal use; set WAYFINDER_NO_UPDATE_CHECK=1 to disable it everywhere.

Run the installer again to install the newest release, or the one WAYFINDER_VERSION names, and to repair an installation. Restart Claude Code to use the updated executable. An upgrade keeps index data separate from runtime files. WAYFINDER_DATA_DIR selects an explicit data root; model environment overrides are described in the CLI package guide.

If a command is missing, check its installation directory is on the PATH used to launch your terminal or Claude Code. If an asset is missing, rerun the complete installer. If search reports a missing or stale index, run wayfinder index on the same bundle. Preserve any operating-system security warning and inspect the release source; the installer does not disable platform protections.

On Windows, Could not determine this machine's processor architecture means the session's .NET architecture probe returned nothing rather than that the machine is unsupported; some interactive Windows PowerShell 5.1 sessions do this. Install from a clean session instead:

powershell -NoProfile -Command "irm https://raw.githubusercontent.com/btwld/wayfinder/main/tool/install.ps1 | iex"

A message naming a machine, such as Windows Arm64 has no prebuilt Wayfinder bundle or Darwin-x86_64 has no prebuilt Wayfinder bundle, reports a machine both installers did detect and that we do not yet publish a verified bundle for.

To uninstall on macOS/Linux, remove the installer-owned command symlinks and runtime directories. On Windows, remove its recorded runtime bin entry from your user PATH and delete the runtime directory. Remove the plugin separately. Saved indexes are not removed by uninstalling runtime files.

Dart developers

dart pub global activate wayfinder_cli

Global activation supports validation and MCP validation. Retrieval additionally needs the native library/model setup described in the package guide; the complete native installer handles those assets for end users. The reusable library is wayfinder_embeddings.

If wayfinder --version still reports a version before 0.0.1, the old global wayfinder package owns the command. Run dart pub global deactivate wayfinder, then activate wayfinder_cli again.