Resolve a target

Use resolve_target when your agent knows a dependency’s name but needs a target for another GitHits tool. It returns candidates such as npm:express, github:openai/codex, or site:docs.example.com/sdk. Target resolution is available by default in githits and @githits/mcp from 0.27.0. Hosted MCP availability depends on the deployed package version. Already have a canonical target such as npm:express? Pass it directly to search, list, or another tool. The resolver accepts human-readable names and rejects canonical targets with INVALID_ARGUMENT.

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"

Parameters

MCP parameter	CLI argument or flag	Description
`name`	Positional argument	Required package, repository, or documentation-site name
`query`	`--query`	Task context for ranking retrieved candidates
`intent_hints`	Repeatable `--intent-hint`	Additional ranking context
`registries`	`--registry`	Package registry filter; CLI accepts a comma-separated list. Repository and site candidates remain eligible
`preferred_kind`	`--prefer-kind`	Preference for `package`, `repository`, or `site`
`limit`	`--limit`	Ranked candidate limit, 1–20; default 8. Exact-name and related targets can appear in addition
`verbose`	`--verbose`	Include name similarity in text output
`format`	`--json`	MCP uses `text` by default; choose `json` for structured output

Ranking context helps order retrieved candidates; it does not expand the search. Inputs must describe public open-source software. Do not include credentials, personal data, private code, or proprietary content.

Choose a target

Results group related package, repository, and documentation identities together. Your agent should follow the result’s guidance:

Result	Next step
Non-ambiguous `EXACT` or `HIGH` match with malicious-content status `clear` or `not_applicable`	Use the best target in the next tool call
`MEDIUM` or `LOW` confidence	Narrow the name or filters, or explicitly choose a candidate
Ambiguous matches	Ask the user to select a target or narrow the input
Affected, uncertain, missing, or unrecognized malicious-content status	Review the warning; GitHits does not offer an automatic next-tool action
No candidates	Correct the name or adjust registry filters. The CLI exits with code `1`

Pass a selected package or repository target to the tool you need. A site: target is for documentation: use list to browse it or search with source: "docs", then reuse the returned read locator.

Malicious-content gating

Package candidates include a check for malicious-package advisories affecting their latest version:

clear: no active malicious-package advisory affects the latest version. This does not mean the package is free of vulnerabilities.
not_applicable: the target is not a package.
affected: an active malicious-package advisory affects the latest version.
unknown: advisories exist, but GitHits cannot reliably classify the latest version.

Warnings link to the relevant MAL-* advisories on OSV. Uncertain results include the reasons for uncertainty; truncated results report omitted advisories. Use pkg_vulns to inspect vulnerabilities for a package version.

JSON output

CLI --json and MCP format: "json" return ambiguous, optional ambiguousReason, candidates, protectedMatches, and an optional best match. best is absent when there are no candidates. Candidates include latestVersionMaliciousStatus. Affected or uncertain candidates also include latestVersionMaliciousEvidence, with advisory IDs, classification reasons, and truncation details. Available nameSimilarity values are included in JSON; similarity alone does not establish that a candidate is the right target.

Get Started

Tools

Reference

Guides

Resolve a target

Parameters

Choose a target

Malicious-content gating

JSON output

​Parameters

​Choose a target

​Malicious-content gating

​JSON output

Parameters

Choose a target

Malicious-content gating

JSON output