> ## 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.
# Changelog
> Recent updates to GitHits — new features, improvements, and bug fixes.
## GitHits 0.27.1
Released [githits 0.27.1](https://github.com/githits-com/githits-cli/releases/tag/v0.27.1) and [@githits/mcp 0.27.1](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.27.1).
* **Shorter search and grep output.** Text results use concise counts and shared Read, More results, and Follow-up guidance. Source details, coverage warnings, JSON output, and request behavior are preserved.
* **Read the sources behind examples.** CLI and MCP examples request copyable source-reading commands or tool calls when the service supports them. Source links, licenses, and JSON envelopes are preserved. See [Example](/tools/code-examples).
* **Clearer changelog ranges.** CLI help and MCP guidance explain that `@from..to` excludes the starting version and includes the ending version. Query `@from` separately for that release's own notes. See [Package Intelligence](/tools/package-inspection).
Hosted MCP receives changes when the service adopts and deploys the released package.
## GitHits 0.27.0
Released [githits 0.27.0](https://github.com/githits-com/githits-cli/releases/tag/v0.27.0) and [@githits/mcp 0.27.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.27.0).
* **Target resolution is available by default.** `githits resolve` and MCP `resolve_target` no longer require experimental opt-in. Use them to find a package, repository, or documentation target from a dependency name. See [Target resolution](/tools/target-resolution).
* **Partial search results by default.** Search returns available hits while other targets or sources prepare. Use CLI `--no-allow-partial` or MCP `allow_partial_results: false` to wait for all runnable targets and sources before returning hits. See [Code](/tools/code-navigation#search).
* **Readable MCP errors.** Text responses explain failures directly. Use `format: "json"` when a script needs structured error codes and retry information.
* **Clearer source and indexing details.** Results show consistent source identities, known commit dates, indexing estimates, and retry guidance.
* **Full changelog bodies with verbose output.** MCP `pkg_changelog` accepts `verbose: true` alongside `body_lines` or `omit_bodies: true`; verbose text includes the full bodies.
Hosted MCP receives changes when the service adopts and deploys the released package.
## GitHits 0.26.0
Released [githits 0.26.0](https://github.com/githits-com/githits-cli/releases/tag/v0.26.0) and [@githits/mcp 0.26.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.26.0).
* **Source diff is available by default.** `githits code diff` and MCP `code_diff` no longer require experimental opt-in. Comparisons cover the whole repository, including for package targets. See [Code](/tools/code-navigation#code-diff).
* **Automatic skill refresh.** Local CLI MCP startup refreshes older, unchanged GitHits-managed `githits-mcp` installs. Edited, unrecognized, and newer content stays untouched. Disable refresh with [`skills.auto_update = false`](/cli/configuration#the-skills-section) or [`GITHITS_DISABLE_SKILL_UPDATE`](/cli/environment-variables#githits_disable_skill_update).
* **Search during indexing.** Results identify the indexed commit and offer a pinned read while the default branch indexes. Finished searches direct agents to a new search instead of further polling.
* **GitHits-first guidance.** Guided `init` tells agents to use GitHits first for code, docs, examples, and package lookups. Rerun guided setup to update installed instructions.
* **Accurate site wait outcomes.** CLI and MCP list JSON preserve `FAILED` and `SUPERSEDED` outcomes. Update scripts that branch on `outcome` to handle them.
* **Breaking provider API change.** Custom `@githits/mcp` providers must implement `codeDiff` on `codeNavigationService`. The built-in client already does.
* **Documentation homepage.** The npm package and plugin manifests now link to `docs.githits.com`.
Hosted MCP receives changes when the service adopts and deploys the released package.
## GitHits 0.25.0 and 0.25.1
Releases [githits 0.25.0](https://github.com/githits-com/githits-cli/releases/tag/v0.25.0) and [0.25.1](https://github.com/githits-com/githits-cli/releases/tag/v0.25.1), with [@githits/mcp 0.25.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.25.0) and [0.25.1](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.25.1), update MCP grep and add explicit session identifiers.
### Changed
* **Unified MCP grep.** In 0.25.0, [`grep`](/tools/code-navigation#grep) replaces `code_grep`. It searches ordered package, repository, and hosted documentation targets with the same defaults as CLI `githits grep`: RE2 regex, case-sensitive matching, and zero context. Migrate to `targets` objects and the new parameters; set `pattern_type: "literal"` and `ignore_case: true` to retain the old matching behavior. Legacy CLI `githits code grep` remains available.
### Added
* **Explicit session identifiers.** In 0.25.1, [`GITHITS_SESSION_ID`](/cli/environment-variables#githits_session_id) overrides automatic request grouping in the CLI and local MCP server. Values must match `[A-Za-z0-9_-]{1,64}` and are transmitted unchanged. Empty or malformed values fail validation without being echoed; unset the variable to restore automatic detection and hashing.
Refresh local MCP tool discovery after updating. Hosted MCP availability depends on the deployed server version; local environment variables do not reconfigure it.
## GitHits 0.24.0
Releases [githits 0.24.0](https://github.com/githits-com/githits-cli/releases/tag/v0.24.0) and [@githits/mcp 0.24.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.24.0) add unified CLI grep, replace the MCP inventory tools with one `list` tool, and make read follow-ups exact across search, listing, and research results.
### Added
* **Unified CLI grep.** `githits grep` searches one or more package, repository, and hosted documentation targets in order. It defaults to regex, case-sensitive matching with zero context lines. Pass `-F` for literal text, `-i` for case-insensitive matching, or `-s` for ripgrep-style case sensitivity. Text output groups matches by file or page with aligned line numbers and numbered locators you can copy into a read. GitHits reports partial coverage explicitly, including unvisited scopes, and returns a cursor to continue. JSON output stays lossless. Legacy CLI `code grep` and MCP `code_grep` remain available.
```bash theme={null}
# Search source and hosted docs together, case-insensitive literal match
githits grep -Fi 'router' npm:express site:expressjs.com
```
### Changed
* **Unified MCP `list` tool.** One MCP `list` tool replaces `code_files` and `docs_list` for package, repository, and explicit site inventories. Its description still mentions both retired names so stale tool searches find it. Default text includes the opaque `after` continuation when more entries are available. Grouped CLI commands such as [`code files`](/cli/commands#npx-githits-latest-code-files) and `docs list` remain available.
* **Backend-selected read actions.** Search and status results and `list` inventories emit read commands with the target, path, selector, and bounds that the backend selected. Replay the complete action instead of rebuilding it. Capped MCP continuations keep the whole remaining selection and served revision. CLI commands handle filenames that start with a dash. JSON shapes and caps are unchanged.
* **Compact search text.** CLI and MCP [`search`](/tools/code-navigation#search) text no longer repeats a read command under every hit. Hit headers remain usable for reads, and JSON keeps each hit's exact `followUp` action.
* **Claude plugin metadata.** The Claude plugin manifest now includes the GitHits display name, publisher contact email, and publisher website.
### Fixed
* **Case-insensitive list filters.** CLI and MCP `list` accept language and file-type filter names in any casing.
* **Leading-slash site selectors.** CLI and local MCP `list` accept one leading `/` in a site path and keep it within the `site:` target's scope. `/` alone browses the target's root.
* **Site directory paths.** CLI [`list`](/cli/commands#npx-githits-latest-list) text no longer drops the first directory component or prints repeated `/` entries for descendant sites. CLI and MCP read-path guidance now uses the supplied site target as the base.
### Experimental
* **Research renders backend Markdown.** Experimental CLI and local MCP [`research`](/tools/experimental-tools) display the complete Markdown returned by the API, so answer sections and citations can change without a client release. JSON output now returns a minimal envelope with `display_markdown` and optional IDs. **Breaking:** this replaces the previous structured answer and source JSON. Update any scripts that parse Research JSON.
Refresh local MCP tool discovery after updating and switch `code_files` and `docs_list` calls to `list`. Hosted MCP clients receive these changes after the service adopts `@githits/mcp` 0.24.0 and deploys.
## GitHits 0.23.0
Releases [githits 0.23.0](https://github.com/githits-com/githits-cli/releases/tag/v0.23.0) and [@githits/mcp 0.23.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.23.0) add CLI inventories and site-page reads and update search evidence.
### Added
* **Unified CLI inventories.** [`githits list`](/cli/commands#npx-githits-latest-list) browses one package, repository, or explicit documentation site. It supports path and glob selectors, recursive traversal, source filters, cursor pagination, paths-only `--silent` output, and JSON with read actions and metadata. Package and repository inventories contain source files; use a `site:` target for hosted docs. CLI `code files` is deprecated in help but remains available. MCP retains `code_files` and `docs_list`.
* **Site-page reads.** CLI and local MCP [`read`](/tools/documentation-access#read) accept an emitted `site:` target plus a host-relative page path, with an optional heading selector. Repository documentation reads return indexed file content with snapshot identity.
### Changed
* **Search JSON migration.** `search` and `search_status` remove `summary`, `highlights.summary`, hit `contentSafety`, and `repositoryEvidence.focusedSource`. Use the [current evidence fields](/tools/code-navigation#search): `matchedSource`, indexed-field provenance, semantic context, and `documentationPreview`.
### Fixed
* **Advisory applicability.** CLI `pkg vulns` and MCP `pkg_vulns` label advisories as affecting the inspected version or historical when the service supplies that status. JSON retains its applicability fields.
* **Package-addressed repository docs.** Search headers and generated read follow-ups use the served package target, target-relative path, and line range consistently, while JSON retains snapshot provenance.
Refresh local MCP tool discovery after updating. Hosted clients receive MCP changes after service adoption and deployment of `@githits/mcp` 0.23.0. Local environment variables do not reconfigure hosted MCP or plugin endpoints.
## GitHits 0.21.0, 0.22.0, and 0.22.1
Releases [githits 0.21.0](https://github.com/githits-com/githits-cli/releases/tag/v0.21.0), [0.22.0](https://github.com/githits-com/githits-cli/releases/tag/v0.22.0), and [0.22.1](https://github.com/githits-com/githits-cli/releases/tag/v0.22.1), plus [@githits/mcp 0.21.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.21.0) and [0.22.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.22.0), add selector and code-symbol reads, rename the local experimental `ask` tool to `research`, and move package changelog lookup to compact targets.
### New
* **Selector reads.** `githits read --selector` and the MCP [`read`](/tools/documentation-access) `selector` parameter read a single documentation heading or indexed code symbol. Ambiguous, missing, and unsupported selections return clear outcomes with recovery guidance.
* **Compact code-symbol reads.** Read a package or repository symbol with `target#symbol`, plus an optional exact path. GitHits picks code or documentation presentation from the result. Available in CLI 0.22.1; `@githits/mcp` 0.22.0 already includes it.
### Changed
* **Experimental `ask` is now `research`.** The local MCP tool is renamed to `research`, matching the [public API](/api/requests-and-responses#research-a-question-with-cited-sources). The CLI uses `githits research` and keeps `githits ask` as an alias. Local MCP clients with experimental tools enabled must switch from `ask` to `research`. See [experimental tools](/tools/experimental-tools).
* **Package-only changelog targets.** MCP [`pkg_changelog`](/tools/package-inspection) now takes one required `target`, such as `npm:express`, `npm:express@5.2.1`, or `npm:express@4.21.2..5.2.1`. It replaces `registry`, `package_name`, `repo_url`, `git_ref`, `from_version`, and `to_version`. The CLI drops `--repo-url` and `--git-ref` and keeps `--from`/`--to` for ranges. Exact pins return one release or `VERSION_NOT_FOUND`. Empty selections now succeed instead of returning `NOT_FOUND`.
* **Clearer compact target guidance.** CLI help, agent guidance, and MCP schemas explain how omitting a suffix selects the latest package or default branch, and how package-subpath scope differs from full-repository scope.
### Fixed
* **Clearer candidate search hits.** Text [`search`](/tools/documentation-access) results show bounded inspection windows, visible query fragments, and enclosing declarations in candidate headers. Fallback summaries are no longer presented as verified matches.
* **No server error pages in errors.** CLI and MCP errors keep the HTTP status and safe JSON details without dumping HTML or plain-text response bodies.
MCP callers must refresh tool discovery and migrate `pkg_changelog` calls to `target`. CLI users must replace repository changelog lookups with package targets. Hosted MCP clients at `https://mcp.githits.com` receive these changes after the service adopts `@githits/mcp` 0.22.0 and deploys.
## GitHits 0.22.0
Releases [githits 0.22.0](https://github.com/githits-com/githits-cli/releases/tag/v0.22.0) and [@githits/mcp 0.22.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.22.0) add selector reads, rename the experimental local `ask` entrypoints to `research`, and clean up search hit headers and HTTP error output.
### Added
* **Selector reads.** [`read`](/tools/code-navigation#read) now accepts a `selector` that reads a documentation heading or an indexed code symbol by name, so you don't need line ranges or URL fragments. On the CLI, pass `--selector`. For code symbols, add an exact path to narrow resolution to one file. Ambiguous, missing, and unsupported-snapshot selections return typed outcomes with recovery guidance.
```bash theme={null}
# Read an indexed code symbol
githits read npm:express@5.2.1 --selector Router
# Read a documentation heading by its logical heading ID
githits read --selector
```
On MCP, call `read` with `target` and `selector`, plus an optional `path` for code.
### Changed
* **Experimental local `ask` renamed to `research`.** The local stdio MCP tool is now `research`. The CLI command is now `githits research`, and `githits ask` still works as an alias. If your local MCP client calls `ask` with [experimental tools](/tools/experimental-tools) enabled, switch it to `research`. Both CLI spellings now report `command.research` telemetry. This matches the [public API rename](#public-api-research-replaces-ask) below.
### Fixed
* **Clearer candidate search hits.** CLI and MCP text [search](/tools/code-navigation) results now show bounded inspection windows, visible identifier-query fragments, and known enclosing declarations in candidate headers. Fallback summaries are no longer presented as verified source matches.
* **No server error pages in errors.** HTTP errors in the CLI and MCP keep the status code and safe JSON details. They no longer include HTML or plain-text response bodies.
MCP callers must refresh tool discovery after updating. Hosted MCP clients at `https://mcp.githits.com` receive selector reads after the service adopts `@githits/mcp` 0.22.0 and deploys.
## Public API: Research replaces Ask
The experimental source-cited answer operation is now [Research](/api-reference/v1/experimental/research-a-question-with-cited-sources): `POST /v1/experimental/research`, operation ID and public MCP tool ID `research`, and `Research*` public schemas. The previous experimental route and tool ID have been removed without aliases.
Answer generation can take up to **210 seconds**. Set a longer client timeout and reuse the returned `thread_id` for follow-up questions. See the [request examples](/api/requests-and-responses#research-a-question-with-cited-sources) and [timeout guidance](/api/errors).
[githits 0.22.0](https://github.com/githits-com/githits-cli/releases/tag/v0.22.0) applies the same rename to the [local experimental tools](/tools/experimental-tools). The local stdio MCP tool is now `research`, and the local server no longer registers `ask`. `githits research` is the canonical CLI command, and `githits ask` remains an alias with the same behavior. Start a new agent session so local MCP clients discover `research`.
## GitHits 0.20.0
Releases [githits 0.20.0](https://github.com/githits-com/githits-cli/releases/tag/v0.20.0) and [@githits/mcp 0.20.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.20.0) finish the compact-target migration for package tools, tighten shared agent instructions, and keep automatic documentation follow-ups stable when hosted pages get republished.
### Changed
* **Compact package targets on MCP.** [`docs_list`](/tools/documentation-access), [`pkg_info`, `pkg_vulns`, and `pkg_deps`](/tools/package-inspection) now take a single string `target` such as `npm:express@5.2.1` instead of separate `registry`, `package_name`, and `version` fields. `pkg_info` requires an unpinned latest-only target. CLI syntax, filters, and returned output are unchanged, and `docs_list` retry hints now use the new target syntax. `pkg_changelog` and `pkg_upgrade_review` keep their structured inputs.
* **Leaner agent instructions.** The shared MCP routing guide and packaged [skills](/installation/skills) now centralize common policy once, keep only the call essentials on each tool, and fit catalog selection sentences into 79 characters. Guidance around changelog caps and dependency graph opt-ins is clearer, and runtime behavior is unchanged.
### Fixed
* **Hosted documentation follow-ups stay stable across publications.** Automatic search follow-ups now reuse mutable hosted page URLs or the exact emitted fragment instead of stale line bounds, so republishing a hosted docs page no longer breaks the next [`read`](/tools/documentation-access) call. Repository-document snapshots and explicit read ranges are unchanged.
MCP callers must refresh tool discovery and migrate the four changed package tool call shapes after updating. Hosted MCP clients at `https://mcp.githits.com` receive these changes after the service adopts `@githits/mcp` 0.20.0 and deploys.
## GitHits 0.18.0
Releases [githits 0.18.0](https://github.com/githits-com/githits-cli/releases/tag/v0.18.0) and [@githits/mcp 0.18.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.18.0) collapse code and search inputs to a single compact `target` string, move repository revisions to `@ref`, and let agents pass search filters inline in the query.
### Changed
**Compact MCP targets on code and search tools**
[`search`](/tools/documentation-access), [`code_files`, `code_grep`](/tools/code-navigation), and the experimental [`code_diff`](/tools/code-navigation#code-diff) now require a single string `target` instead of registry-and-package or repo-and-ref pairs. Migrate:
* `{registry: "npm", package_name: "express", version: "5.2.1"}` → `"npm:express@5.2.1"`
* `{repo_url: "https://github.com/expressjs/express", git_ref: "main"}` → `"github:expressjs/express@main"`
* Search `{site: "https://expressjs.com/"}` → `"site:expressjs.com"`
CLI syntax is unchanged.
**Repository revisions use `@ref` instead of `#ref`**
Repository targets are now `provider:path@ref`. Later `@` characters inside a ref are preserved, and legacy `#ref` input is rejected with the exact canonical replacement so migration is mechanical. Package `registry:name@version` targets and documentation fragments are unchanged.
**Inline MCP search qualifiers**
Move `category`, `kind`, `path_prefix`, `file_intent`, `name`, and `language` into the `query` string as `category:callable`, `kind:function`, `path:lib/`, `intent:production`, `name:Router`, and `lang:typescript`. CLI flags, `public_only`, results, and continuation behavior are unchanged.
MCP callers must refresh tool discovery after updating. Hosted MCP clients at `https://mcp.githits.com` receive these changes after the service adopts `@githits/mcp` 0.18.0 and deploys.
## GitHits 0.19.0
Releases [githits 0.19.0](https://github.com/githits-com/githits-cli/releases/tag/v0.19.0) and [@githits/mcp 0.19.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.19.0) remove the separate language lookup step for implementation examples.
### Removed
* **Language discovery:** the `search_language` MCP tool and `githits languages` CLI command have been removed. Pass `language` to [`get_example`](/tools/code-navigation) or `--lang` to [`githits example`](/cli/commands), or omit the language to let GitHits infer it from your query. If GitHits cannot match the language, retry with a suggestion from the error or omit the language filter.
These changes are live on the hosted MCP server at `https://mcp.githits.com`. Refresh your client's MCP tool discovery to load the current tool catalog.
## Unified REST read API
The [public API contract](https://api.githits.dev/v1/openapi.json) now exposes `GET /v1/read` for both documentation pages and source files. The separate documentation and code read endpoints have been removed.
* **Documentation:** pass the `docs_read_target` returned by package documentation listing or search as `target`, omitting `path`. Indexed URL fragments select a section.
* **Source code:** pass a package or public repository `target` and an exact target-relative `path`.
* **Responses:** branch on `kind` (`documentation` or `code`). Both return `metadata` and `content` by default and preserve the identity and source information for their result type.
See [read requests and migration guidance](/api/requests-and-responses#read-documentation-or-source-code) and the [unified read reference](/api-reference/v1/read/read-documentation-or-source-code). This entry describes the REST API contract; CLI and MCP releases have separate availability.
## GitHits 0.17.0 and 0.17.1
Releases [0.17.0](https://github.com/githits-com/githits-cli/releases/tag/v0.17.0) and [0.17.1](https://github.com/githits-com/githits-cli/releases/tag/v0.17.1) shipped together. MCP `code_read` and `docs_read` merge into a single [`read`](/tools/documentation-access) tool, discovery waits grow to 120 seconds when the backend supplies indexing estimates, code and repository-doc results now emit copyable read targets, and every public-evidence MCP tool is annotated as open-world so clients with open-world filters can classify them correctly.
### Changed
**Unified `read` tool for code and documentation**
MCP `code_read` and `docs_read` are replaced by a single `read` tool that takes a compact target and an optional file path. Documentation fragments and code indexing waits behave the same, and Ask citations translate into the new locators automatically. The CLI adds `githits read` alongside the existing `githits code read` and `githits docs read` commands, which continue to work as deprecated aliases. MCP callers must rediscover the tool catalog after updating. Hosted MCP clients at `https://mcp.githits.com` receive the change after the service adopts `@githits/mcp` 0.17.0 and deploys.
**Discovery waits up to 120 seconds using backend estimates**
[`search`](/tools/documentation-access), search-status, and [code navigation](/tools/code-navigation) now preserve backend indexing timing evidence in JSON and use it when suggesting follow-up waits. When an estimate is available, waits can extend up to 120 seconds to match HTTP deadlines and MCP cancellation. Default waits are unchanged when no estimate is returned, and explicit wait overrides still apply.
### Fixed
* **Copyable file-list targets.** MCP `code_files` headers now render the served repository commit instead of treating the Git SHA as a package version, so the displayed target can be pasted directly into `read`.
* **Copyable repository documentation targets.** [`search`](/tools/documentation-access) text results for repository-backed documentation now show the backend's repo-doc read locator and separate line bounds, matching the JSON follow-up and avoiding invented package or path locators.
* **Public-evidence MCP tools are annotated as open-world.** The 12 stable public code, documentation, package, and search-result MCP tools and the three local experimental tools (`ask`, `resolve_target`, `code_diff`) now set `openWorldHint: true` while keeping `readOnlyHint: true` and `destructiveHint: false`. Static guidance and language lookup remain closed-world. MCP clients that filter by open-world semantics can now include these evidence tools. Refresh MCP tool discovery after updating; hosted clients at `https://mcp.githits.com` receive the change after the service adopts `@githits/mcp` 0.17.1 and deploys.
## GitHits 0.16.1 and 0.16.2
Releases [0.16.1](https://github.com/githits-com/githits-cli/releases/tag/v0.16.1) and [0.16.2](https://github.com/githits-com/githits-cli/releases/tag/v0.16.2) shipped together. Search now emits ready-to-read documentation fragments, MCP tool catalogs lead with question-to-tool routing before argument details, the default indexing wait grows from 20 to 30 seconds, and oversized `code_grep` context requests are clamped instead of failing.
### New
**Read exact documentation sections and ranges**
[`search`](/tools/documentation-access) now emits indexed documentation fragments as ready-to-read targets for [`docs_read`](/tools/documentation-access). `docs read` and `docs_read` resolve those fragments without synthesizing bounds, preserve absolute page coordinates, and keep unresolved sections distinct from missing pages. Requires the compatible backend schema, which is already deployed.
### Improved
**Longer default indexing wait**
The shared CLI and MCP wait on [`search`](/tools/documentation-access), search-status, and [code navigation](/tools/code-navigation) grew from 20 to 30 seconds so more indexing and metadata fetches complete before the response returns progress. Explicit wait overrides and the 60-second maximum are unchanged.
**Routing guidance before tool discovery**
The self-contained `quick_start` guide and the packaged [`githits-mcp` skill](/installation/skills) now lead with question-to-tool routing, so agents pick [`search`](/tools/documentation-access), [`code_*`](/tools/code-navigation), [`pkg_*`](/tools/package-inspection), or [`ask`](/tools/experimental-tools) from the question itself and only load argument details for the selected tool.
**Ask follow-up scope guidance**
The [experimental `ask`](/tools/experimental-tools) tool now documents how to change project, version, or topic within an existing thread and keeps the thread when clarifying a failed lookup, so follow-up questions don't force a new thread.
**Prefer text for model-visible MCP output**
Tool descriptions and the packaged [skill](/installation/skills) now recommend keeping model-visible MCP results in `text` and reserving `json` for host-side field handling or fields absent from text. Rendering and JSON payloads are unchanged.
**Consolidated MCP wait guidance**
Repeated MCP wait and indexing-recovery guidance moved into the shared `quick_start` and `githits-mcp` skill, and wait parameter descriptions shrank to units and bounds. Agent context stays leaner.
### Fixed
* **`code_grep` clamps oversized context instead of erroring.** Requests with more than 10 lines of context per side are clamped to 10, asymmetric overrides are preserved, and JSON returns both requested and effective values with an actionable text notice. For larger source windows, follow up with [`code_read`](/tools/code-navigation).
* **`search` rejects path prefixes without a code source.** Path prefix filters are now rejected locally when no code search source is selected, and CLI/MCP guidance explains that documentation and symbol searches don't support this filter.
* **Documentation URL schemes are recognized case-insensitively.** Documentation fragment handoffs no longer stall on mixed-case URL schemes.
* **Ask guidance no longer references unavailable defect reporting.** Instructions to report defects using an Ask run ID have been removed because no such action is available.
Hosted MCP clients at `https://mcp.githits.com` receive the applicable changes after the service adopts `@githits/mcp` 0.16.2 and deploys.
## GitHits 0.16.0
Releases [githits 0.16.0](https://github.com/githits-com/githits-cli/releases/tag/v0.16.0) and [@githits/mcp 0.16.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.16.0) retire feedback submission, mark every remaining MCP information tool as read-only, and preserve actionable recovery guidance when Ask cannot resolve a target.
### Changed
* **All remaining MCP information tools are marked read-only.** Every advertised tool now sets `readOnlyHint: true`, including the local experimental [`ask`](/tools/experimental-tools) tool. Internal result storage, source preparation, and research-thread behavior are unchanged.
### Removed
* **Feedback submission has been retired from the CLI and MCP package.** The MCP `feedback` tool, the `githits feedback` command, feedback instructions, and the exported TypeScript `submitFeedback` service method are no longer available. Existing `experimental.report_tool_issues` configuration keys are ignored. If your integration called feedback through these surfaces, remove those calls and refresh MCP tool discovery after updating.
### Fixed
* **Ask keeps actionable target diagnostics.** CLI and local MCP Ask responses now preserve validated server diagnostics and recovery guidance when a target needs clarification. New diagnostic codes and reasons can reach the caller without requiring another client release, while malformed or legacy responses receive actionable fallback text.
* **Public skills match the current product surface.** GitHits skills no longer recommend the retired feedback workflow. Onboarding and recovery guidance also preserve the requested CLI version, project scope, guidance preference, and separate Cursor authentication.
Hosted MCP clients at `https://mcp.githits.com` receive the applicable changes after the service adopts `@githits/mcp` 0.16.0 and deploys.
## GitHits 0.15.1
Releases [githits 0.15.1](https://github.com/githits-com/githits-cli/releases/tag/v0.15.1) and [@githits/mcp 0.15.1](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.15.1) let Ask clarify an ambiguous target with ranked candidates instead of failing, bring question-only Ask to the local MCP server, and preserve documentation indexing state in `docs list` results.
### Fixed
* **Ask target clarification shows resolver candidates.** When a question-only [`githits ask`](/tools/experimental-tools) cannot confidently select a target, it now returns a clarification with ranked resolver candidates instead of an error. Candidates keep their confidence, related-target groups, protected matches, and malicious-status evidence, in the same layout as `resolve`. The command completes successfully, and `--json` marks the response `outcome: "needs_target"` with the typed resolution. Repeat the question with a selected canonical target. Answered responses and explicit-target behavior are unchanged, and the clarification requires backend support.
* **Question-only Ask works in the local MCP server.** The local MCP [`ask`](/tools/experimental-tools) tool now accepts a question alone, matching the CLI. Omit both `target` and `thread_id` and GitHits identifies the target from the question, returning the same clarification candidates as the CLI when the target is ambiguous. Explicit targets and thread follow-ups keep working, but cannot be combined.
* **`docs list` reports documentation indexing state.** [`docs_list`](/tools/documentation-access) and `githits docs list` now distinguish documentation that is still being prepared from a terminal empty result. Empty results during preparation or indexing say so and suggest retrying the same call later instead of reporting "No documentation pages found." Provisional results keep the pages that are already available while marking that indexing continues, and JSON retains the exact backend `codeIndexState` lifecycle value.
Hosted MCP clients at `https://mcp.githits.com` receive the applicable changes after the service rollout.
## GitHits 0.15.0
Releases [githits 0.15.0](https://github.com/githits-com/githits-cli/releases/tag/v0.15.0) and [@githits/mcp 0.15.0](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.15.0) add Codeberg and nested GitLab repository targets, let the experimental `githits ask` infer a target from your question, and fix authentication error handling.
### New
**Codeberg and GitLab repository targets**
[Search](/tools/documentation-access) and [code navigation](/tools/code-navigation) now accept explicit `codeberg:owner/repo` and nested `gitlab:group/subgroup/project` targets alongside `github:owner/repo`, plus the matching full HTTPS URLs. Each form takes an optional `#ref`, follow-up commands preserve the provider identity and exact ref, and GitHub shorthand, GitHub URLs, and registry-native Swift and Zig package coordinates keep working unchanged. Bare `owner/repo` names and unsupported hosts are rejected up front. Hosted MCP clients at `https://mcp.githits.com` receive the change once the remote server is redeployed on 0.15.0.
**Question-only `githits ask`**
The experimental [`githits ask`](/tools/experimental-tools) command no longer requires an explicit target. Ask with a single argument and GitHits identifies the public package or repository from the question itself:
```bash theme={null}
npx githits@latest ask "How does FastAPI dependency injection resolve nested dependencies?"
```
Passing an explicit target first keeps the search scoped, and `--thread` follow-ups work as before. Enable the suite with `[experimental] tools = true` in your [CLI configuration](/cli/configuration).
### Fixed
* **Code navigation recovers from backend authentication errors.** [Code navigation](/tools/code-navigation) tools now recognize the backend `AUTHENTICATION_REQUIRED` code and attempt the standard single credential refresh, matching package inspection behavior, while access-denied errors are preserved. See [authentication](/authentication).
* **Rejected refresh credentials are classified correctly.** The CLI now recognizes OAuth and Supabase refresh-token and session rejection codes without relying on error description wording. Rejected tokens are cleared so the next login starts clean, while client registration and credentials replaced mid-refresh are preserved.
* **Site documentation is described as crawled on demand.** The experimental [`resolve`](/tools/target-resolution) surfaces now describe documentation sites that need preparation as crawled on demand instead of implying they are unavailable, keeping the normal on-demand search continuation.
## GitHits 0.13.0 and 0.14.0
Releases [0.13.0](https://github.com/githits-com/githits-cli/releases/tag/v0.13.0) and [0.14.0](https://github.com/githits-com/githits-cli/releases/tag/v0.14.0) shipped together. Search results gain semantic context and authoritative match evidence, `pkg_vulns` adds opt-in transitive vulnerability audits, `pkg_deps` picks up NuGet, Maven, and Packagist, and MCP output formats simplify to `text` and `json`.
### New
**Semantic search context**
0.13.0 [`search`](/tools/code-navigation) and search-status results now show the enclosing declaration and numbered focused source for each hit, with precise attributed read coordinates for follow-up [`code_read`](/tools/code-navigation) calls. JSON output adds the same structural evidence as additive fields. Hosted MCP clients at `https://mcp.githits.com` receive the change once the remote server is redeployed on 0.13.0.
**Authoritative search match evidence**
0.14.0 changes default [`search`](/tools/documentation-access) text to authoritative match evidence. Path-only matches render as compact file headers instead of arbitrary source chunks, source hits show proven snippets, and documentation hits use structural previews. Search JSON adds indexed-field provenance, the authoritative matched source, and crawled-documentation previews.
**Transitive vulnerability audits on `pkg vulns`**
[`pkg_vulns`](/tools/package-inspection) now offers opt-in npm-audit-style evidence covering vulnerabilities in the versions a package resolves, not just its direct advisories. Pass `--transitive` on the CLI or `include_transitive: true` in MCP; direct-only output remains the default, and severity and advisory-scope filters apply consistently to root and dependency rows.
```bash theme={null}
npx githits@latest pkg vulns npm:express@4.18.2 --transitive
```
**NuGet, Maven, and Packagist dependency support**
[`pkg_deps`](/tools/package-inspection) now accepts NuGet, Maven, and Packagist targets alongside the previously supported dependency registries, so .NET, JVM, and PHP dependency graphs resolve like the rest.
### Improved
**Simplified MCP output formats: `text` and `json`**
All format-selectable MCP tools now expose exactly two formats: `text` (the default) and `json`. Tool descriptions, `quick_start`, and the GitHits MCP [skill](/installation/skills) recommend text for reading and follow-up tool calls, reserving JSON for parsing in code or fields absent from text. Explicit `text-v1` callers must switch to `text` or omit the format parameter; rendering and JSON payloads are unchanged.
**`..` upgrade-review ranges**
Positional [`pkg_upgrade_review`](/tools/package-inspection) ranges now use `..`, including for scoped packages, and the legacy `->` delimiter is rejected with guidance. Write ranges as `:@..`:
```bash theme={null}
npx githits@latest pkg upgrade-review npm:lodash@4.17.20..4.17.21
```
**Documentation reads through emitted targets**
[`docs_list`](/tools/documentation-access) and search results now retain a `docsReadTarget`, the stable `pageId`, and a provenance `sourceUrl` for every documentation entry. Follow-up guidance prefers clickable URL targets for [`docs_read`](/tools/documentation-access), and historical `pageId` reads stay compatible.
**Complete vulnerability rows**
Compact [`pkg_vulns`](/tools/package-inspection) CLI text now shows every selected direct and transitive advisory row, verbose mode adds clearer transitive evidence, and JSON preserves advisory-wide affected-range and fixed-version fields. Compact MCP text remains capped; use verbose mode for all selected advisory rows.
### Fixed
* **Go module versions in MCP tools.** The MCP package documentation, dependency, vulnerability, changelog, and upgrade-review tools now accept exact Go versions with or without the `v` prefix and send the backend the canonical `v`-prefixed form, matching the CLI fix that shipped in 0.12.1. See [package inspection](/tools/package-inspection).
* **Vulnerability text is safe to print.** Hostile terminal control sequences are stripped from vulnerability display values before rendering, while JSON evidence stays lossless.
## Week of September 2 – September 4
Releases [0.12.0](https://github.com/githits-com/githits-cli/releases/tag/v0.12.0) and [0.12.1](https://github.com/githits-com/githits-cli/releases/tag/v0.12.1) shipped this week. An experimental `githits ask` command answers grounded questions about a package or repository with cited sources, `pkg deps` gains opt-in dependency issue analysis, and `pkg_info` separates current vulnerability exposure from historical advisories.
### New
**Experimental Agentic Ask: `githits ask`**
0.12.0 adds an opt-in `githits ask` command and matching local MCP `ask` tool to the [experimental suite](/tools/experimental-tools). Ask one question about a canonical package or repository target (for example `githits ask npm:express "Where is router dispatch implemented?"`) and get a grounded answer with cited sources, an Ask run ID, and a thread ID. Pass the thread ID to `--thread` (or `thread_id` in MCP) for follow-up questions without repeating the target; threads support up to ten turns. Source citations default to directly executable source-reading calls; use `--source-format url` for original upstream URLs instead. Enable the suite with `[experimental] tools = true` in your [CLI configuration](/cli/configuration).
**Dependency issue analysis on `pkg deps`**
[`pkg_deps`](/tools/package-inspection) now offers opt-in analysis of deprecated, outdated, duplicate, and conflicting dependencies. Pass `--issues` on the CLI or `include_issues: true` in MCP to get actionable conflict constraints and importer provenance in both text and JSON, with full or depth-limited traversal.
### Improved
**Clearer package overview evidence**
[`pkg_info`](/tools/package-inspection) now separates vulnerabilities affecting the latest version from package-wide advisory history, so current exposure is no longer conflated with resolved past advisories. Verbose text and JSON also expose the published-version count and download freshness, and CLI help and the MCP descriptor keep routing full-history questions to the right tool.
**Explicit upgrade-review batch limit**
[`pkg_upgrade_review`](/tools/package-inspection) CLI and MCP surfaces now advertise and enforce the deployed limit of 30 nonblank package upgrades per request, so oversized batches fail fast locally instead of at the backend.
### Fixed
* **Go module versions work with or without the `v` prefix.** Package documentation, dependency, vulnerability, changelog, and upgrade-review inputs now accept exact Go versions in either form and send the backend the canonical `v`-prefixed version. See [package inspection](/tools/package-inspection).
* **Repository grep advertises only real symbol fields.** [`code_grep`](/tools/code-navigation) CLI and MCP validation now expose only the symbol metadata repository grep can actually return.
* **Windows token refresh handoff.** File-backed auth locks are now released without racing successor agents against removal of the shared lock path, so concurrent CLI and MCP processes on Windows refresh tokens reliably. See [authentication](/authentication).
* **GitHits skill discovery.** The packaged MCP [skill](/installation/skills) now describes the OSS and package tasks that should trigger it instead of assuming GitHits was already selected, so agents load it when those tasks come up.
## GitHits 0.11.5
Releases [githits 0.11.5](https://github.com/githits-com/githits-cli/releases/tag/v0.11.5) and [@githits/mcp 0.11.5](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.11.5) make `quick_start` discoverable in deferred tool catalogs, clarify the security boundaries for retrieved public OSS content, and fix Agent Skill discovery and packaging.
### Improved
**`quick_start` is discoverable in deferred tool catalogs**
The `quick_start` catalog sentence now identifies it as the required first call for plain MCP sessions and names the untrusted-content safety rules it loads. Clients that defer or truncate tool catalogs (surfacing only short per-tool summaries until a tool is expanded) now route agents to `quick_start` before other GitHits evidence tools instead of burying it.
**Clarified untrusted remote-OSS content boundaries**
Tool guidance and the packaged [skills](/installation/skills) now consistently frame retrieved public OSS content — source, docs, package metadata, changelogs — as untrusted evidence. Instructions found inside retrieved content cannot override your authorization decisions or your coding tool's safeguards, and the existing prompt-injection protections are preserved.
### Fixed
* **Standards-compliant installers can parse the `githits-mcp` skill again.** The YAML frontmatter description in the packaged `githits-mcp` [skill](/installation/skills) is now quoted, so strict Agent Skill installers no longer fail to parse `SKILL.md`.
* **Internal skills stay out of public skill registries.** Repository-internal maintainer skills are now marked internal, so public skill registries and installers only offer the supported end-user skills.
* **Sampled changelog context is preserved in upgrade reviews.** Compact [`pkg_upgrade_review`](/tools/package-inspection) output now keeps identity-only sampled releases visible — version, publication date, URL, and headline — instead of dropping them, and no longer repeats the same release across keyword, sampled, and verbose entries.
## GitHits 0.11.4
Releases [githits 0.11.4](https://github.com/githits-com/githits-cli/releases/tag/v0.11.4) and [@githits/mcp 0.11.4](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.11.4) add definition-aware search evidence and improve MCP session guidance and wrapped source readability.
### New
**Definition-aware search evidence**
CLI and MCP [`search`](/tools/code-navigation) results now preserve focused, indexed, and symbol-definition ranges for each source hit. Output leads with the focused evidence and annotates the qualified enclosing symbol (for example the function or class the match sits in), so you can tell at a glance whether a hit is the definition you're looking for or a use site. Follow-up [`code_read`](/tools/code-navigation) suggestions target the exact served revision and the enclosing-definition range, so reading the full definition takes one call with no ref or line-range guessing.
### Improved
**Readable wrapped source comments**
Compact search output now repeats source comment markers on wrapped continuation lines, so long comments stay recognizable as comments instead of looking like executable code.
### Fixed
* **Reliable MCP session guidance.** MCP servers built from `githits` or `@githits/mcp` now require one `quick_start` call per plain session, while agents with the loaded `githits-mcp` [skill](/installation/skills) skip it for every tool. GitHits MCP and CLI skills use transport-specific triggers so agents load only the workflow that matches their transport.
## GitHits 0.11.3
Releases [githits 0.11.3](https://github.com/githits-com/githits-cli/releases/tag/v0.11.3) and [@githits/mcp 0.11.3](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.11.3) improve search recovery, target resolution, upgrade-review output, authentication guidance, and keychain error reporting.
### Improved
**Grouped project identities in target resolution**
The opt-in [`resolve`](/tools/target-resolution) command and `resolve_target` tool now keep related package, repository, and documentation-site identities together. Compact per-target rows preserve popularity, license, malicious-content, availability, and relation-truncation evidence. Pass `--verbose` or `verbose: true` to include coarse lexical name similarity; JSON includes available numeric similarity without changing backend ranking.
**Outcome-first upgrade evidence**
[`pkg_upgrade_review`](/tools/package-inspection) now uses the same compact, grouped evidence hierarchy in CLI and MCP text. It preserves vulnerability changes, dependency examples, issue locators, and structured JSON while leaving the final risk assessment to the caller.
**Current-evidence routing for security questions**
[`pkg_vulns`](/tools/package-inspection) now explicitly covers broad package-security questions so agents retrieve current advisory evidence instead of relying on potentially stale model knowledge.
### Fixed
* **Search recovery and provenance.** [`search`](/tools/code-navigation) and `search_status` preserve canonical package addressing, pinned repository identity, replayable source provenance, and terminal next actions across partial and terminal target states.
* **Backend authentication-required errors.** Package and source tools now recognize the backend `AUTHENTICATION_REQUIRED` code and return the standard refresh or sign-in guidance.
* **Code diff version alternatives.** [`code_diff`](/tools/code-navigation#code-diff) preserves backend-ranked package-version alternatives and their proven source refs in structured error details and CLI guidance.
* **Keychain access failures.** Inaccessible or unavailable credential stores now return an explicit error instead of appearing empty. See [authentication troubleshooting](/guides/troubleshooting).
## Week of August 27 – August 28
Releases [0.11.1](https://github.com/githits-com/githits-cli/releases/tag/v0.11.1) and [0.11.2](https://github.com/githits-com/githits-cli/releases/tag/v0.11.2) shipped this week. Search output is now compact and consistent across CLI and MCP, the experimental resolver recognizes standalone documentation sites, agents can read larger source and docs slices in one call, and `githits init` recovers cleanly when stale credentials fail to refresh.
### New
**Standalone documentation site resolution**
The opt-in [`resolve`](/tools/target-resolution) command and `resolve_target` MCP tool now recognize standalone documentation sites as first-class candidates, labeled `site` instead of a generic fallback. You can request them explicitly with `--prefer-kind site` (or the matching MCP argument), and selected site targets route straight into documentation [`search`](/tools/documentation-access). Stable MCP guidance now also distinguishes package-only `docs_list` from the standalone-site search and `docs_read` flow.
**Browser-callable `get_example` for WebMCP**
`@githits/mcp` 0.11.1 adds a dedicated `@githits/mcp/tools` entry that exposes the validated [`get_example`](/tools/code-examples) surface for frontend WebMCP integration. Only this selected entry is browser-safe; the installed package and other entries remain Node-oriented.
### Improved
**Compact, unified search output**
[`search`](/tools/documentation-access) and search-status responses now share one outcome-first formatter across the CLI and MCP: compact completed-result headlines, numbered locator-first hits that keep docs page IDs for `docs_read` follow-ups, source provenance, target-grouped readiness when it matters, and terminal-aware wrapping in the CLI. JSON output states partial-result truth exactly, and continuation guidance stays native to the surface you called from.
**Fewer context round trips on source and docs reads**
[`code_read`](/tools/code-navigation) and [`docs_read`](/tools/documentation-access) now allow deliberate 300-line reads while keeping the 150-line default, and `code_grep` per-file limits align with the requested totals. Agents fetch what they need in fewer calls, and served indexing snapshots plus public-repository discovery guidance are clearer.
**Intent-first package tool descriptions**
[Package inspection](/tools/package-inspection) MCP descriptions now lead with compact user-intent phrases, so truncated tool catalogs still make clear which tool answers health, vulnerability, dependency, changelog, and upgrade questions.
### Fixed
* **`githits init` recovers sign-in after stale refresh failures.** Interactive [`githits init`](/cli/commands) now proceeds to browser OAuth when retained expired credentials cannot refresh, instead of stalling, and its runnable authentication guidance consistently uses `npx githits@latest`. See [authentication](/authentication) for the refresh model.
* **Uninstall respects your guidance selection.** Interactive user-level [`githits uninstall`](/cli/commands) now removes guidance only for selected tools whose MCP configuration is absent after cleanup, and preserves shared guidance still usable by detected tools you kept.
* **Self-contained MCP skill.** The packaged `githits-mcp` [skill](/installation/skills) now includes the stable quick-start guidance directly, removing a redundant bootstrap call, while plain MCP clients keep the `quick_start` fallback.
## Week of August 24 – August 27
Releases [0.10.2](https://github.com/githits-com/githits-cli/releases/tag/v0.10.2) and [0.11.0](https://github.com/githits-com/githits-cli/releases/tag/v0.11.0) shipped this week. The experimental resolver now fails closed on malicious package candidates, remote MCP clients get a one-call `quick_start` guide with benefit-first tool routing, and onboarding gains a predictable setup flow plus a canonical top-level `githits uninstall` command.
### New
**One-call `quick_start` guidance for MCP clients**
0.11.0 adds a read-only `quick_start` MCP tool that returns the full GitHits tool guide in a single call: public-OSS scope, target syntax, compact-output guidance, cross-tool workflows, and safety rules, without querying any GitHits evidence. Call it once per session before other GitHits tools unless the guide is already in your agent's context. It replaces inconsistently surfaced server instructions, and the packaged Agent Skill now points at the guide instead of duplicating it. The hosted endpoint at `https://mcp.githits.com` must run `@githits/mcp` 0.11.0 before remote plugins and extensions can rely on `quick_start`.
**Top-level `githits uninstall` command**
Removing GitHits setup now has a canonical command: [`githits uninstall`](/cli/commands) removes GitHits MCP configuration from your coding tools, and unless you pass `--keep-guidance` it also cleans up the GitHits-owned skill files while preserving unrelated skills and directories. The previous `githits init uninstall` form remains a compatibility alias with identical flags and behavior.
```bash theme={null}
npx githits@latest uninstall # Interactive: choose user-level or project-level
npx githits@latest uninstall --yes # Non-interactive user-level removal
npx githits@latest uninstall --yes --keep-guidance # Remove MCP config, keep guidance files
```
### Improved
**Benefit-first MCP tool routing**
Remote MCP tool catalogs are now written benefit-first with explicit workflow handoffs between tools, so agents pick the right tool ([`search`](/tools/documentation-access), [`code_*`](/tools/code-navigation), [`pkg_*`](/tools/package-inspection)) from the description instead of trial and error.
**Predictable onboarding setup and removal**
[`githits init`](/cli/commands) now targets only the agents you select: an unselected configured agent is reported unchanged and never retargeted. Guidance-only and stale-skill cleanup selections repair packaged guidance without touching MCP configuration or requiring authentication, an empty selection exits with `Nothing selected, no changes made`, and a fully configured run becomes a verification-only review with no confirmation, authentication, or writes. Review and summary output is transport-aware, describing local stdio, Cursor's hosted remote MCP, or both based on what you actually selected.
### Fixed
* **Experimental resolver fails closed on malicious package candidates.** The opt-in [`resolve_target`](/tools/target-resolution) tool and `githits resolve` command now preserve latest-version malicious-content decisions and bounded OSV evidence, link affected or uncertain advisories in warnings, and withhold the normal CLI/MCP continuation for affected, unknown, or unrecognized states instead of suggesting a next action on a suspect target. 0.10.2 also fine-tunes partial-readiness handling so incomplete resolver evidence is surfaced rather than treated as a clean result.
* **Canonical resolve inputs are rejected locally.** [`githits resolve`](/tools/target-resolution) and the local `resolve_target` tool now direct already-canonical targets like `npm:express` or `github:owner/repo` straight to the next GitHits tool without calling the resolver backend.
* **Reliable `init` install and uninstall state.** [`githits init`](/cli/commands) now uses structured inspection of Claude's user-scoped MCP state and best-effort guidance cleanup, so absent state is skipped safely, failures stay visible, and guidance reporting is kept separate from agent counts.
* **Correct changelog range semantics.** [`pkg_changelog`](/tools/package-inspection) now documents and exposes `from` as an exclusive lower bound, so exact-release and range requests follow the backend contract consistently. Returned entries preserve backend/source order; consumers must not assume newest-first ordering.
## GitHits 0.10.1
Releases [githits 0.10.1](https://github.com/githits-com/githits-cli/releases/tag/v0.10.1) and [@githits/mcp 0.10.1](https://github.com/githits-com/githits-cli/releases/tag/mcp-v0.10.1) preserve usable search evidence while indexing and harden authentication across concurrent CLI and local MCP processes.
### Improved
**Provisional search evidence**
[`search`](/tools/code-navigation) and `search_status` now render queryable `PROVISIONAL` repository and documentation freshness. Responses keep the exact served identity, indexing guidance, available hits, and a `searchRef` only while the session remains active.
### Fixed
* **Reliable concurrent authentication.** Live per-user auth locks survive temporary process-inspection failures, and stale-owner cleanup is serialized so parallel CLI and local MCP processes do not reuse rotating refresh tokens. Restart long-running local MCP processes after upgrading so they load the hardened lock protocol.
* **Evolving search-session statuses.** CLI and MCP search preserve evidence for terminal `DEFERRED` and future status values. Only known active sessions direct callers to keep polling; stopped or unknown sessions return a new-search action.
## Week of August 17 – August 21
Releases [0.9.3](https://github.com/githits-com/githits-cli/releases/tag/v0.9.3) and [0.10.0](https://github.com/githits-com/githits-cli/releases/tag/v0.10.0) shipped this week, introducing opt-in local experimental tools for target resolution and source diffs, adding documentation source evidence to search results, and improving CLI recovery, validation, and diagnostics.
### New
**Opt-in local experimental tools: `resolve` and `code diff`**
0.10.0 adds a hidden-by-default experimental suite to the [`githits` CLI](/cli/commands) and its local stdio MCP server: `githits resolve` (with the matching `resolve_target` MCP tool) ranks canonical package and GitHub repository targets, and `githits code diff` (with `code_diff`) produces bounded, Git-like diffs across [code navigation](/tools/code-navigation) targets. Enable them by setting `[experimental] tools = true` in your [CLI configuration](/cli/configuration). The hosted MCP at `https://mcp.githits.com`, plugins, extensions, and the public MCP API stay on the stable tool inventory.
**Documentation source evidence on `search`**
Unified [`search`](/tools/documentation-access) and search-status responses now identify the repository and published-site documentation behind each result. Healthy sources render as compact references; stale, incomplete, pending, or unavailable sources explain what was searched and what the published evidence actually covers, so you can tell partial hits from full coverage at a glance.
**`githits code diff` (silent dogfood in 0.9.3)**
0.9.3 introduced [`githits code diff`](/cli/commands) as an unpromoted CLI surface: bounded Git-like views, repository-relative glob filtering, reversible path quoting, apply-safe patch handling, structured completeness diagnostics, and `--json` output. 0.10.0 promotes it to the experimental suite alongside the matching MCP tool.
### Improved
**Authoritative documentation site identities**
Discovery [`search`](/tools/documentation-access) and search-status now carry canonical documentation site URLs and show the host and path even when no hits are returned, so you can see exactly which site was consulted.
**Repository-wide code diff scope, spelled out**
CLI help, legacy-scope diagnostics, and public client docs for `code diff` / `code_diff` now explain that package targets resolve repository and commit identity while raw diffs remain repository-wide. Bounded results may contain only sibling paths, and the surface says so instead of implying a package-scoped diff.
**Confident target resolution guidance**
`resolve` now emits direct canonical next actions only for non-ambiguous exact or high-confidence matches. Weaker and empty results require explicit correction or selection instead of an unsafe auto-pick.
**Diff terminal output**
`code diff` aligns wide Unicode paths by terminal cell width and colors patches, stat bars, summary markers, and change statuses when the terminal supports it. Verbose code-file rows use the same alignment.
**Standalone-site search recovery**
[`search`](/tools/documentation-access) now preserves ordered backend site suggestions, distinguishes truncated candidate lists, and directs active crawls through search-status without guessing or rewriting your target. Help text also separates atomic interim evidence from opted-in partial target/source subsets.
### Fixed
* **Exact-path recovery names the right surface.** `code_read` and `code_grep` now return `FILE_PATH_EXCLUDED` for excluded files and `SOURCE_FILE_INVENTORY_UNKNOWN` when the index cannot verify a path, with actionable path and resolution details, instead of a generic `NOT_FOUND`. See [code navigation](/tools/code-navigation).
* **Waited searches no longer suggest an older ref.** After a waited [`search`](/tools/documentation-access) or [code navigation](/tools/code-navigation) call reaches the requested commit, the response no longer recommends falling back to an earlier ref.
* **Code validation errors match the caller's surface.** Client-side `INVALID_ARGUMENT` errors from shared code-read and grep request builders name CLI commands, positionals, and flags for the [`githits` CLI](/cli/commands) while MCP callers keep MCP-native tool and argument syntax.
## Week of August 12 – August 14
Releases [0.9.1](https://github.com/githits-com/githits-cli/releases/tag/v0.9.1) and [0.9.2](https://github.com/githits-com/githits-cli/releases/tag/v0.9.2) shipped this week, tightening exact-path recovery on [code navigation](/tools/code-navigation), making [`githits init`](/cli/commands) checks for Claude Code and Codex CLI reliable, and sharpening client-side validation error messages so CLI and MCP callers see the right syntax for the surface they're on.
### Improved
**Surface-native validation guidance**
Client-side `INVALID_ARGUMENT` errors from shared code read and grep request builders now name the right syntax for the caller. The [`githits` CLI](/cli/commands) sees `githits code read`, `githits code grep`, positionals, and flags; MCP callers see [`code_read`](/tools/code-navigation), [`code_grep`](/tools/code-navigation), and MCP argument names. No more mismatched examples in errors.
### Fixed
* **Exact-path recovery on missing files.** Typed `FILE_NOT_FOUND` responses from [`code_read`](/tools/code-navigation) and [`code_grep`](/tools/code-navigation) now name `code_files`, `code_grep`, and `code_read` (or their `githits code …` CLI equivalents) in path-discovery guidance. Extensionless exact files use their containing directory for the follow-up listing, and generic `NOT_FOUND` errors no longer receive misleading file-path hints.
* **Reliable Claude Code and Codex CLI setup in `githits init`.** User-scoped MCP checks now run outside project configuration, use targeted server probes with host-specific timeouts, and distinguish missing, non-canonical, disabled, and failed states. Enabled customized Codex entries are preserved, and a cleanup no-op is no longer reported as successful setup when a later command fails.
## Week of August 10 – August 11
Release [0.9.0](https://github.com/githits-com/githits-cli/releases/tag/v0.9.0) adds a canonical `githits settings` surface with Terms of Service acceptance, tightens `search` and `code_grep` recovery so agents stop retrying futile calls, hardens the OAuth callback flow for remote and sandboxed logins, and picks up the latest `undici` security patches.
### New
**Manage account settings and Terms of Service from the CLI**
The new [`githits settings`](/cli/commands) command group lets you view and update account settings (default language, license mode, blocked license IDs, marketing emails) without leaving the terminal. Use `githits settings show` to print the full canonical settings object, `githits settings get ` and `githits settings set ` for individual fields, and `githits settings clear ` to reset a clearable field. Every subcommand supports `--json` for scripting.
**Accept the Terms of Service without a browser round-trip**
`githits settings terms` shows the current Terms of Service acceptance requirement, and `githits settings terms accept` records acceptance directly from the CLI. When the API returns a terms-remediation error on any authenticated call, the [`githits` CLI](/cli/commands) and MCP tools now surface a structured error pointing at `githits settings terms accept` so agents know exactly which command to run.
### Improved
**Bounded recovery guidance for `search` and `code_grep`**
Empty and still-indexing results on [`search`](/tools/code-navigation) and [`code_grep`](/tools/code-navigation) now come with bounded, actionable follow-ups instead of open-ended retry prompts. Terminal search sessions no longer poll indefinitely, deferred searches return an explicit continuation, grep truncation messages use normalized producer values, and case-sensitivity and per-command pivots are accurate across MCP and CLI output. Identical retry loops are prevented while structured JSON diagnostics are preserved.
**Forward-compatible account settings**
The account settings client now accepts unknown fields returned by newer account APIs, so older [`githits` CLI](/cli/commands) versions keep working when the server adds new settings.
### Fixed
* **OAuth login completes cleanly on interrupted callbacks.** Valid sign-in callbacks now resolve even when the response closes before finish, timeout and callback-error reporting stay independent of listener teardown, and `githits login` no longer blocks waiting for the temporary callback server to shut down. See [authentication](/authentication) for the full flow.
* **`githits init` sandbox and `--no-browser` logins are more resilient.** Temporary callback connections are force-closed after the response finishes and token exchange continues without awaiting listener teardown, so proxied sandbox and SSH-tunneled logins finish reliably. See the [`init` command reference](/cli/commands) for `--no-browser` and `--port`.
* **`undici` security patches.** The bundled HTTP client was upgraded to `undici` 7.29.0 to resolve five published advisories while retaining Node 20 compatibility.
## Week of August 3 – August 7
Releases [0.6.7](https://github.com/githits-com/githits-cli/releases/tag/v0.6.7), [0.7.0](https://github.com/githits-com/githits-cli/releases/tag/v0.7.0), and [0.8.0](https://github.com/githits-com/githits-cli/releases/tag/v0.8.0) shipped this week. `githits init` now discloses what it sends where before any changes land, cross-host plugin packaging consolidates into a single canonical source, and GitHits ships as a portable Agent Plugins 1.0.0 package that any compliant client can install directly.
### New
**Portable Agent Plugins 1.0.0 support**
0.8.0 publishes GitHits as a portable [Agent Plugin](https://agent-plugins.org) alongside the existing native adapters. Any Agent Plugins 1.0.0 client can install GitHits from the repository root and connect to the hosted remote MCP at `https://mcp.githits.com` over Streamable HTTP, no host-specific glue required. Existing installs for Claude Code, Cursor, Codex, Gemini CLI, Google Antigravity, and VS Code/GitHub Copilot OpenPlugin keep working unchanged. See [Manual remote MCP setup](/installation/manual-setup) for the hosted transport.
**`githits init` discloses outbound data flows and requires a review acknowledgment**
Before configuring any coding tool, [`githits init`](/cli/commands) now shows the outbound queries, targets, and feedback endpoints it will contact and asks you to acknowledge the install review, even when there is nothing to write. Guidance-only remediation stays actionable, MCP configuration targets are listed separately from supporting-guidance targets, and `--no-guidance` is preserved through the generated install and verification commands.
**Explicit documentation site targets on unified `search`**
Unified [`search`](/tools/documentation-access) now accepts explicit indexed documentation site targets, so you can point a query at a specific site instead of relying on inferred routing. Responses continue to surface per-source [coverage state](/tools/documentation-access) — pages crawled, frontier remaining, and a human-readable note — for sites that are partially crawled or capped.
**Consolidated cross-host plugin packaging**
0.7.0 collapses cross-host packaging around the [`githits-cli`](https://github.com/githits-com/githits-cli) repository as the single source of truth. Claude Code, Cursor, Codex, Gemini CLI, Google Antigravity, and generic/OpenPlugin now expose the same four current skills (`githits-onboarding`, `githits-mcp`, `githits-code`, `githits-package`), and every plugin/extension install goes through the hosted remote MCP at `https://mcp.githits.com` with host-managed OAuth. See [Manual remote MCP setup](/installation/manual-setup) for the hosted transport, and [Skills](/installation/skills) for the shared skill contract.
### Changed
* **Direct `githits init` installs continue to use local stdio MCP for supported tools, with one exception: Cursor is now remote-only.** [Automatic local MCP setup](/installation/automatic-setup) covers the local stdio flow; Cursor users should follow [Manual remote MCP setup](/installation/manual-setup).
* **Legacy plugin surfaces removed.** The legacy Cursor command payload and the duplicated standalone Claude and Gemini plugin repositories have been retired now that every host reads from the canonical repository.
### Fixed
* **Concurrent auth operations stay isolated across process restarts.** The local auth storage lock now caches each process's identity per storage instance and retries transient identity lookups, so PID-reuse protection can't be weakened when multiple [`githits` CLI](/cli/commands) or MCP processes touch credentials at the same time. See [authentication](/authentication) for the full storage model.
## Week of July 27 – July 31
Release [0.6.6](https://github.com/githits-com/githits-cli/releases/tag/v0.6.6) tightens keychain error handling, adds schema-level validation to the [`code_grep`](/tools/code-navigation) tool, clarifies [`docs_read`](/tools/documentation-access) output limits, and surfaces documentation crawl coverage warnings on unified [`search`](/tools/documentation-access).
### Improved
* **Clearer `code_grep` context limits.** The `context_lines`, `context_lines_before`, and `context_lines_after` parameters on [`code_grep`](/tools/code-navigation) are now validated at the MCP schema level (integer, 0–100), so agents catch out-of-range values before the call is made. Each field also documents that `_before` / `_after` override the shared `context_lines` for their side.
* **Precise `docs_read` text output description.** The [`docs_read`](/tools/documentation-access) tool description and parameter hints now spell out the text-mode behavior explicitly: text output is capped at 150 lines per call (including explicit larger ranges), the response reports the returned range plus `totalLines` for follow-up slices, and JSON output remains uncapped when `end_line` is omitted.
* **Partial documentation coverage is surfaced on `search`.** When a hosted documentation site is still being crawled or its crawl was capped, unified [`search`](/tools/documentation-access) responses now include per-source coverage state (pages crawled, frontier remaining, and a human-readable note) so agents can decide whether to retry, widen the query, or proceed with the partial hits instead of assuming full coverage.
### Fixed
* **Keychain access failures no longer look like a missing login.** The migrating auth storage layer now distinguishes a missing credential from an unreachable system keychain. In keychain mode, a locked or otherwise unavailable keychain surfaces a clear storage error (with guidance to unlock the keychain, set `GITHITS_API_TOKEN`, or opt into `auth.storage = "file"`) instead of silently returning "unauthenticated" or falling back to plaintext files. See [authentication](/authentication) for the full storage model.
## Week of July 27 – July 28
Release [0.6.5](https://github.com/githits-com/githits-cli/releases/tag/v0.6.5) restores silent automatic refresh of expired local logins, so long-running CLI and MCP sessions no longer see stray `AUTH_REQUIRED` prompts when a valid refresh token is on disk.
### Fixed
* **Expired access tokens refresh silently again.** Once an access token expired, authenticated [`githits` CLI](/cli/commands) and MCP calls could incorrectly raise an `AUTH_REQUIRED` prompt even with a valid refresh token stored. Normal expiry is noninteractive again — the token is refreshed in the background and the call proceeds.
* **Transient refresh failures preserve stored credentials.** Transport, timeout, and 5xx failures during token refresh no longer surface as a missing-token error. The recoverable failure is reported to the caller, the refresh token stays on disk, and later calls retry the refresh automatically. See [authentication](/authentication) for the full recovery model.
* **Missing OAuth client registration is reported explicitly.** If tokens exist but the companion dynamic OAuth client registration is missing or unreadable, authenticated calls return a clear re-login error instead of the generic missing-token message.
## Week of July 20 – July 24
A small maintenance week: [`githits init`](/cli/commands) picks up the same SSH-friendly callback options that [`githits login`](/cli/commands) already exposes, so guided setup works cleanly on remote and headless machines. Runtime and workflow dependencies also got a routine refresh.
### Fixed
* **`githits init` supports `--no-browser` and `--port`.** You can now run guided setup on a remote host or SSH session and either print the sign-in URL as a fallback or forward the callback over an SSH tunnel — for example `ssh -N -L 8765:127.0.0.1:8765 user@remote-host` alongside `npx githits@latest init --port 8765`. See the [`init` command reference](/cli/commands) for the full flag list.
## Week of July 13 – July 17
Releases [0.6.3](https://github.com/githits-com/githits-cli/releases/tag/v0.6.3) and [0.6.4](https://github.com/githits-com/githits-cli/releases/tag/v0.6.4) shipped this week, bringing structured rate-limit and timeout errors across the [`githits` CLI](/cli/commands) and MCP tools, marketplace-ready MCP tool annotations with a compact-by-default output format, and tighter credential persistence when refreshes hit transient failures.
### New
**Marketplace-ready MCP tool annotations**
Every public MCP tool now declares explicit `readOnlyHint`, `openWorldHint`, and `destructiveHint` annotations, so MCP-aware clients and marketplaces (including the OpenAI marketplace) can classify what each tool does before calling it. Read-only tools like [`docs_read`](/tools/documentation-access), [`pkg_info`, `pkg_vulns`, `pkg_deps`, `pkg_changelog`, and `pkg_upgrade_review`](/tools/package-inspection) are marked as such; tools that may enqueue private indexing or crawl work (like `search`, [`code_files`, `code_read`, `code_grep`](/tools/code-navigation), and [`docs_list`](/tools/documentation-access)) are explicit about the bounded, non-destructive nature of those writes.
**Compact `text-v1` is now the default MCP output format**
Format-selectable MCP tools now default to `text-v1` and advertise it as the first `format` option. Agents get concise, markdown-shaped responses out of the box instead of the full JSON envelope, cutting context usage on `code_read`, `code_grep`, `docs_read`, `pkg_changelog`, and `pkg_deps`. JSON stays available as an opt-in for scripting.
### Improved
**Structured rate-limit and timeout errors across CLI and MCP**
API rate-limit (`429`) and request-timeout responses are now classified consistently across the [`githits example`](/cli/commands) command, [code navigation](/tools/code-navigation), [documentation access](/tools/documentation-access), and [package inspection](/tools/package-inspection). JSON output preserves standard retry metadata (`details.retryAfterSeconds`, `details.timeoutMs`) with `retryable: true`; terminal output surfaces the same information in plain language, for example `Request limit reached. Try again in 17 seconds.` The client returns the error immediately instead of silently retrying, and public messages stay provider-neutral.
**Longer client deadline for `githits example`**
Example generation now uses a longer client-side deadline than shorter metadata operations, so complex example requests can complete without spurious timeouts. Explicit timeout overrides are honored for tests and embedding clients, and hosted transports can reserve time for their outer response boundaries. The CLI default stays at four minutes.
### Fixed
* **Transient auth failures no longer clear your refresh credentials.** Transport, timeout, and 5xx failures during token refresh now retain the stored refresh token and retry on the next call. Only classified terminal failures (revoked sessions, refresh-token reuse, invalid client) clear credentials — see [authentication](/authentication) for details.
* **Auth files preserve tightened permissions.** On POSIX, new and rewritten `auth.json`, `client.json`, `metadata.json`, and `diagnostics.json` are capped at `0600`; existing more-restrictive modes (like `0400`) are preserved instead of being loosened.
* **Ambiguous legacy plaintext credentials are reconciled safely.** File-mode auth loads now run under the auth lock when migration is needed: the newest valid timestamp wins, canonical copies are re-persisted, and legacy copies are cleared. Ambiguous ties between legacy stores are left intact with a warning instead of guessing.
## Week of July 6 – July 10
A batch of network and reliability fixes landed on `main` this week: [`githits`](/cli/commands) now honors standard HTTP proxy environment variables across every CLI-originated call, local auth commands no longer trip over a malformed proxy setting, and missing GitHub repositories in [code navigation](/tools/code-navigation) get a clean "not found" instead of a generic error.
### New
**HTTP proxy support across the CLI**
The [`githits` CLI](/cli/commands) now honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` (and their lowercase aliases) for every CLI-originated request — OAuth discovery, sign-in, token refresh, REST API calls, code and package service calls, local MCP tool calls started through `githits mcp start`, and npm update checks. Lowercase values win when both cases are set, matching standard proxy precedence. `NO_PROXY` bypass and credential redaction in error messages both work out of the box, so you can now run GitHits from behind a corporate proxy without extra configuration. The Node.js floor moves to `^20.18.1 || >=22.13.0` as part of this change.
### Fixed
* **`githits auth status` and `githits logout` no longer fail on malformed proxy env.** Proxy validation is now deferred until the first network call, so local-only auth paths (checking status, logging out) run cleanly even when `HTTP_PROXY` is set to an unparseable value.
* **Missing GitHub repositories now return `NOT_FOUND` from [code navigation](/tools/code-navigation).** A backend `REPOSITORY_NOT_FOUND` used to surface as a generic error; it's now classified as a clean, non-retryable `NOT_FOUND`, with `repoUrl` and `requestedRef` echoed in the error details so agents can give a specific "that repo doesn't exist" message instead of guessing.
## Week of July 6, 2026
Release [0.6.2](https://github.com/githits-com/githits-cli/releases/tag/v0.6.2) shipped this week, adding a scripting-friendly `githits auth token` command, publishing GitHits to the official MCP registry as `com.githits/githits`, and polishing the `githits login` URL fallback plus the packaged GitHits MCP skill copy.
### New
**`githits auth token` for scripting and CI**
A new [`githits auth token`](/cli/commands) command prints the current bearer token to stdout — no labels, prompts, or extra whitespace — so you can pipe it directly to other tools or use it in command substitution. Resolution matches the rest of the CLI: if `GITHITS_API_TOKEN` is set it wins, otherwise the stored OAuth access token is printed, refreshing it against the saved client first if it's expired. When no credentials are available the command exits non-zero instead of triggering an interactive login, so CI runs fail fast with a clear signal.
```bash theme={null}
curl -H "Authorization: Bearer $(npx githits@latest auth token)" \
https://api.example.com/resource
```
**Published to the official MCP registry**
GitHits is now listed in the [official MCP registry](https://github.com/modelcontextprotocol/registry) as `com.githits/githits`, giving MCP-aware clients a canonical discovery and installation path in addition to the existing `npx githits@latest init` flow. The registry entry is published automatically from the release pipeline, so it stays in lockstep with each new CLI release.
### Improved
**Visible sign-in URL fallback during `githits login`**
[`githits login`](/cli/commands) now always prints the browser sign-in URL as a visible fallback during normal runs, not just under `--no-browser`. If the browser launch is hidden (for example inside a wrapper terminal) or fails silently, you'll still see the URL and can open it yourself without rerunning the command.
**Tightened GitHits MCP skill guidance**
The packaged `githits-mcp` skill installed by guided `githits init` picks up small copy tweaks — clearer framing that GitHits covers public OSS and package evidence, and less prescriptive advice about unrelated local tools — so agents get a calmer, more accurate description of when to reach for GitHits.
## Week of June 29 – July 3
Release [0.6.0](https://github.com/githits-com/githits-cli/releases/tag/v0.6.0) shipped this week, making guided GitHits MCP setup the recommended `githits init` path, adding a packaged `githits-mcp` skill and short managed instruction block that agents pick up automatically, and expanding the set of supported MCP setup targets.
### New
**Guided GitHits MCP init is the new recommended path**
[`githits init`](/cli/commands) now leads with **Install GitHits MCP + supporting instructions (Recommended)** as the top choice, with plain MCP and standalone Agent Skills kept as explicit alternatives. Guided setup installs the MCP server plus a small `githits-mcp` skill and a managed instruction block, so agents reliably reach for GitHits as the default OSS context layer instead of falling back to model memory or generic web search.
New flags let you pick a mode non-interactively:
* `githits init --guidance` — install MCP plus the supporting skill and instruction block.
* `githits init --no-guidance` — install plain MCP only.
* `githits init uninstall --keep-guidance` — remove the MCP config but keep the skill and instruction block in place.
Interactive setup, `--yes`, and staged `--install-agents` all default to guided MCP unless `--no-guidance` is passed. Reruns are idempotent: if MCP is already installed but guidance is missing, guided init installs only the missing pieces, and vice versa. Uninstall cleans up GitHits MCP config, the managed instruction block (identified by `` markers), and the GitHits-owned `githits-mcp/SKILL.md` from every target path, deleting the skill directory only if it ends up empty.
Guidance is installed at both **user** and **project** scope depending on the tool — for example a project-level `.claude/skills/githits-mcp/SKILL.md` alongside a user-level `~/.copilot/instructions/githits.instructions.md`.
**Packaged `githits-mcp` skill and managed instruction block**
GitHits now ships a dedicated `githits-mcp` Agent Skill and a short managed instruction paragraph that guided init drops into `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and equivalent per-tool instruction files. The skill tells agents to prefer GitHits for open-source discovery, planning, research, implementation, debugging, and maintenance — package docs, indexed package and repository source, examples, dependency graphs, vulnerabilities, changelogs, and upgrade-review evidence — and to route to the right tool (`search`, `docs_*`, `code_*`, `pkg_*`, `get_example`) instead of relying on model memory. The instruction block stays intentionally one paragraph; the skill carries the detailed behavior, so agent context stays lean.
**Expanded MCP setup targets**
Guided and plain `githits init` now configure MCP for a wider set of current, docs-backed clients:
* **Zed** — `context_servers` in `~/.config/zed/settings.json` (user) or `.zed/settings.json` (project).
* **Junie** — `mcpServers` in `~/.junie/mcp/mcp.json` or `.junie/mcp/mcp.json`.
* **Qwen Code** — `mcpServers` in `~/.qwen/settings.json` or `.qwen/settings.json`.
* **Kiro** — `mcpServers` in `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json`.
* **Kilo Code** — `mcp` in `~/.config/kilo/kilo.jsonc` or `.kilo/kilo.jsonc`, using the local command shape.
* **Factory Droid** — `mcpServers` in `~/.factory/mcp.json` or `.factory/mcp.json`.
* **Amazon Q CLI** — command-driven user install via detected `q mcp` / `qchat mcp`; no direct file editing.
Each target participates in the same install, uninstall, rerun, and `--install-agents --json` flows as existing tools.
### Fixed
* **Headless-friendly `githits init` sign-in.** Release [0.6.1](https://github.com/githits-com/githits-cli/releases/tag/v0.6.1) adds a `--no-browser` flag to [`githits init`](/cli/commands) that prints the sign-in URL instead of trying to open a browser, so SSH sessions, containers, and other display-less environments can complete guided setup without a remote browser popping up. Behaves the same as `githits login --no-browser`.
## Week of June 22 – June 26
Releases [0.5.1](https://github.com/githits-com/githits-cli/releases/tag/v0.5.1), [0.5.2](https://github.com/githits-com/githits-cli/releases/tag/v0.5.2), and [0.5.3](https://github.com/githits-com/githits-cli/releases/tag/v0.5.3) shipped this week, focused on a canonical syntax for GitHub repository targets, sharper "did you mean" guidance when a ref doesn't exist, and a leaner aggregate path for `pkg_upgrade_review`.
### New
**Canonical `github:owner/repo#ref` target syntax**
[Code navigation](/tools/code-navigation), search, and [documentation access](/tools/documentation-access) now accept GitHub repository targets in a canonical `github:owner/repo#ref` form, plus full `https://github.com/owner/repo` URLs. The `#ref` form makes refs that contain `@` (for example `n8n@2.26.5`) unambiguous, and CLI and MCP follow-ups now echo the same canonical label everywhere. Malformed GitHub URLs are rejected up front instead of being passed through.
**Aggregate `pkg_upgrade_review` with transitive truncation metadata**
[`pkg_upgrade_review`](/tools/package-inspection) now uses a single aggregate backend query instead of fanning out per package, so reviews are faster and JSON/text output stays in lockstep. Public JSON also gains `*TotalCount` and `*Truncated` fields on transitive vulnerability detail pages, so agents can tell when a list was cut off and decide whether to ask for more.
### Improved
**Cleaner `githits init` status rows**
[`githits init`](/cli/commands) now shows the read-only probe command (for example `checked via claude plugin list`) on rows that didn't change, prints install or uninstall commands only when they actually ran, and aligns multi-command continuation rows to the detail column. Composite rows that pair a CLI check with a config-file write are preserved.
**Leaner package metadata payloads**
Package summary, dependency, and changelog backend calls now request only the fields each output mode actually uses — compact text and `--omit-bodies` skip verbose fields, while JSON and verbose modes keep everything. You should see faster responses for the common `pkg info`, `pkg deps`, and `pkg changelog` paths with no change in what's rendered.
**"Did you mean" suggestions for unknown repository refs**
When [code navigation](/tools/code-navigation) hits a `REF_NOT_FOUND` for a GitHub target, the error now includes the backend's `suggestedRefs` (a short "did you mean" list) separately from `availableRefs` (indexed refs you can retry against). CLI and MCP error details surface both, and the inline hint only appends a suggestion when the backend message doesn't already include one — no more duplicated suggestions in the same error.
**Indexing wait estimates in error messages**
Code navigation responses for repos that are still being indexed now include a compact estimate of how long indexing should take, alongside structured `indexingEstimate` fields in the error details. You'll know whether to wait a few seconds or come back later.
## Week of June 15 – June 19
Releases [0.4.14](https://github.com/githits-com/githits-cli/releases/tag/v0.4.14) and [0.4.15](https://github.com/githits-com/githits-cli/releases/tag/v0.4.15) shipped this week, focused on a much clearer `init` install/uninstall experience, stricter package target syntax, and a wave of auth hardening for users running multiple agents in parallel.
### New
**Per-tool change rows in `githits init`**
[`githits init`](/cli/commands) now reports exactly what changed for every detected tool — `created`, `updated`, `unchanged`, or `ran` — alongside the config path or command it touched, instead of a generic success line. Already-configured tools are included in the audit so you can see at a glance what your setup looks like, and `--install-agents --json` includes structured `changes` for scripting.
**Unified `init uninstall` UX**
`githits init uninstall` now uses the same selection model as install: configured tools are pre-checked, deselecting one keeps it, and `--yes` removes from all configured tools. Per-tool result rows use the same aligned renderer as install, so install and uninstall finally read the same way.
**Auth-clear breadcrumb in `githits doctor`**
[`githits doctor`](/cli/commands) now surfaces the last auth-clear event (`reason` + timestamp) when your token went missing — for example after a refresh-token reuse, a rejected client registration, or an explicit `logout`. When the active token is missing, `doctor` also prints a cause-specific recommendation so you know what to do next. No secrets are stored.
### Improved
**Explicit package registries in target specs**
Package targets across `search`, [code navigation](/tools/code-navigation), [documentation access](/tools/documentation-access), and [package inspection](/tools/package-inspection) now require an explicit registry prefix — for example `npm:express` instead of a bare `express`. GitHub repository shorthands `github:owner/repo` and `github.com/owner/repo` are normalized. Errors for mixed package/repo targets, CLI help, and MCP tool descriptions were rewritten to match.
**Cleaner `login` and `logout` output**
`githits login` and `githits logout` output is now concise — no token-lifetime or environment details, no implementation-oriented progress lines. Just what happened.
**Dedicated message for missing git refs**
Code navigation tools now classify backend `REF_NOT_FOUND` responses separately and show repo/ref-specific guidance instead of generic path-narrowing or "try `code_files`" hints. You'll know immediately when a branch, tag, or commit doesn't exist.
**Windows launcher detection in `doctor`**
`githits doctor`'s PATH lookup now checks PATHEXT launchers like `githits.cmd` on Windows, so `doctor` correctly reports the CLI as installed instead of missing.
### Fixed
* **Refresh-token reuse races between concurrent agents.** The auth refresh lock is now keyed to the credential scope (per-user) instead of the active config directory, so two local agents sharing the same keychain credential no longer both submit the same single-use refresh token and trigger a server-side family revocation. Terminal `invalid_client` and refresh-reuse failures also clear stale state immediately so the next login starts clean.
* **Cross-class credential tug-of-war.** Keychain and file-mode auth storage are now isolated for both reads and writes — agents running in different storage modes can no longer steal and delete each other's tokens. Switching `auth.storage` between modes now requires an explicit `githits login`.
* **Automatic auth clears stay scoped to the active backend.** A stale credential in an inactive backend (for example a leftover keychain token) can no longer wipe the good credential in the mode you actually run. Explicit `githits logout` still clears every backend.
* **Auth lock acquisition retries on write races.** Concurrent token refreshes no longer fail with `ENOENT` when another contender removes the lock directory between create and owner-file write.
## Week of June 8 – June 12
### New
**GitHits onboarding skill**
A new `githits-onboarding` skill walks coding agents through a safe, staged GitHits setup — detecting supported tools, asking before writing any config, installing the ones you pick, guiding you through login, and verifying the result. It ships as a public skill and as part of the Claude Code plugin. Install [GitHits Skills](/installation/skills) and your agent can run setup for you instead of you wiring `init` flags by hand.
### Improved
**More resilient `githits init` on slow machines**
Agent detection and config probes in [`githits init`](/cli/commands) now run with bounded timeouts (2–5s) so a stuck binary lookup or hung config check fails fast instead of stalling onboarding. Set `GITHITS_INIT_TRACE=1` to print step-by-step diagnostics on stderr when you need to debug a detection issue — JSON output on stdout is unaffected and stays machine-parseable.
## Week of June 1 – June 5
### New
**OpenCode support in `githits init`**
[`githits init`](/cli/commands) now detects and configures [OpenCode](/installation/automatic-setup) alongside the other supported AI coding tools, with a higher generated MCP timeout tuned for OpenCode's session flow.
**Safer MCP package tool inputs**
[Package inspection](/tools/package-inspection) tools picked up cleaner, agent-safer schemas: `pkg_deps` now takes `max_depth`, `pkg_changelog` takes `omit_bodies`, and `pkg_upgrade_review` takes `skip_transitive_security`. Defaults are no longer silently coupled to other options, so agents get more predictable behavior on every call.
### Improved
**Better language search results**
[`githits languages`](/cli/commands) and the [`search_language`](/tools/code-examples) MCP tool now route queries through the backend's ranked `/languages` endpoint instead of local filtering. Short aliases like `ts`, `py`, `js`, `c++`, and `c#` now surface the right language first.
**Clearer authentication errors**
Auth failures now distinguish missing local credentials from backend-rejected tokens, both in CLI JSON output and MCP error envelopes. Remediation guidance points you to the right next step — OAuth login, [`GITHITS_API_TOKEN`](/authentication), or support — instead of a generic "not authenticated" message.
**Normalized empty MCP search filters**
The `search` tool no longer fails with `INVALID_ARGUMENT` when an agent passes empty docs-only filter fields. Blank filters are treated as absent, matching how other MCP inputs behave.
### Fixed
* **Concurrent agents no longer invalidate each other's auth tokens.** Token refresh is now serialized across CLI and MCP processes sharing the same credentials, so running multiple agents in parallel won't spend a single-use refresh token twice and log you out.
## Week of May 25 – May 29
### New
**Project-level `githits init`**
[`githits init`](/cli/commands) now supports installing GitHits MCP configuration at the project level, alongside the existing user-level setup. Project mode covers detect, install, and uninstall flows for supported agents — including a new VS Code stdio config — so you can scope GitHits to a single repo without touching your global agent setup.
**`githits doctor` diagnostics command**
A new [`githits doctor`](/cli/commands) command prints a redacted snapshot of your runtime, environment, config path, service override, and auth file state. Text and `--json` output are both supported, and probes are read-only so running it never triggers auth migration or token refreshes. Use it first when filing an issue.
**Swift package support**
Swift is now a first-class registry across `search`, [code navigation](/tools/code-navigation), [documentation access](/tools/documentation-access), and [package inspection](/tools/package-inspection). Vulnerability and dependency lookups, `v`-prefixed versions, and GitHub-shaped package coordinates all work for Swift packages out of the box.
### Improved
**Simpler search source selection**
The `search` tool and `githits search --source` now take a single source value instead of a list. Descriptions for `target` and `source` were also rewritten to be clearer for agents. Passing `--source` more than once is now rejected explicitly instead of silently picking one.
**Request timeouts everywhere**
Network requests now time out with a clear error, so stalled requests no longer leave the CLI waiting indefinitely.
**Structured auth failures**
Missing-auth failures from authenticated commands now return a consistent JSON envelope (`AUTH_REQUIRED`), while terminal sessions still see the friendly login guidance. Easier to handle from scripts and agents.
### Fixed
* **Empty optional MCP fields no longer break tool calls.** `pkg_upgrade_review`, `search` targets, `pkg_changelog` addressing, and `code_*` targets now treat harness-filled empty arrays and blank strings as absent instead of failing validation.
* **Token refresh races hardened.** Concurrent refresh attempts coalesce correctly across soft and forced refreshes, rotated refresh tokens are preserved on same-lineage conflicts, and newer external sessions/logouts still take precedence.
* **Windows `init` no longer triggers Node DEP0190.** Subprocess probes now run through `cmd.exe` with safe argument escaping so shim resolution works without deprecation warnings.
## Week of May 18 – May 22
### New
**Hermes Agent support in `githits init`**
`githits init` now detects [Hermes Agent](/installation/automatic-setup) alongside the other supported AI coding tools and writes its MCP server configuration to `~/.hermes/HERMES_HOME` while preserving existing YAML comments. Run `githits init` to set it up.
**Agent-safe staged onboarding**
The `init` command now supports a staged, non-interactive flow for agents and CI. New flags on [`githits init`](/cli/commands):
* `--detect-agents` — scan for supported AI tools and exit without making changes.
* `--install-agents ` — install only the agents you explicitly name. Idempotent for already-configured agents.
* `--json` — emit detection and install results as structured JSON.
`--yes` is rejected in non-interactive runs to prevent surprise side effects. See the [headless CI guide](/guides/headless-ci) for usage patterns.
**Copy-paste agent snippet on the `init` ready screen**
After setup completes, `githits init` now prints a snippet you can drop directly into your `AGENTS.md` or `CLAUDE.md` so your agent knows when to reach for GitHits tools.
### Improved
**Redesigned `init` onboarding flow**
Rewritten copy across every `init` screen (intro, detect, choose, sign-in, install, ready, uninstall) in a clearer, agent-focused voice. The CLI also picks up a new brand color, a gradient ASCII logo, highlighted `--help` section titles, and an animated spinner with rotating labels on `example`, `search`, `code`, and `docs` while requests are in flight.
**Target resolution feedback for code navigation**
[Code navigation](/tools/code-navigation) tools (`search`, `code_files`, `code_read`, `code_grep`) now surface compact, actionable warnings when a target needs freshness or indexing attention, and stay quiet on healthy default-branch requests. Follow-up targets and default-branch intent are preserved across calls.
**Severity-filtered transitive upgrade advisories**
[`pkg_upgrade_review`](/tools/package-inspection) now applies your `min_severity` setting to transitive vulnerability counts, so the evidence you see matches the threshold you asked for. The previous "transitive counts are unfiltered" caveat has been removed.
### Fixed
* **`--no-color` now actually disables color.** The flag was previously registered but never wired up. Every styled output across the CLI now respects it.
* **`githits logout` no longer reads the keychain.** Logout completes cleanly without unnecessary credential prompts.
* **Auth is refreshed before `init` login** to avoid stale-session failures during onboarding.
* **Init detection messaging** is clearer when no compatible agents are found, and login guidance is suppressed when an install step fails.
* **Node 20 compatibility restored** after a regression in the previous release.
* **Stale-search warnings suppressed** when the follow-up target matches the original request.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.