Skip to main content
The Code tools let your agent search indexed public packages and repositories, grep source, list files, read exact lines, and find implementation examples. Source navigation can target a specific package version or repository ref. get_example finds prior art and current patterns without version-pinned inspection. Since githits and @githits/mcp 0.17.0, the MCP surface exposes a single read tool that reads both source files and documentation pages. See the read accordion below. If you upgrade an existing MCP client, refresh its tool catalog so the client discovers read and drops the retired code_read and docs_read entries. 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 and an active status (PENDING, INDEXING, or SEARCHING) that you can poll with search_status. Some responses also include provisional hits you can use immediately while indexing continues. 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 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).
Provisional resultsWhile a target is still indexing, search can return provisional repository-code evidence. Provisional hits come from an exact-commit snapshot and are immediately usable, but the session is not finished. The response marks the evidence as still indexing, reports the exact served identity and PROVISIONAL freshness instead of the ref you requested, and keeps the active searchRef so you can continue with search_status.Semantic match evidenceRepository code and repository docs hits render authoritative match evidence: the enclosing declaration scopes around the match, followed by the exact matched source with its original line numbers:
  • The header carries the read target, path, and matched line range. Package hits pair the registry, package, and version with the package-relative path. Repository hits pair the repository with its exact served commit and the repository-root path.
  • Scope rows list the enclosing declarations outer-to-inner, each with its kind, qualified name, and inclusive declaration line range. Pick your follow-up read range directly from these rows: the header range for the local match context, or an enclosing declaration range for the full definition. No separate per-hit read command is printed.
  • Source lines keep their original numbering, indentation, and boundaries. A > gutter marks lines that contain matches and stays visible without color. Omitted lines, cropped long lines, truncated scope chains, and incompletely highlighted matches carry explicit ASCII notices.
Search text only shows source the backend proved matched:
  • A repository hit without proven matched source renders as a single candidate header line. No source lines, scope rows, or summary appear under it:
    • The line range is the backend’s bounded read window. Use it as a place to inspect with read. It does not prove the match location.
    • For a bare identifier query, visible terms: lists the query fragments (split on camel case and underscores) visible in the title or displayed path when those indexed fields contributed to the hit. If no fragment is visible, the header names the contributing indexed fields instead, for example indexed: path/identifiers. If field provenance is unknown, the header shows only candidate.
    • When a known declaration in the same file contains the window, the header ends with its kind and qualified name, for example - interface AuthSessionStore.
    • visible terms are substrings observed in the returned text. They do not prove a match and do not explain the ranking.
  • Older results without repository evidence still show Snippet unavailable and keep their locators.
  • Crawled documentation pages use a structural preview of the page with match highlighting instead of source lines.
  • Explicit symbol hits show qualified identity with signature detail, kind, and any differing definition range, without a summary body.
In JSON output, each repository hit’s locator keeps the legacy filePath, startLine, and endLine and adds:
  • commitSha — the exact served revision
  • repositoryFilePath — the repository-root path (as opposed to the target-relative filePath)
  • evidenceRange — the focused match range
  • indexedRange — the originally indexed range
  • symbolContext — the enclosing symbol’s name, optional qualifiedPath and kind, and a normalized lowercase relation: encloses_match (a proven enclosing definition, always with a complete definitionRange) or associated_with_indexed_chunk (associated context, definitionRange optional)
JSON hits additionally carry the structured evidence behind the text rendering:
  • repositoryEvidence.semanticContext — the enclosing declaration scopes (outer-to-inner, with kind, qualified path, inclusive declaration ranges, parameter names, and return type) and a preferredRead locator with exact attributed read coordinates
  • repositoryEvidence.matchedSource — the proven numbered source: inclusive line bounds, match anchor, range kind, per-line text with grapheme-offset highlights, and crop/omission flags
  • repositoryEvidence.bm25MatchFields — the indexed fields that contributed matches (SYMBOL_NAME, FILE_PATH, DOCUMENTATION, SOURCE_IDENTIFIER). A known list is complete and ordered; null means the breakdown is unknown, not that nothing matched.
  • documentationPreview — the structural preview text and highlight ranges for crawled documentation hits
