Skip to main content
The public API exposes research at POST /v1/experimental/research, with public MCP tool ID research. It can take up to 210 seconds and reuses thread_id for follow-ups. The CLI 0.21.0 and its local stdio MCP server still use ask as documented below; those are separate release surfaces, not aliases for the removed public API tool or route.
The local experimental suite contains opt-in tools for local dogfooding before they are considered for the stable surface. They are disabled and hidden from CLI help by default, and their contracts may change based on dogfood evidence. Experimental status does not weaken the privacy or output-safety expectations that apply to stable GitHits tools. Reports and reporting guidance never include credentials, personal data, private or proprietary content, file bodies, or large outputs.

​
Availability

The local experimental tools described below are available only in the published githits CLI and its local stdio MCP server. They are not registered by:
  • the hosted MCP at https://mcp.githits.com
  • plugin or extension installs, which use the hosted MCP
  • Cursor’s remote MCP setup, which points at the hosted URL
  • the public @githits/mcp server API
npx githits@latest init configures local stdio for supported hosts except Cursor, which is remote-only. A Cursor setup therefore cannot enable these tools. If a host is configured with the hosted URL, switch it to a local stdio setup before opting in.

​
Enable the tools

Create or edit the GitHits config.toml for the user account that runs the CLI or coding agent. The configuration reference covers the file location and the other supported sections; the relevant paths are: Add the [experimental] section:
~/.config/githits/config.toml
tools must be the TOML boolean true, not a quoted string. Existing sections such as [auth] can remain in the same file. Restart the coding agent after editing so it starts a new local MCP process. The CLI reads the setting on each invocation. Confirm the CLI opt-in:
Root help should list ask and resolve, and npx githits@latest code --help should list diff. If an explicit experimental command is still disabled, the error names the config path GitHits read.

​
ask — source-cited answers about a package or repository

githits ask and the local MCP ask tool answer one question about a public package or repository. An answered response contains a grounded answer, cited sources, an Ask run ID, and a thread ID. Use it when you want a synthesized, source-backed answer instead of chaining discovery tools yourself. Provide at most one way to identify the target. Combining them is rejected:
  • Question only. Omit the target and thread. GitHits identifies the public package or repository from the question itself. This works in both the CLI and, since 0.15.1, the local MCP ask tool.
  • Explicit target. Pass a canonical target such as npm:express or github:openai/codex to keep the lookup scoped.
  • Thread follow-up. Pass the returned thread ID to --thread in the CLI or thread_id in MCP to ask a follow-up without repeating the target. Threads support up to ten turns.
Source citations default to directly executable source-reading calls: CLI commands in the CLI, and MCP-native read calls in the local MCP tool. Since githits and @githits/mcp 0.17.0, the local MCP adapter translates backend code_read and docs_read citations into read invocations so clients can execute them without knowing the retired tool names. Use --source-format url in the CLI or source_format: "url" in MCP to get the original upstream HTTP URLs instead. CLI usage

​
Target clarification

Since 0.15.1, a question-only Ask that cannot confidently select a target returns a clarification instead of an error. Both the CLI and the local MCP tool list resolver candidates with their confidence, related-target groups, protected matches, and malicious-status evidence, in the same layout as resolve. GitHits does not choose or promote a target for you. Repeat the question with a selected canonical target. A clarification is a completed lookup, not a failure. The CLI exits 0. JSON output marks the response with outcome: "needs_target" and preserves the typed candidate resolution. It carries no answer, source pointers, run ID, or thread ID. When no candidates match, the same shape returns with an empty candidate list; correct the spelling or name the target explicitly.

​
resolve_target — rank canonical targets for a fuzzy name

