> ## Documentation Index
> Fetch the complete documentation index at: https://docs.githits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Code navigation: search, read, and grep indexed packages

> Search, list, read, and grep source code in any indexed npm, PyPI, GitHub, or other open-source package — no cloning required.

Code navigation gives your agent direct access to the internals of any indexed package or GitHub repository. Your agent can search symbols, list files, read source at exact line ranges, and grep across a dependency — all correctly versioned against what you have installed, without cloning anything.

GitHits indexes average repositories in about 10 seconds. Large repositories like the Linux kernel take 2–5 minutes. After indexing, queries return in sub-second time. When a repository is still being indexed, the response carries a `searchRef` or an `INDEXING` status that you can poll with `search_status`.

**Supported languages for code indexing:** Bash, C#, C++, CSS, Dart, Elixir, Erlang, Go, Java, JavaScript, Kotlin, Lua, Markdown, PHP, Proto, Python, R, Ruby, Rust, Scala, SCSS, Swift, TypeScript, Zig, and more.

<AccordionGroup>
  <Accordion title="search — unified code, docs, and symbol search">
    `search` is the primary discovery tool. It searches across code, documentation, and explicit symbols in any indexed package or GitHub repository. Use it when you need to find where something is defined, which files handle a specific concern, or which docs page explains a behavior.

    Query syntax supports implicit AND, uppercase OR, grouping with parentheses, negation with `-`, quoted phrases, and semantic qualifiers:

    | Qualifier   | Description         | Example             |
    | ----------- | ------------------- | ------------------- |
    | `kind:`     | Symbol kind         | `kind:function`     |
    | `category:` | Symbol category     | `category:callable` |
    | `path:`     | File path component | `path:src/auth`     |
    | `lang:`     | Language            | `lang:typescript`   |
    | `name:`     | Symbol name         | `name:createServer` |
    | `intent:`   | File intent         | `intent:test`       |

    Scope targets with the registry prefix format (`npm:react`, `pypi:requests`) or a full GitHub URL (`https://github.com/expressjs/express`). In the CLI, pass targets with repeatable `--in` flags. In MCP, pass `target` for one target or `targets` for multiple targets.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest search "createServer" --in npm:express
    npx githits@latest search "middleware error handling" --in npm:express@4.18.0
    npx githits@latest search "kind:function authentication" --in https://github.com/supabase/supabase
    npx githits@latest search "pub sub Redis" --in pypi:python-socketio
    ```

    **Key parameters**

    <ParamField query="query" type="string" required>
      Discovery query string. Supports AND (implicit), OR (uppercase), parentheses, `-` negation, quoted phrases, and semantic qualifiers (`kind:`, `category:`, `path:`, `lang:`, `name:`, `intent:`).
    </ParamField>

    <ParamField query="target" type="string">
      Single search target. Package format: `npm:react@18.2.0` or `npm:react` for latest. Repository format: `https://github.com/facebook/react`.
    </ParamField>

    <ParamField query="targets" type="array">
      Multiple search targets. Use either `target` or `targets`, not both.
    </ParamField>

    <ParamField query="source" type="string">
      Restrict results to `code`, `symbol`, or `docs`. Omit to let GitHits choose the best indexed sources. See [Documentation Access](/tools/documentation-access) for docs-focused search, listing, and reading workflows.
    </ParamField>

    <ParamField query="allow_partial_results" type="boolean">
      When `true`, returns hits from sources that finished indexing while others continue, plus a `searchRef` for continuation. Defaults to `false` (waits for all sources).
    </ParamField>

    <ParamField query="limit" type="number">
      Maximum results to return (default 10, max 100).
    </ParamField>

    Each hit's `type` field tells you which follow-up tool to use:

    * `repository_code` or `repository_symbol` → `code_read` with `locator.filePath` (and `locator.startLine`/`endLine` when present)
    * Documentation hits → `docs_read` with the result's `pageId`
  </Accordion>

  <Accordion title="search_status — poll async indexing progress">
    `search_status` lets you follow up on a `search` response that returned a `searchRef` instead of hits. This happens when indexing is still running. Pass the `searchRef` from the prior search response to check progress, fetch partial hits, or retrieve final results.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest search-status <searchRef>
    ```

    **Parameters**

    <ParamField query="search_ref" type="string" required>
      The `searchRef` value from a prior `search` response. Pass it through unchanged (the response field uses camelCase; this parameter uses snake\_case).
    </ParamField>

    <Tip>
      If your original `search` call used `allow_partial_results: true`, the `search_status` response may include hits from sources that have finished so far, with pagination support via `nextOffset`.
    </Tip>
  </Accordion>

  <Accordion title="code_files — list files in an indexed package or repo">
    `code_files` lists the files contained in an indexed dependency or repository. Use it to discover paths before calling `code_read`, to scope a `code_grep`, or to explore the structure of an unfamiliar package.

    Filter results by path prefix, glob patterns, file extensions, programming language, or file intent (production source, tests, examples, generated files, etc.).

    **CLI usage**

    ```bash theme={null}
    npx githits@latest code files npm:express
    npx githits@latest code files npm:express src/
    npx githits@latest code files npm:express --ext ts --ext js
    npx githits@latest code files https://github.com/expressjs/express --file-intent test
    ```

    **Parameters**

    <ParamField query="target" type="object" required>
      Package target (`registry` + `package_name`) or repository target (`repo_url` + optional `git_ref`). Mutually exclusive.
    </ParamField>

    <ParamField query="path_prefix" type="string">
      Literal directory prefix to filter by (e.g., `src/` or `lib/parser`). Not a glob — use `globs` for pattern matching.
    </ParamField>

    <ParamField query="globs" type="array">
      Glob selectors with full glob semantics (e.g., `src/**/*.ts`). Combined with OR logic alongside `path` and `path_prefix`.
    </ParamField>

    <ParamField query="extensions" type="array">
      File extensions to include, without a leading dot (e.g., `["ts", "js"]`). In the CLI, use repeatable `--ext` flags.
    </ParamField>

    <ParamField query="languages" type="array">
      Language filters matching aigrep language names.
    </ParamField>

    <ParamField query="file_intent" type="string">
      Inclusive file-intent filter: `production`, `test`, `benchmark`, `example`, `generated`, `fixture`, `build`, or `vendor`.
    </ParamField>

    <ParamField query="exclude_doc_files" type="boolean">
      Exclude documentation files after inclusive filtering.
    </ParamField>

    <ParamField query="exclude_test_files" type="boolean">
      Exclude test files after inclusive filtering.
    </ParamField>

    <ParamField query="limit" type="number">
      Maximum entries to return (1–1000, default 200).
    </ParamField>

    The JSON envelope shape is `{total, hasMore, files: [{path, name, language, fileType, byteSize}], resolution, indexedVersion}`.
  </Accordion>

  <Accordion title="code_read — read source files at exact line ranges">
    `code_read` reads a specific file from an indexed dependency at exact line ranges. Use the `filePath` from a `search`, `code_grep`, or `code_files` result to target the file, then set `start_line` and `end_line` to fetch only the window you need.

    The MCP surface caps each read at **150 lines per call**. If you request a broader range, the response truncates to 150 lines from your start point and includes a `hint` with the continuation `start_line` for the next call. The CLI command `npx githits@latest code read` has no line cap.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest code read npm:express src/application.js
    npx githits@latest code read npm:express src/application.js --lines 120-200
    npx githits@latest code read https://github.com/expressjs/express lib/router/index.js
    ```

    **Parameters**

    <ParamField query="target" type="object" required>
      Package target (`registry` + `package_name`) or repository target (`repo_url` + optional `git_ref`). Mutually exclusive.
    </ParamField>

    <ParamField query="path" type="string" required>
      Exact file path to read. Use `code_files` to discover paths when you receive a `FILE_NOT_FOUND` error.
    </ParamField>

    <ParamField query="start_line" type="number">
      Starting line (1-indexed). Omit to start at line 1.
    </ParamField>

    <ParamField query="end_line" type="number">
      Ending line (inclusive). When omitted, defaults to `start_line + 149` because the MCP surface caps each read at 150 lines.
    </ParamField>

    <Warning>
      Pick a focused window — typically 80–150 lines around the symbol or grep match you are investigating. Each call beyond the cap costs additional context budget, so aim for one well-sized read per location.
    </Warning>

    Response fields: `{path, language, totalLines, startLine, endLine, content, isBinary, hint?}`. Binary files set `isBinary: true` and omit `content`.
  </Accordion>

  <Accordion title="code_grep — deterministic grep over indexed source">
    `code_grep` runs a deterministic text or regex grep over the indexed source files of a package or repository. Use it when you know the exact string or pattern you are looking for. Use `search` for discovery when you do not.

    Grep results include the matching file path and line number, which chain directly into `code_read` — pass `filePath` as `path` and pick a window around `match.line` for `start_line`/`end_line`.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest code grep npm:express "Router"
    npx githits@latest code grep npm:express "use\(.*middleware" --regex
    npx githits@latest code grep npm:express "createServer" src/ --ext js
    npx githits@latest code grep https://github.com/expressjs/express "response.json"
    ```

    **Parameters**

    <ParamField query="target" type="object" required>
      Package target (`registry` + `package_name`) or repository target (`repo_url` + optional `git_ref`). Mutually exclusive.
    </ParamField>

    <ParamField query="pattern" type="string">
      The text pattern to search for. Literal by default.
    </ParamField>

    <ParamField query="pattern_type" type="string" default="literal">
      `literal` (default) or `regex` (RE2 syntax). In the CLI, pass `--regex` for regex mode.
    </ParamField>

    <ParamField query="path_prefix" type="string">
      Literal directory prefix to scope the grep (e.g., `src/`).
    </ParamField>

    <ParamField query="globs" type="array">
      Glob selectors (e.g., `src/**/*.ts`).
    </ParamField>

    <ParamField query="extensions" type="array">
      File extensions to include, without a leading dot. In the CLI, use repeatable `--ext` flags.
    </ParamField>

    <ParamField query="case_sensitive" type="boolean">
      Case-sensitive matching. Defaults to `false`.
    </ParamField>

    <ParamField query="context_lines" type="number">
      Lines of context before and after each match (equivalent to `grep -C`).
    </ParamField>

    <ParamField query="max_matches" type="number">
      Cap on total matches returned.
    </ParamField>

    <Tip>
      Narrow the grep scope with `path_prefix`, `globs`, or `extensions` to keep responses small. A whole-package grep can return a large number of matches on bigger packages.
    </Tip>
  </Accordion>
</AccordionGroup>

## MCP tool reference

| MCP tool        | CLI command                        | Purpose                                              |
| --------------- | ---------------------------------- | ---------------------------------------------------- |
| `search`        | `npx githits@latest search`        | Unified discovery across code and symbols            |
| `search_status` | `npx githits@latest search-status` | Poll async indexing and fetch results by `searchRef` |
| `code_files`    | `npx githits@latest code files`    | List files in an indexed package or repo             |
| `code_read`     | `npx githits@latest code read`     | Read source at exact line ranges                     |
| `code_grep`     | `npx githits@latest code grep`     | Deterministic text or regex grep over indexed source |