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 publishedgithits 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/mcpserver 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 GitHitsconfig.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:
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 or GitHub repository name to ranked canonical targets such as npm:express or github:openai/codex. Use it when the caller’s input is fuzzy, misspelled, or ambiguous and you need a concrete <registry>:<name> or github:<owner>/<repo> value before calling another GitHits tool. Canonical inputs like npm:express do not need resolution.
Terminal and MCP output share one actionability rule keyed off confidence:
--query and --intent-hint are ranking context, not filters. They cannot create candidates and must not contain credentials, personal data, private code, or proprietary content. --prefer-kind package|repository is a soft preference. --registry accepts a comma-separated list of package registries; repository candidates remain eligible.
CLI usage
--json emits the stable compact envelope {best?, ambiguous, ambiguousReason?, candidates, protectedMatches}. best is absent whenever there are no candidates.
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.
CLI usage
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. Addingreport_tool_issues lets the local MCP instructions 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 onlyresolve_targetandcode_diff."all"— reporting guidance covers any GitHits tool while the experimental suite is active.
tools = false, but invalid values and types are still rejected by strict config-consuming paths.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
Settools = 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.