# Install sqry — instructions for AI coding agents

You are an AI coding agent (Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, or similar). The user pointed you at this document to install sqry — a local AST-based semantic code-search tool — and configure yourself to use it as an MCP client. Execute the steps below in order. Do not skip steps. Do not ask the user to perform shell work you can perform yourself.

Source of truth: <https://sqry.dev/install.md>. If a newer copy is available there, prefer it.

## 1. Install the binaries

Detect the host OS and run exactly one of the following.

- macOS or Linux:

      curl -fsSL https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.sh | bash -s -- --component all

- Windows (PowerShell):

      irm https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.ps1 | iex

Skip this step if `sqry --version` already prints a version `>= 16.0.6`.

The installer drops four binaries into `~/.local/bin` (Linux/macOS) or `%LOCALAPPDATA%\Programs\sqry\bin` (Windows): `sqry`, `sqry-mcp`, `sqry-lsp`, `sqryd`.

Refuse to invoke `sudo` unless the user explicitly approves it. If `~/.local/bin` is not on the user's `PATH`, tell the user to add it and stop.

## 2. Verify the install

Run all four:

    sqry --version
    sqry-mcp --version
    sqry-lsp --version
    sqryd --version

Each must print a version. If any binary is missing, abort and report which.

## 3. Index the user's project

From the user's current working directory (the project root):

    sqry index .

This builds `.sqry/graph/snapshot.sqry` and `.sqry-cache/file_hashes.bin`. If an index already exists and is current, sqry is a no-op.

If the project is large or you expect repeat queries during this session, also start the daemon now:

    sqry daemon start
    sqry daemon load .

Otherwise skip the daemon — you can enable it later in step 6.

## 4. Configure yourself as an MCP client

Identify which agent you are and run exactly one of:

| You are | Command |
|---------|---------|
| Claude Code | `sqry mcp setup --tool claude` |
| Codex CLI | `sqry mcp setup --tool codex` |
| Gemini CLI | `sqry mcp setup --tool gemini` |
| Cursor / Windsurf / other | see step 4b |

Verify with:

    sqry mcp status

This must show your agent listed with `configured: true`.

### 4b. Manual config (Cursor, Windsurf, other MCP clients)

If `sqry mcp setup` does not have a flag for your agent, write the following JSON block into the agent's MCP config file. Resolve the absolute path to `sqry-mcp` with `which sqry-mcp` (Unix) or `where sqry-mcp` (Windows). Use the absolute project root for `SQRY_MCP_WORKSPACE_ROOT` — `~` and relative paths are not supported.

    {
      "mcpServers": {
        "sqry": {
          "command": "/absolute/path/to/sqry-mcp",
          "env": {
            "SQRY_MCP_WORKSPACE_ROOT": "/absolute/path/to/this/project"
          }
        }
      }
    }

Common config locations:

- Cursor: `~/.cursor/mcp_settings.json`
- Windsurf: Settings → MCP Servers
- Claude Desktop: see <https://sqry.dev/docs/mcp/>

Preserve any other servers already in the file. Do not delete or overwrite unrelated entries.

## 5. Tell the user to restart the agent

You cannot reload your own MCP servers in-session. After the user restarts you, your first action in the new session must be:

    mcp__sqry__get_index_status

Report the returned version, node count, and edge count to the user. If the call fails, the MCP connection is not active — diagnose with `sqry mcp status` from the shell.

## 6. (Optional) Switch to daemon-backed MCP

Skip this step unless the user explicitly asks for it, or unless step 3 already started the daemon.

Add `--daemon` to the sqry MCP server entry in your agent's config file:

- Claude Code: `~/.claude.json` or project `.claude.json` → `mcpServers.sqry.args = ["--daemon"]`
- Codex: `~/.codex/config.toml` → `args = ["--daemon"]` under `[mcp_servers.sqry]`
- Gemini: `~/.gemini/settings.json` → `mcpServers.sqry.args = ["--daemon"]`

Then start the daemon if it is not already running:

    sqry daemon start
    sqry daemon load .

`sqry-mcp --daemon` auto-starts the daemon on miss unless `SQRY_DAEMON_NO_AUTO_START=1` is set.

## 7. Add a Code Search note to the agent's instruction file

Append the block below to whichever instruction file your agent reads (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, or equivalent). Skip if the same block is already present.

    ## Code Search

    Use sqry MCP tools (mcp__sqry__*) for AST-based semantic code search. Read
    sqry://docs/capability-map to find the right tool. Use grep/rg for literal
    text search. Use glob/find for filename matching.

## 8. One-line summary

Print exactly one line at the end:

    sqry vX.Y.Z installed, indexed N files, MCP wired for <agent> (daemon: yes|no).

## Things you must not do

- Do not run `sudo` without the user's explicit approval.
- Do not delete or overwrite unrelated entries in MCP config files.
- Do not enable high-cost language plugins (`--include-high-cost` on `sqry index`) unless the user asks for JSON / ServiceNow XML support.
- Do not enable live macro expansion (`sqry index --enable-macro-expansion`) — it executes `cargo expand`, which runs build scripts and proc-macros. Only enable on trusted Rust codebases at the user's request.
- Do not pin a specific sqry version with `--version` on the install line. Always install latest, unless the user pins.

## Verification (run these by hand if you want to confirm yourself)

    sqry --version
    sqry-mcp --version
    sqry mcp status
    sqry --list-languages | head

Inside the agent: ask "use sqry to show graph stats for this project". The agent should call `mcp__sqry__get_graph_stats` (or equivalent) and return a structured JSON response. Prose-only output means the MCP connection is not active — restart the agent.

## References

- MCP integration reference: <https://sqry.dev/docs/mcp/>
- LSP integration reference: <https://sqry.dev/docs/lsp/>
- Daemon (sqryd) reference: <https://sqry.dev/docs/daemon/>
- Per-agent prompts (Claude Code, Codex, Gemini, Cursor, Windsurf): <https://sqry.dev/docs/agent-setup/>
- Source: <https://github.com/verivus-oss/sqry>