Since 0.23.0, search and search_status no longer emit summary, highlights.summary, hit contentSafety, or repositoryEvidence.focusedSource. JSON consumers must use matchedSource, indexed-field provenance, semantic context, and documentationPreview as appropriate. A candidate header is a navigation aid; inspect its bounded window before treating it as a source match.Repository hits also provide a followUp read command. Prefer this emitted action so the target, path, and bounds stay consistent. Package-attributed repository code and docs use the served package target and target-relative path; repository targets retain the served revision and repository-root path. JSON keeps snapshot provenance. When a preferred range exceeds the 300-line MCP read cap, the generated command requests a bounded window while the structured ranges remain unchanged.Search text does not print a read command under each hit. Use the target and location from the header for direct reads. For the exact backend-selected section, request JSON and replay the complete followUp, including its target, path, selector, and bounds.Follow-up toolsEach hit’s type field tells you which follow-up tool to use:
  • repository_code or repository_symbol → read with the compact target and exact path. In text output, build the call from the hit header and scope rows. In JSON, prefer the hit’s followUp command, which reads the preferred range at the exact served revision.
  • Repository documentation hits → use the emitted followUp, or the target, path, and range in the text header. These reads return indexed file content.
  • Hosted documentation hits → read with the result’s docsReadTarget as target (and no path), or its pageId when no target is emitted.
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.Session statesEvery search and search_status response reports a session status. The status set is open: the backend can introduce new values, and clients preserve them instead of rejecting the response.DEFERRED is terminal on both the initial search response and search_status progress. It means background lifecycle work continues outside the session, so the searchRef no longer advances. Any hits already disclosed remain valid evidence.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).
​
number
Maximum time to wait for progress, 0–120,000 milliseconds (default 30,000). The 120-second ceiling matches the upstream HTTP deadline; GitHits picks a longer wait automatically when the response carries indexing-time estimates.
​
string
default:"text"
text (default) for compact output, or json for the structured result. The former text-v1 value is no longer accepted; omit the parameter or pass text instead.
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.
grep searches ordered package, repository, and hosted documentation targets for a known pattern. Use search for topics, list to find paths, and read for more context.Since @githits/mcp 0.25.0, grep replaces code_grep. Refresh local MCP tool discovery and migrate the arguments; this is not just a rename. Hosted availability depends on the deployed server version. CLI githits grep was added in 0.24.0; legacy githits code grep remains available with its older flags and defaults.The defaults are RE2 regex, case-sensitive matching, zero context lines, and all indexed repository files. To preserve the old literal, case-insensitive behavior, set pattern_type: "literal" and ignore_case: true explicitly.MCP example
Package targets also include their selected hosted documentation. corpus and path_selectors filter repository files only; they do not exclude a package’s hosted docs. Site entries accept only target.CLI usage
See the grep CLI reference for all flags.Parameters
​
array
required
One to 20 ordered objects. Each contains target, plus optional corpus (source, documentation, or all) and path_selectors for package or repository targets. Each path selector has kind (exact, prefix, or glob) and value; selectors form a union relative to that target’s root. Omit both controls for site: targets.
​
string
required
Pattern of 1–200 UTF-8 bytes. RE2 regex does not support lookaround or backreferences; multi-file regex requires a literal anchor. Unsupported patterns fail explicitly.
​
string
default:"regex"
regex or literal substring matching.
​
boolean
default:"false"
Set to true for case-insensitive matching with Unicode folding.
​
number
default:"0"
Lines before each match, 0–10.
​
number
default:"0"
Lines after each match, 0–10.
​
number
default:"100"
Maximum occurrences across all scopes on this page, 1–1000. This is a global cap, not a per-file limit.
​
string
Opaque continuation cursor. Reuse the same ordered targets, pattern, and matching controls. Empty starts the first page. Restart without a cursor if it expires.
​
number
default:"0"
First-page preparation wait in milliseconds, 0–300,000. Continuation never waits.
​
string
default:"text"
text for grouped matches, read locators, coverage, and continuation guidance. Use json for detailed hit and scope fields, read actions, and byte coordinates.
Text groups matches under numbered file or page headers. Use the emitted read locator and line numbers for more context. Match rows use : after the line number; context rows use -. Coverage and counts describe this page only. A small match cap can leave scopes unvisited; follow the returned cursor to continue. Hosted pages may change between grep and read.
list lists the files and documentation paths in one known package, repository, or hosted documentation site. Use it to discover paths before calling read, to scope a grep, or to explore the structure of an unfamiliar package. Use search instead when your agent knows the topic.Since @githits/mcp 0.24.0, list replaces the retired code_files and docs_list MCP tools. If you upgrade an existing MCP client, refresh its tool catalog so it discovers list. The hosted MCP server exposes list once GitHits deploys @githits/mcp 0.24.0 to it.A package target covers that package’s own source tree. A repository target covers the whole snapshot. Both include source and documentation files. Hosted documentation is a separate inventory that requires an explicit site: target. See Documentation for site inventories.Select entries with paths. Each entry is a target-relative literal path or glob, and multiple entries form a union. Selected directories show their immediate children unless recursive is true. Glob depth is independent of recursion.Text output starts with a # source <target> header and a read <target> $path follow-up hint, followed by one path per line. Directory entries end in /. When more entries exist, the output ends with the after cursor to pass on the next call. Reuse the same target, paths, and options with that cursor, and treat it as opaque.
CLI usage
npx githits@latest code files is deprecated but keeps its existing behavior for compatibility. See the list command for all CLI flags.Parameters
​
string
required
Package such as npm:express@5.2.1, repository such as github:expressjs/express, or hosted docs site such as site:expressjs.com.
​
array
Target-relative literal paths or globs, such as ["lib/", "lib/**/*.js"]. Entries form a union. Omit or pass [] to browse the root.
​
boolean
Expand selected directories to all descendant files. Without it, selected directories show immediate children.
​
array
Source inventories only. Case-insensitive classifications such as source or doc. Use paths globs for extensions.
​
array
Source inventories only. Case-insensitive language names such as javascript or typescript.
​
array
Source inventories only. File intents: PRODUCTION, TEST, BENCHMARK, EXAMPLE, GENERATED, FIXTURE, BUILD, or VENDOR.
​
number
Maximum entries to return (1–500).
​
string
Opaque nextCursor from a prior list response. Reuse the same target, paths, filters, recursion, and limit.
​
number
Maximum wait for source indexing in milliseconds (0–300,000).
​
string
text (default) or json. Use json for exact entry kinds (FILE, PAGE, or DIRECTORY), read and browse actions, lifecycle metadata, and nextCursor.
read is the one advertised reader on the MCP surface. Pass a package or repository target and exact path to read a file, including repository documentation. For hosted documentation, pass a page locator alone or, since 0.23.0, an emitted site: target plus its target-relative page path. The resolved result determines code or documentation presentation. See Documentation for hosted page reads.Use the read locator from search, grep, or list to target a file, then set start_line and end_line to fetch only the window you need. Repository search hits supply read coordinates directly: the hit header and scope rows in text output, or the ready-made followUp read command in JSON, both pinned to the exact served revision.Since githits and @githits/mcp 0.22.0, you can pass selector to read an indexed code symbol, such as a function or class name, without knowing its line range. A symbol read returns the symbol’s indexed definition range by default. Add path to restrict the lookup to that exact file, or omit it to search the whole code target. path always means an exact target-relative file. Either explicit bound overrides the definition range. The hosted MCP server exposes selector once GitHits deploys @githits/mcp 0.22.0 to it.When a symbol selection returns no source, the response carries a typed status with recovery guidance:
  • AMBIGUOUS: several indexed symbols match. The response lists up to 10 candidates. Retry with one candidate’s exact path.
  • NOT_FOUND: no indexed symbol matches. The response lists up to 10 suggestions. Retry with a suggestion, or locate the symbol with search.
  • SNAPSHOT_UNSUPPORTED: the indexed snapshot does not support symbol selection. Find the definition with search or grep, then read the exact path with start_line and end_line.
