Skip to main content
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.
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: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
Key parameters
​
string
required
Discovery query string. Supports AND (implicit), OR (uppercase), parentheses, - negation, quoted phrases, and semantic qualifiers (kind:, category:, path:, lang:, name:, intent:).
​
string
Single search target. Package format: npm:react@18.2.0 or npm:react for latest. Repository format: https://github.com/facebook/react.
​
array
Multiple search targets. Use either target or targets, not both.
​
string
Restrict results to code, symbol, or docs. Omit to let GitHits choose the best indexed sources. See Documentation Access for docs-focused search, listing, and reading workflows.
​
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).
​
number
Maximum results to return (default 10, max 100).
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
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
Parameters
​
string
required
The searchRef value from a prior search response. Pass it through unchanged (the response field uses camelCase; this parameter uses snake_case).
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.
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
Parameters
​
object
required
Package target (registry + package_name) or repository target (repo_url + optional git_ref). Mutually exclusive.
​
string
Literal directory prefix to filter by (e.g., src/ or lib/parser). Not a glob — use globs for pattern matching.
​
array
Glob selectors with full glob semantics (e.g., src/**/*.ts). Combined with OR logic alongside path and path_prefix.
​
array
File extensions to include, without a leading dot (e.g., ["ts", "js"]). In the CLI, use repeatable --ext flags.
​
array
Language filters matching aigrep language names.
​
string
Inclusive file-intent filter: production, test, benchmark, example, generated, fixture, build, or vendor.
​
boolean
Exclude documentation files after inclusive filtering.
​
boolean
Exclude test files after inclusive filtering.
​
number
Maximum entries to return (1–1000, default 200).
The JSON envelope shape is {total, hasMore, files: [{path, name, language, fileType, byteSize}], resolution, indexedVersion}.
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
Parameters
​
object
required
Package target (registry + package_name) or repository target (repo_url + optional git_ref). Mutually exclusive.
​
string
required
Exact file path to read. Use code_files to discover paths when you receive a FILE_NOT_FOUND error.
​
number
Starting line (1-indexed). Omit to start at line 1.
​
number
Ending line (inclusive). When omitted, defaults to start_line + 149 because the MCP surface caps each read at 150 lines.
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.
Response fields: {path, language, totalLines, startLine, endLine, content, isBinary, hint?}. Binary files set isBinary: true and omit content.
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
Parameters
​
object
required
Package target (registry + package_name) or repository target (repo_url + optional git_ref). Mutually exclusive.
​
string
The text pattern to search for. Literal by default.
​
string
default:"literal"
literal (default) or regex (RE2 syntax). In the CLI, pass --regex for regex mode.
​
string
Literal directory prefix to scope the grep (e.g., src/).
​
array
Glob selectors (e.g., src/**/*.ts).
​
array
File extensions to include, without a leading dot. In the CLI, use repeatable --ext flags.
​
boolean
Case-sensitive matching. Defaults to false.
​
number
Lines of context before and after each match (equivalent to grep -C).
​
number
Cap on total matches returned.
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.

​
MCP tool reference