GitHits

get_example

Use when the user needs a canonical open-source example, usage pattern, or API snippet that is not tied to one already-known dependency/repository. Best for "how do I use X", cross-project patterns, up-to-date examples, or when package-scoped search was not enough. For inspecting a specific known package or repository, use search, code_, or docs_ instead. Default output is markdown, with source repository provenance when available and a trailing solution_id: ... line when available. When presenting an example to a user, report the source repositories/citations from GitHits' generated references/provenance section whenever present; they are core evidence, not optional metadata. Pass format: "json" for {result, solution_id?}. Pass solution_id to feedback after using or rejecting the example. For searching indexed dependency and repository code/docs, use the unified search tool instead.

search_language

Use before get_example only when you need to force a language and are unsure of GitHits' exact language name. Finds supported language names and aliases; returns up to 5 matches. Default output is one language per line; pass format: "json" for the structured array.

feedback

Use after a GitHits result was helpful, unhelpful, wrong, incomplete, slow, or confusing. Submit feedback on a tool result or the GitHits experience. Two modes: 1. Solution-tied — pass the solution_id from a prior get_example response to rate that specific result. 2. Generic — omit solution_id to send session feedback about any tool (search, code_grep, code_read, code_files, docs_, pkg_) or the overall experience. accepted is always required (true = positive, false = negative). Add feedback_text for context — strongly recommended in generic mode. Pass tool_name when rating a specific tool result. Feeds ranking and product quality.

search

Use when investigating a known package or repository and you need to discover relevant docs, source files, examples, tests, or APIs before reading exact files. Search indexed dependency and repository code, docs, and explicit symbols. Required: query plus either target or targets; pass target or targets, not both. Omit source to let GitHits select the best sources; set it only to restrict results to docs, code, or symbols. Structured parameters combine with the query using AND semantics. For source:"docs", code/symbol-only filters (category, kind, file_intent, public_only) are ignored because docs search does not support them. Complete by default — if indexing is still running, the response carries a searchRef and no hits; pass it to search_status to follow up. Set allow_partial_results: true to opt into hits from sources that finished while others continue indexing. Each hit's type tells you the follow-up tool: documentation_page and repository_doc → docs_read with locator.pageId; repository_code and repository_symbol → code_read with locator.filePath (and locator.startLine/endLine when present).

search_status

Use only after search returns a searchRef. Check progress, fetch partial hits (when the original request used allow_partial_results: true), or fetch final results for a prior search that returned a searchRef. Pass the searchRef from that response as search_ref here (response field is camelCase; this parameter is snake_case).

code_files