The MCP surface returns 150 lines by default and allows explicit ranges up to 300 lines per call. When you omit end_line, the read returns 150 lines from your start point. When you pass an explicit start_line/end_line range, the read honors it up to 300 lines. Broader ranges truncate and include a hint describing what was returned versus requested, with the continuation start_line for the next call. The CLI command npx githits@latest read has no line cap for piping.CLI usage
With --repo-url and --selector, pass at most one positional path. The CLI rejects an extra path argument.CLI 0.22.1 and MCP 0.22.0 also support compact target#symbol reads, with an optional exact path. Do not combine a compact fragment with selector.The npx githits@latest code read and npx githits@latest docs read commands remain available as deprecated commands with their existing flags. Use top-level read for site paths, compact symbol targets, and --selector.Parameters
​
string
required
With path: a compact package or repository target, or an emitted site: target for hosted documentation. Without path: a documentation locator, a compact target#symbol, or a code target with selector. Pass emitted locators through unchanged.
​
string
Exact package- or repository-relative file path from discovery results, or a target-relative page path for an explicit site: target. Omit when passing a complete documentation locator; an empty string counts as omitted. Use list to discover source paths.
​
string
Indexed code symbol name, or a logical documentation heading ID. With a code path, searches only that exact file; with a site path, selects a hosted heading. Without a code path, searches the whole code target. Selected code returns its definition range unless you set a bound. Do not combine with a URL fragment or compact target#symbol.
​
number
Starting line (1-indexed). For code reads, omit to start at line 1. For documentation pages, either bound replaces a URL fragment with a page-relative range.
​
number
Ending line (inclusive). Must be ≥ start_line when both are set. Text output returns 150 lines without an end, up to 300 with one. Code JSON is also bounded; documentation JSON preserves the backend selection.
​
number
Code indexing wait, 0–60,000 ms (default 30,000). Validated for documentation reads but not forwarded, because the docs backend has no indexing wait.
Read only the lines you need — a focused window around the symbol or grep match you are investigating. The 150-line default keeps reads focused; use an explicit range up to 300 lines when you know the required bounds, such as reading a modest whole file without pagination. Each retry costs additional context budget, so aim for one well-sized read per location.
Response fields for code reads: {path, language, totalLines, startLine, endLine, content, isBinary, hint?}. Binary files set isBinary: true and omit content. Documentation reads keep their existing docs-side response shape.
get_example is part of the Code category. Use it when your agent needs prior art or implementation patterns from open-source repositories, issues, discussions, and pull requests, and does not need to inspect a specific package version or repository ref.The get_example MCP tool and its CLI counterpart npx githits@latest example accept a plain-language query and return an implementation example with source citations.
Code examples are not version-aware. Use search, grep, list, and read when your agent needs to inspect a specific package version or repository ref.
How agents use itYour agent calls get_example automatically when it is stuck on an unfamiliar API, needs to validate a pattern, or encounters an error it cannot resolve from training data. You do not need to prompt it manually — once GitHits is connected via MCP, the agent decides when to reach for the tool.You can also trigger it explicitly from the CLI for manual research or to give your agent a head start with fresh context:
When using the CLI, pass --lang to force a language and --license to choose the license filter. The MCP parameters are named language and license_mode.Parameters
​
string
required
Natural-language description of the code pattern or API usage you need. Write it the way you would describe the problem to a colleague — for example, "broadcast messages to specific rooms using python-socketio with Redis as the message queue backend".
​
string
Optional programming language. Omit it to let GitHits infer the language from your query. If GitHits cannot match it, retry with a suggested language from the error, or omit this parameter.
​
string
default:"strict"
Controls license filtering for implementation examples only. Use strict by default, yolo for unfiltered research, or custom for your configured blocklist at githits.com.
Example outputThe following query asks for a Python Redis pub/sub pattern. GitHits returns an implementation example alongside citations showing where that prior art appears in the open-source ecosystem.
The result includes:
  • An implementation example based on real-world usage
  • Source repository citations (e.g., socketio/socket.io-redis-adapter, miguelgrinberg/python-socketio)
  • A solution_id identifying the generated example
Results are useful for current ecosystem patterns, not for version-pinned dependency inspection.

​
Output formats

Every format-selectable MCP tool accepts a format parameter with exactly two values: text (the default) and json. Use text for reading and tool follow-ups; it is token-efficient, and you can pass returned paths, IDs, and line ranges directly to subsequent tools. Use json only to parse responses in code or to obtain fields absent from text. The former text-v1 value is rejected as of CLI and @githits/mcp 0.13.0; callers that passed it explicitly should omit format or send text. Rendering and JSON payloads are unchanged.

​
MCP tool reference

Two additional code-navigation-adjacent tools ship as experimental opt-ins: resolve_target maps a fuzzy or misspelled name to a canonical target, and code_diff compares repository trees resolved from two package versions or refs. Both are available only in the CLI and its local stdio MCP server, and are disabled and hidden by default.