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

# Research

> Ask how a package or repository works and get an answer with cited sources.

Use `research` to ask how a public package or repository works and receive an answer with source citations. Research is experimental: [enable it](/tools/experimental-tools#enable-the-tools) for the CLI or local stdio MCP server. It is not available through hosted MCP.

```bash theme={null}
npx githits@latest research npm:express "How does Express handle middleware errors?"
```

The MCP tool is `research`. For HTTP integration, use the [REST endpoint](/api/requests-and-responses#research-a-question-with-cited-sources).

## Parameters

Choose one target mode:

| Mode | Usage |
| - | - |
| Question only | Omit the target; GitHits identifies it from the question |
| Explicit target | Pass a package or repository such as `npm:express` |
| Follow-up | Pass `--thread` in the CLI or `thread_id` in MCP; omit the target |

Threads support up to ten turns. Replace `<threadId>` with the ID from an earlier answer:

```bash theme={null}
npx githits@latest research --thread '<threadId>' "Which source files implement that?"
```

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

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

```json theme={null}
{
  "display_markdown": "Answer and source citations...",
  "tool_call_id": "<runId>",
  "thread_id": "<threadId>"
}
```

`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](/api/requests-and-responses#research-a-question-with-cited-sources).

## Target clarification

If the target is ambiguous, GitHits returns candidates in `display_markdown`. Choose a target and repeat the question. 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.