resolve_target maps a human-provided package, GitHub repository, or documentation-site name to grouped canonical targets such as npm:express, github:openai/codex, or site:docs.example.com/sdk. Use it when the caller’s input is fuzzy, misspelled, or ambiguous and you need a concrete target before calling another GitHits tool. Canonical inputs do not need resolution, and since 0.11.0 they are rejected before any backend call. Passing a target already accepted by downstream tools, such as npm:express, github:owner/repo, or site:docs.example.com/sdk, returns INVALID_ARGUMENT guidance telling you to pass that target directly to the next GitHits tool. Unprefixed human names such as @types/node, punctuated names, and slash-separated names remain valid resolver input. Terminal and MCP output share one actionability rule keyed off confidence and the malicious-content decision: --query and --intent-hint are ranking context, not filters. They rank retrieved candidates, cannot create or expand candidates, and must not contain credentials, personal data, private code, or proprietary content. --prefer-kind package|repository|site is a soft preference. --registry accepts a comma-separated list of package registries and constrains package candidates only; repository and site candidates remain eligible. Related package, repository, and documentation-site identities render as one project group. Compact metric lanes keep target-specific popularity, license, malicious-content, and availability evidence attached to the target they describe. Pass --verbose in the CLI or verbose: true to the MCP tool to include backend name similarity in text output. This percentage is coarse lexical support. It does not rerank candidates or replace confidence and malicious-content checks. JSON always includes available numeric nameSimilarity values.

​
Malicious-content gating

Since 0.10.2, every candidate carries a malicious-content decision for its latest version:
  • clear — no active malicious evidence affects the latest version. This is not a vulnerability-free claim.
  • not_applicable — the candidate is not a package, such as a repository target.
  • affected — active malicious evidence affects the latest version.
  • unknown — active malicious evidence exists, but the latest version cannot be classified reliably.
Text output stays silent for clear and not_applicable. affected and unknown decisions render a concise warning, red in the terminal, that links each status-relevant MAL-* advisory at https://osv.dev/vulnerability/<osv-id>. unknown warnings also summarize the classification reasons, and truncated evidence reports how many advisories were omitted. resolve fails closed. A best match becomes a direct next action only when its status is exactly clear or not_applicable. Affected, unknown, missing, and unrecognized statuses suppress the normal next-tool handoff. --json preserves the lowercase latestVersionMaliciousStatus field on every candidate and latestVersionMaliciousEvidence (advisory osvId values, classificationReasons, totalCount, truncated) for affected and uncertain candidates. CLI usage
--json emits the stable compact envelope {best?, ambiguous, ambiguousReason?, candidates, protectedMatches}. best is absent whenever there are no candidates. Pass a selected site: target to search with source: "docs". Request format: "json" only if a required docsReadTarget (or pageId) or line locator is absent from text, then pass it to read as target (with no path).

​
code_diff — compare package versions or repository refs

code_diff compares repository trees resolved from two package versions or two public GitHub refs, left-to-right. Use it to inspect changes between exact versions when you want git-shaped output. For upgrade evidence — vulnerabilities, changelog entries, deprecation, peer/dependency changes — call pkg_upgrade_review instead; raw diffs do not prove API compatibility or upgrade safety. Package targets must omit a version and repository targets must omit a ref because both endpoints belong in the required two-dot range. Three-dot merge-base syntax and --git-ref are rejected. Scope is always repository-wide. Package addressing resolves package, repository, version, and exact-commit identity, but every raw diff is repository-wide. code_diff does not discover or filter to a package directory. Sibling package paths may appear in a monorepo, and a bounded relevance-ranked result may contain no files from the addressed package. That absence does not prove the package is unchanged. The optional value after -- is one caller-supplied repository-relative bounded glob. It narrows repository paths without changing the effective scope. A backslash escapes one following non-slash character according to the backend grammar. --patch is the default view. --stat, --name-only, and --name-status select cheaper views and are mutually exclusive with --patch and each other. --max-files applies to every view after deterministic repository-relative relevance ranking; --max-patch-bytes is patch-only. The CLI does not send client defaults for either bound. Pass --verbose to show exact version or ref resolution and effective repository-scope diagnostics in text output. CLI usage
The selected Git-like view goes to stdout. Truncation, content-safety, and display-only path warnings go to stderr. Empty authoritative diffs exit 0. Caller-selected --max-files and --max-patch-bytes bounds may intentionally produce partial patches and still exit 0 with warnings. Unexpectedly incomplete or non-applicable plain patches are suppressed and exit 1; the --stat, --name-only, --name-status, and JSON views preserve their structured partial evidence.

​
Disable the tools

Set tools = false or remove the [experimental] section, then restart the coding agent. The CLI commands become hidden and unavailable, and newly started local MCP servers return to the stable tool inventory. No stored tool data or migration is involved.