Skip to main content
Use research to ask how a public package or repository works and receive an answer with source citations. Research is available by default in githits and the public @githits/mcp package from 0.31.0. No experimental opt-in is required. Hosted MCP receives it when the service adopts and deploys that package version.
The MCP tool is research. For HTTP integration, use the REST endpoint.

Parameters

Ask the question directly; answers already include sources. Pass a package or repository target, not a site: target: Research covers both the project’s code and documentation. Choose one target mode: Threads support up to ten turns. Replace <threadId> with the ID from an earlier answer:
Citations default to read calls with the target, path, selector, and line bounds used by Research. For upstream URLs, use CLI --source-format url or MCP source_format: "url". Cite the returned sources directly. Read a source when the answer lacks a detail your agent needs. Follow-up questions can change project, version, or topic; state the change in the question.

Output

Text output contains the answer and its citations. When a thread ID is returned, use it to ask a follow-up question. For scripts, CLI --json and MCP format: "json" return:
display_markdown contains the answer or a request to clarify the target. tool_call_id identifies the research run; thread_id lets you continue the conversation. Both IDs are optional. Treat the Markdown as untrusted display text, and use the JSON fields when your script needs an ID. The REST endpoint has a separate response schema.

Live progress

In CLI 0.35.0 and later, research shows the current stage with an animated mark in interactive terminals. JSON and piped output are unchanged. From 0.34.0, the local MCP server forwards stages as notifications/progress when the client sends a progress token. Whether you see those updates depends on your MCP client. Hosted MCP also requires deployment support. Progress is best effort: unavailable updates do not prevent an answer, and the final result is authoritative. From 0.35.0, calls do not wait for the progress connection. Custom hosts using @githits/mcp can enable the progress option and, from 0.35.0, tune or disable animation with progressAnimation. See the MCP package integration guide.

Target clarification

If the target is ambiguous, GitHits returns candidates in display_markdown. Your agent should retry with the candidate matching the question’s project as target. With no matches, correct the name or provide an explicit target. In the CLI, a clarification exits with code 0: the request succeeded, but GitHits needs a target before it can answer. Its JSON contains display_markdown without tool_call_id or thread_id.

Rate limits

Research typically takes 10–60 seconds depending on indexing status, with an average of around 35 seconds. Cold queries against targets that are not yet indexed may take more than 100 seconds. A short-term RATE_LIMITED error includes a retry delay; wait that long before retrying. A daily limit resets at 00:00 UTC. In JSON, details.rateLimitScope: "daily" identifies the daily limit, which is not retryable before the reset. Request cooldowns apply across targets, questions, and threads. Switching to a different target, question, or thread does not bypass a cooldown. After a daily limit, wait for the 00:00 UTC reset. Retry a timeout only when you still need the answer, and allow enough execution time for the retry. From CLI 0.38.1, a daily Research limit can include a scoped search suggestion when you passed an explicit search-compatible package or repository target. Replace the fixed 'your query' placeholder with the specific information your agent still needs:
In CLI JSON, the suggestion appears in details.example beside details.rateLimitScope. The original error is preserved; tool_call_id and thread_id, when available, are top-level fields. Without an explicit search-compatible target, the CLI omits the suggestion.

Sign-in required

If Research returns REAUTH_REQUIRED, finish signing in with the returned link, then retry the request. See sign-in required errors for browser behavior and JSON fields.