> ## Documentation Index
> Fetch the complete documentation index at: https://docs.githits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Experimental tools: resolve_target and code_diff

> Opt-in resolve_target and code_diff tools that ship with the GitHits CLI and its local stdio MCP server, disabled and hidden from help by default.

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.

| MCP tool         | CLI command                    | Purpose                                                                                                |
| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `resolve_target` | `npx githits@latest resolve`   | Rank canonical package or public GitHub repository targets for a fuzzy, misspelled, or ambiguous name. |
| `code_diff`      | `npx githits@latest code diff` | Compare repository trees resolved from two exact package versions or public GitHub refs.               |

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](/cli/configuration) covers the file location and the other supported sections; the relevant paths are:

| Platform      | Path                                                                                                       |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| macOS / Linux | `$XDG_CONFIG_HOME/githits/config.toml`, or `~/.config/githits/config.toml` when `XDG_CONFIG_HOME` is unset |
| Windows       | `%APPDATA%\githits\config.toml`                                                                            |

Add the `[experimental]` section:

```toml ~/.config/githits/config.toml theme={null}
[experimental]
tools = true
```

`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:

```bash theme={null}
npx githits@latest --help
npx githits@latest resolve --help
npx githits@latest code diff --help
```

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 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:

| Confidence                       | Behavior                                                                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `EXACT` or `HIGH`, non-ambiguous | The best match is a direct, copyable next action for the follow-up command.                                                                 |
| `MEDIUM` or `LOW`, non-ambiguous | Results are labeled as unconfirmed ranked candidates. The caller must narrow the name or filters, or pick a canonical candidate explicitly. |
| Ambiguous                        | The existing choose-or-narrow guidance is preserved and the follow-up command uses a literal `<target>` placeholder.                        |
| No candidates                    | The command asks for a corrected spelling or adjusted registry filters and exits `1`, because no target was resolved.                       |

`--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**

```bash theme={null}
npx githits@latest resolve express
npx githits@latest resolve codex --prefer-kind repository
npx githits@latest resolve guava --registry maven --limit 3
npx githits@latest resolve "pi agent" --query "coding agent CLI" --json
```

`--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**

```bash theme={null}
npx githits@latest code diff npm:express 4.18.1..4.18.2
npx githits@latest code diff npm:express 4.18.1..4.18.2 --stat
npx githits@latest code diff npm:express 4.18.1..4.18.2 --name-status -- 'lib/**/*.js'
npx githits@latest code diff --repo-url https://github.com/expressjs/express v4.18.1..v4.18.2 --name-only
```

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

```toml ~/.config/githits/config.toml theme={null}
[experimental]
tools = true
report_tool_issues = "experimental"
```

<ParamField body="report_tool_issues" type="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.
</ParamField>

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.