tool-query

tool-query is a Bun CLI for Linux x64 that catalogs invokable commands from PATH, blocks search until every visible command has one-sentence metadata, and then performs semantic capability search with a first-run-downloaded Vulkan llama.cpp runtime plus EmbeddingGemma GGUF.

Runtime Requirements

• Bun >= 1.3.9
• Linux x64
• Vulkan-capable machine for the semantic embedding path

Package

• npm package: @howaboua/tool-query
• CLI binary: tool-query

Install

npm install -g @howaboua/tool-query

tool-query is a Bun-native package. The installed binary uses the bun shebang, so bun must be present on the machine.

On first semantic search, tool-query downloads:

• the Vulkan llama.cpp runtime into ${XDG_CACHE_HOME:-$HOME/.cache}/tool-query/runtime
• the EmbeddingGemma GGUF model into ${XDG_CACHE_HOME:-$HOME/.cache}/tool-query/models

Repo Map

• src/main.ts: entrypoint, exit codes, and stdout JSON envelope.
• src/cli.ts: positional command parsing and JSON payload validation.
• src/app.ts: high-level command orchestration.
• src/command_index.ts: Linux PATH scan and first-match command resolution.
• src/search/: sync-and-gate search flow plus lexical ranking.
• src/store/: SQLite schema, sync, metadata persistence, and validation.
• src/embedder/: config, runtime download, model download, and fingerprint lifecycle.
• src/xdg.ts: cache/config path resolution.

Workflow

1. tool-query search '{"query":"browser automation"}' syncs the current PATH.
2. If any visible command lacks metadata, search returns metadata_required.
3. tool-query describe '{"entries":[{"name":"agent-browser","description":"CLI for browser automation, page interaction, and screenshots."}]}' writes up to five one-sentence descriptions.
4. Once every visible command is documented, tool-query search ... returns matching command names.

Local Checks

Run ./scripts/check.