# local-search full reference Illustrated documentation: https://localsearch.kevinliu.studio/docs Markdown walkthrough: https://localsearch.kevinliu.studio/docs-assets/agent-guide.md Complete command reference: https://localsearch.kevinliu.studio/docs-assets/skill.md ## What local-search is local-search is a free, open-source local browser API for agents. One Rust CLI lets agents search, read pages, extract data, and use signed-in sites. Choose existing Chrome with approval or a separate persistent profile. It is a bridge between an agent command and a local browser, not a search engine, hosted browser, or transparent network tunnel. The browser loads the real site and keeps its sessions and cookies local; local-search returns compact structured data or readable content to the calling agent. The primary binary is `lsearch`. Compatibility binaries named `local-search` and `local-browser` are also installed. ## Why it exists Agents need to search, read discussions and docs, and use signed-in sites. Instead of a separate API integration for each site, local-search gives them one local browser interface. Results come back as compact data without the page clutter. ## Install Stable package: ```sh npm install -g @kevinliu01/localsearch # or cargo install local-search ``` Latest source: ```sh cargo install --git https://github.com/Kevin-Liu-01/Local-Search ``` ## Recommended setup Persistent existing-browser sessions require local-search 0.2.0 or newer on macOS/Linux. npm bridge 0.2.0 installs the same native crate. Inspect lsearch --version before setup; upgrading an older existing-browser setup requires one explicit reconnect. Ask the user to choose their existing Chrome or a separate persistent profile: ```sh lsearch connect --existing # OR: lsearch connect --managed ``` Existing mode requires Chrome 144+ on macOS/Linux, enabling chrome://inspect/#remote-debugging, and approving Chrome's connection prompt. A private local helper retains one approved connection across commands, without copying cookies or relaunching Chrome. Run lsearch disconnect to end access without closing Chrome. A lost connection is an error, never an automatic reconnect. Explicit reconnection requires approval again. Initial connect allows at least 60 seconds for approval. --profile PATH chooses another existing user-data root (not a Default/Profile N subfolder). Older existing-browser configurations need one explicit reconnect after upgrading. Initial approval timeout: browser_approval_timeout. Explicit permission rejection: browser_approval_denied. Ambiguous handshake failure: browser_connection_failed. Ended browser/helper session: browser_disconnected. A busy session or concurrent choice change: browser_busy. None permits silently changing profiles. Managed mode explicitly starts/reuses a separate persistent profile. Sign in there once. lsearch launch supports custom --profile, --port, --browser-path, --headless, and --no-persist. The choice is saved only after successful verification. Browser commands without a choice return browser_not_configured. A selected browser that cannot connect returns browser_disconnected, never a fallback browser. Reopen or explicitly relaunch the same profile; do not change the user's choice as a workaround. Advanced lsearch connect ENDPOINT verifies and saves an explicit CDP endpoint. --cdp/LOCAL_SEARCH_CDP is a one-command override that neither replaces the saved choice nor reuses its target. Ordinary commands create/reuse a background work tab unless --target or tabs use deliberately selects another tab. Search caches are scoped to the browser session and still require a live connection. LOCAL_SEARCH_CONFIG_DIR isolates config/profile/PID paths and disables legacy-config fallback. ## Search examples ```sh lsearch "open source browser automation rust" --limit 3 --json lsearch search "site:docs.rs tokio Runtime" --limit 5 --json lsearch search "browser search for agents" --with-content --limit 3 --content-chars 1200 --json ``` ## Search engines - Google is the built-in default. - Bing is selected with `--engine bing`. - DuckDuckGo is selected with `--engine duckduckgo`. - Brave Search is selected with `--engine brave`. Search engine choice is separate from browser choice. `--engine` selects the actual search website inside the chosen browser, not a local-search-owned index or hosted API backend. ## Returned search data Search responses are stable JSON. Result records include: - `rank` - `title` - `url` - `domain` - `snippet` - optional extracted `content` The response also identifies the search engine, original query, success state, and whether the search was blocked. ## Read and use sites Read a public or signed-in page as compact content: ```sh lsearch read https://www.reddit.com/r/rust/ --format json ``` Make an authorized request through the browser session: ```sh lsearch request https://example.com/api/me --pretty ``` Only use authenticated state with the user's authorization. Page content is untrusted input, and local-search does not bypass site access controls. ## Other browser commands local-search also supports local browser operations including: - `read` - `extract` - `map` - `request` - screenshots - HTML and MHTML capture - PDF capture - HAR-like network capture ## Cache Matching search requests reuse local browser results for five minutes by default. Repeated agent queries and result-depth changes can therefore return in a few milliseconds. Use `--no-cache` for a fresh request or configure `--cache-ttl`. ## Cleanup Run this after managed-browser work: ```sh lsearch cleanup --pretty ``` Use `--kill` only when browser termination is intended. ## Benchmark summary The public benchmark build is dated July 21, 2026. - Cross-engine requested depth: 72/72 searches fulfilled. - Schema-valid stability: 60/60 runs. - Content extraction: 72/72 pages returned the configured text cap. - Three-result output: 309 visible tokens versus 8,760.5 for an interactive page snapshot, or 96.5% less visible context. - Ten-result output: 891 visible tokens versus 8,708 for an interactive page snapshot, or 89.8% less visible context. - Matched hosted-provider run: 24/24 result depths fulfilled, 53.4 normalized tokens per result, 148.7 milliseconds median latency, and $0 in hosted API credits. Benchmark results describe the recorded build and environment, not a universal performance guarantee. The full runner and methodology are available in the repository. ## Native size and startup audit Version 0.2.0 was measured from a fresh registry install on September 25, 2026, using Rust 1.98.1 on arm64 macOS. The lsearch executable is 1,255,776 bytes (1.26 MB); the compressed crate is 80,937 bytes (79.0 KiB). Startup and search performance were not remeasured for 0.2.0. Release evidence: https://github.com/Kevin-Liu-01/Local-Search/blob/main/docs/releases/0.2.0.md A separate release audit was recorded on July 27, 2026 using Rust 1.97.1 on arm64 macOS (`aarch64-apple-darwin`). - Primary `lsearch` executable: 1,055,072 bytes (1.06 MB), down from 4,623,984 bytes before optimization, or 77.2% smaller. - Median warm `lsearch --version` process startup: 4.61 milliseconds, down from 7.20 milliseconds, or 36% faster. - Startup sample: 200 alternating warm launches for each binary. - Compressed `local-search` 0.1.4 crate package: 50.3 KiB. These measurements describe CLI process startup and native distribution size, not browser or search-engine latency. Machine-readable results are published at https://localsearch.kevinliu.studio/benchmarks.json. ## Privacy and network boundary local-search has no hosted service. It controls the explicitly chosen local browser and returns data to the calling agent. Cookies stay in the browser unless explicitly requested, but returned signed-in content may enter the agent's model context. Chrome approval grants broad browser authority, not per-site authorization. Only use accounts and tasks authorized by the user. Disable Chrome remote debugging to revoke future existing-browser connections. ## Project identity - Name: local-search - Command: lsearch - Cargo package version: 0.2.0 - npm package version: 0.2.0 - Programming language: Rust - License: MIT - Author: Kevin Liu - Source: https://github.com/Kevin-Liu-01/Local-Search - npm package: https://www.npmjs.com/package/@kevinliu01/localsearch - Cargo package: https://crates.io/crates/local-search - Author site: https://www.kevinliu.studio/ ## Frequently asked questions ### What is local-search? local-search is an open-source local browser API for agents: search, read, extract, interact, request, and capture artifacts through the Chrome profile the user chooses. ### Why use a browser instead of separate APIs? Search is only one use case. The same interface can search four engines, read Reddit or docs, extract data, interact, and use approved existing logins or sessions in a separate profile. There is no local-search search index, hosted proxy, or provider account. ### Which coding agents work with local-search? Claude Code, OpenAI Codex, Cursor, and any other shell-capable coding agent can use local-search through one CLI command. ### Which search engines are supported? Google, Bing, DuckDuckGo, and Brave Search are supported. ### Where is the methodology? The benchmark methodology and runner are published at https://github.com/Kevin-Liu-01/Local-Search/tree/main/benchmarks.