> ## 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.

# Documentation: hosted and repo-backed docs

> Use search, list, and read to find, browse, and read hosted docs and repository-backed docs for indexed packages.

Use `search` to find a topic, `list` to browse pages, and `read` to retrieve a page or section. These tools cover hosted documentation and repository docs.

MCP 0.24.0 replaces `docs_list` and `code_files` with `list`. Refresh your client's tool catalog after updating; hosted availability depends on the deployed version. CLI `docs list` still returns a package's combined documentation catalog.

<AccordionGroup>
  <Accordion id="search" title="search — find documentation by topic">
    `search` is the primary discovery tool for documentation questions. It can search indexed package docs alongside code and symbols, then return documentation hits that chain into `read`.

    Use it when your agent knows the package and topic, such as an option name, guide title, error message, migration note, or API behavior.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest search "middleware error handling" --in npm:express --source docs
    npx githits@latest search "streaming responses" --in pypi:requests --source docs
    ```

    **Key parameters**

    <ParamField query="query" type="string" required>
      Discovery query string. Describe the documentation topic, API, option, behavior, or error message you need.
    </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="source" type="string">
      Set to `docs` when you only want documentation results. Omit it when documentation can be mixed with code and symbol results.
    </ParamField>

    <ParamField query="limit" type="number">
      Maximum results to return.
    </ParamField>

    For hosted documentation hits, pass the emitted `docsReadTarget` URL or fragment unchanged as `target` to `read`, with no `path`. If no `docsReadTarget` is emitted, use the `pageId`. Hosted URLs address mutable current content. For the exact section selected by the backend, request JSON and replay the complete `followUp`, including its target, selector, and bounds. When constructing a read directly from a URL, add bounds only to intentionally select a page-relative range.

    Repository documentation hits use snapshot identity. Since 0.23.0, package-attributed repo docs display the served package target, target-relative path, and line range, matching source code headers. Prefer the generated `followUp` or those exact coordinates; JSON retains snapshot provenance. See [search results](/tools/code-navigation#search) for the current JSON fields.
  </Accordion>

  <Accordion id="list" title="list — browse documentation pages">
    `list` browses the paths in one known package, repository, or hosted documentation site. Since `@githits/mcp` 0.24.0, it replaces the retired `docs_list` and `code_files` MCP tools. Refresh your MCP client's tool catalog after upgrading. The hosted MCP server exposes `list` once GitHits deploys `@githits/mcp` 0.24.0 to it.

    Package and repository targets include documentation files shipped in their source tree. Hosted documentation is a separate inventory. Browse it with an explicit `site:<host[/path]>` target, such as `site:expressjs.com`. `list` does not discover sites for you. For a package's hosted docs, run `search` with `source` set to `docs`, then pass the `site:` target from a `[docs page]` result header to `list`.

    Site text output prints a shared read target in the header when available. Pair listed paths with that target; a full URL row is its own read target. Paths are relative to the supplied `site:` target, and `/` denotes that target's root. A trailing `/` marks a directory; a page path has no trailing `/`, even if its publisher URL does. Use JSON when you need exact entry kinds or per-entry read actions. Pass the `site:` target as `target` and the page path as `path` to `read`. When more entries exist, the output ends with the `after` cursor for the next call.

    To narrow a site inventory, pass target-relative `paths`. A selector with one leading `/` stays within the supplied target, and `/` alone selects its root. Source-only filters such as `languages`, `file_types`, and `intents` do not apply to sites. See the [`list` parameters](/tools/code-navigation#list) for the full reference.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest list site:expressjs.com --limit 20
    npx githits@latest read site:expressjs.com /
    ```

    To list documentation files shipped inside a package or repository, run `list` on that package or repository target, such as `npx githits@latest list npm:express@5.2.1 --recursive`.

    `npx githits@latest docs list` remains available as a legacy CLI browser with its existing behavior.
  </Accordion>

  <Accordion id="read" title="read — read a documentation page">
    `read` accepts a complete documentation locator as `target` with no `path`. Since CLI and MCP 0.23.0, it also accepts an emitted `site:` target plus a target-relative page `path`, with an optional heading `selector`. Hosted clients receive this after the service adopts and deploys MCP 0.23.0.

    Repository documentation resolves to indexed file content with snapshot identity and the [code read response](/tools/code-navigation#read), including its MCP JSON bounds. Hosted/crawled pages use the documentation response described below. A nonempty `path` does not by itself imply source code: a site target still reads hosted documentation.

    URL targets resolve only documentation that GitHits has already indexed. Reading an unknown URL returns a `NOT_FOUND` error and never enqueues crawling.

    A hosted docs URL fragment selects its heading and full subtree through the next equal-or-higher heading. Supplying either `start_line` or `end_line` replaces the fragment with a page-relative range on the same page. Line ranges work the same with URL targets and page IDs. In text mode, the MCP surface returns 150 lines by default and allows explicit ranges up to 300 lines per call; broader ranges truncate and report the returned range. The response carries `totalLines` so the agent can continue reading the next slice when needed. JSON responses retain the `docsReadTarget`, the stable `pageId` for replays, and the provenance `sourceUrl` — and, unlike code JSON, keep the full backend selection instead of applying the 150/300-line cap.

    Since `githits` and `@githits/mcp` 0.22.0, you can pass `selector` with a logical heading ID to read one heading's section. The heading ID is the fragment without `#`, for example `expressjson` for `#expressjson`. Use it when you know the heading ID but the target has no fragment. Do not combine `selector` with a target that already contains a URL fragment. Either explicit bound overrides the heading selection. `selector` also reads indexed code symbols; see the [Code tools page](/tools/code-navigation#read) for symbol reads and their `AMBIGUOUS`, `NOT_FOUND`, and `SNAPSHOT_UNSUPPORTED` outcomes. The hosted MCP server exposes `selector` once GitHits deploys `@githits/mcp` 0.22.0 to it.

    **CLI usage**

    ```bash theme={null}
    npx githits@latest read https://expressjs.com/en/5x/api/express/
    npx githits@latest read https://expressjs.com/en/5x/api/express/ --lines 50-150
    npx githits@latest read https://expressjs.com/en/5x/api/express/#expressjson
    npx githits@latest read <pageId>
    npx githits@latest read https://expressjs.com/en/5x/api/express/ --selector expressjson
    npx githits@latest read <pageId> --selector <heading-id>
    ```

    For a site inventory, use the emitted read action. The following placeholders must be replaced with the target and path returned by `list`:

    ```bash theme={null}
    npx githits@latest list site:expressjs.com --recursive --json
    npx githits@latest read '<read.target>' '<read.path>'
    ```

    `npx githits@latest docs read` remains available with its older flags. Use top-level `read` for site paths, `--selector`, and `--start`/`--end`.

    **Parameters**

    <ParamField query="target" type="string" required>
      Read target from discovery results: an emitted `docsReadTarget` URL (including fragments), historical page ID, or explicit `site:` target with a separate page path. Pass emitted values through unchanged.
    </ParamField>

    <ParamField query="path" type="string">
      Target-relative page path when `target` is an emitted `site:` target. Omit for complete documentation URLs or page IDs. With a package or repository target, this is an exact source file path instead.
    </ParamField>

    <ParamField query="selector" type="string">
      Logical heading ID to read, such as `expressjson`. Returns that heading's section. Do not combine with a URL fragment in `target`. Added in 0.22.0.
    </ParamField>

    <ParamField query="start_line" type="number">
      Starting line (1-indexed). Omit to start at line 1. Setting either bound replaces a URL fragment with a page-relative range.
    </ParamField>

    <ParamField query="end_line" type="number">
      Ending line (inclusive). Must be ≥ `start_line` when both are set. In text mode, omitting it returns 150 lines from `start_line`, and an explicit range may request up to 300 lines. Documentation JSON keeps the backend selection.
    </ParamField>

    <ParamField query="wait_timeout_ms" type="number">
      Validated for compatibility with source reads (0–60,000 ms), but not forwarded to the documentation backend, which has no indexing wait.
    </ParamField>
  </Accordion>
</AccordionGroup>

## MCP tool reference

| MCP tool | CLI command | Purpose |
| - | - | - |
| `search` | `npx githits@latest search` | Find documentation pages by topic, API, option, behavior, or error |
| `list` | `npx githits@latest list` | Browse a package or repository tree, or an explicit hosted documentation site |
| `read` | `npx githits@latest read` | Read a page or heading by URL/page ID, or an emitted site target plus page path |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.