List files in an indexed dependency. First choice for file/path enumeration tasks such as files under a directory; use path_prefix for directory prefixes (e.g. lib/) and optional extensions for language filtering. Use this to discover paths before code_read (when code_read returns FILE_NOT_FOUND or you don't yet know the path) and to scope code_grep. Address via target.registry + target.package_name (package scope) or target.repo_url + optional target.git_ref (repo scope), mutually exclusive. Narrow with path, path_prefix, globs, extensions, file_types, languages, or file-intent filters. JSON envelope shape: {total, hasMore, files: [{path, name, language, fileType, byteSize}], resolution, indexedVersion}. When fresh data is not ready within the wait window, responses may include targetResolution provenance, indexingEstimate, and immediately-queryable alternatives. availableVersions and availableRefs are already indexed/queryable; suggestedRefs are fuzzy ref hints and may need indexing first. On an INDEXING error envelope, retry with a longer wait_timeout_ms or use a version/ref from details.availableVersions / details.availableRefs.

code_read

Read one exact file from an indexed dependency; it does not list directories. Use code_files with path_prefix for file/path enumeration. MCP cap: 150 lines per call — broader requests (or no range) silently truncate to the first 150 lines from your start, with a hint describing what was returned vs. requested. Pick a focused window from a search / code_grep match. Response: {path, language, totalLines, startLine, endLine, content, isBinary, hint?}. Binary files set isBinary: true and omit content. Pass the same path emitted by code_files. Address via target.registry + target.package_name (package scope) or target.repo_url + optional target.git_ref (repo scope), mutually exclusive. When fresh data is not ready within the wait window, responses may include targetResolution provenance, indexingEstimate, and immediately-queryable alternatives. availableVersions and availableRefs are already indexed/queryable; suggestedRefs are fuzzy ref hints and may need indexing first. On INDEXING retry with a longer wait_timeout_ms or use a version/ref from error details. On NOT_FOUND / FILE_NOT_FOUND call code_files to discover the actual path.

code_grep

Deterministic text or regex grep over indexed dependency and repository source files. Use this when you know the pattern (literal by default; pass pattern_type: "regex" for RE2). Use search for discovery instead. Whole-target grep is the default — narrow with path, path_prefix, globs, or extensions to keep responses small. Each match's filePath (or text file heading) chains into code_read.path; pick a window around match.line for code_read.start_line / end_line. When fresh data is not ready within the wait window, responses may include targetResolution provenance, indexingEstimate, and immediately-queryable alternatives in error details. availableVersions and availableRefs are already indexed/queryable; suggestedRefs are fuzzy ref hints and may need indexing first.

docs_list

List mixed package documentation pages from hosted docs and repository-backed docs. This browses available pages; for topic search, use search with source: "docs" and pass the returned pageId to docs_read. Every entry includes a stable pageId, sourceKind (crawled or repo), and source URL; repo-backed entries also expose repoUrl / gitRef / filePath for exact file reads. Pass a returned pageId to docs_read. Use this to browse before reading a full page.

docs_read

Read a documentation page by page ID. Works for both hosted/crawled docs and repository-backed docs. Pass start_line / end_line to fetch only a slice when a page is too long — response carries totalLines so you can target the next slice. Repo-backed results additionally include exact file follow-up metadata for code_read.

pkg_info

Use for a quick latest-version package adoption or health check: license, description, repository health, downloads, publish age, and latest vulnerability status. Latest-version package overview for dependency triage. Provide registry and package_name (for example npm + express). Default text returns license, description, repository popularity (stars/forks/issues and [ARCHIVED] when applicable), downloads, publish age, and vulnerability status. Set verbose: true for GitHub language/topics/last-pushed, recent advisories, and recent changes. Pass format: "json" for structured fields. Use pkg_vulns for version-specific vulnerability details.

pkg_vulns

Use when the user asks whether a package or pinned version has known vulnerabilities, advisories, CVEs, malware, affected ranges, or fix versions. Check known vulnerabilities for a package on npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, RubyGems, Go, or Swift (vcpkg and Zig are not supported for vulnerability data). Returns a count summary, each advisory with OSV ID, severity, affected ranges, and fix versions. Malicious-package advisories surface in a separate bucket. Example: {"registry":"npm","package_name":"lodash","version":"4.17.20","min_severity":"high"}. Pass version to inspect a pinned release; omit it for latest. Default text is capped for readability; use verbose:true for all selected advisory rows or format:"json" for the complete envelope. Use min_severity to filter to a threshold (low, medium, high, critical) and include_withdrawn to also see retracted advisories. Use advisory_scope:"non_affecting" to list historical advisories that do not affect the inspected version, or advisory_scope:"all" to list affected and historical advisories together.

pkg_deps

Use when the user asks what a package depends on, wants dependency groups, or needs a bounded transitive dependency footprint. Analyze a package's dependency graph. Lists direct runtime dependencies with resolved versions; non-runtime groups are omitted by default. Use lifecycle with a concrete value for matching dependency groups, or all for every available group. Runtime group rows include resolved versions when available. Pass max_depth to add a transitive block with the capped install footprint, conflict detection, and circular-dependency flags; layer include_importers: true on top when you also need per-package provenance. Supports npm, PyPI, Hex, Crates, Zig, vcpkg, RubyGems, Go, and Swift.

pkg_changelog

Use when the user asks what changed in a package, wants release notes, or needs changelog evidence for a manual upgrade review. Release notes for a package or GitHub repo, newest-first. Default latest mode returns the ten most recent entries (limit 1–50). With from_version, returns every entry in the [from_version, to_version] range (range mode, no count cap). Address via registry + package_name or repo_url (mutually exclusive). Response includes optional source ("releases" / "changelog_file" / "hexdocs") when a concrete changelog source exists, mode ("latest" or "range"), and entries with markdown body previews. Example: {"registry":"npm","package_name":"express","limit":2}. Text output previews 10 body lines by default; use body_lines to tune the preview or verbose:true for full text bodies. Set omit_bodies: true for a version / date / URL timeline only; pass format: "json" for the complete structured envelope. Package-version entries without changelog text succeed with source omitted; no-source plus no entries returns NOT_FOUND. Supports npm, PyPI, Hex, Crates, NuGet, Maven, Zig, vcpkg, Packagist, RubyGems, Go, and Swift.

pkg_upgrade_review

Use when the user asks whether to accept, assess, review, or investigate a dependency update from one version to another. Report package-upgrade evidence by comparing current and target versions with direct vulnerability checks, changelog range evidence, target deprecation metadata, peer dependency changes, and optional transitive evidence diffs. The tool reports facts only and does not assign risk or decide whether to accept an upgrade. Use this instead of inferring acceptability from semver, including patch bumps. Accepts either one package via registry/package_name/current_version/target_version or batch packages[]. Batch execution is capped internally to avoid flooding the package-intelligence backend.