Skip to main content
GitHits 0.10 introduces two 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 experimental tools 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 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.

​
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 JSON when you need the exact pageId and line locators for a docs_read follow-up.

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

​
Optional issue reporting

Issue reporting is off unless you explicitly enable it. Adding report_tool_issues lets the local quick_start guide ask the agent for one concise, redacted negative-feedback call per distinct observed defect. It is guidance to the agent; GitHits never sends feedback automatically.
~/.config/githits/config.toml
​
string
Optional. Accepted values:
  • "experimental" — reporting guidance covers only resolve_target and code_diff.
  • "all" — reporting guidance covers any GitHits tool while the experimental suite is active.
Omit the field for reporting-off (the default). The value is dormant when tools = false, but invalid values and types are still rejected by strict config-consuming paths.
When enabled, an agent may make one accepted: false feedback call per distinct observed issue and must include the exact tool name. Reports must not contain credentials, personal data, private or proprietary content, file bodies, or large outputs.

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