[Canonical HTML page](https://githits.com/blog/search-code-and-documentation/)
[Back to blog](/blog.md)
November 3, 2026 · 6 min read
# Search: finding code and documentation in open-source projects
Follow a GitHits search from Pi's session documentation into the code that writes files. Find relevant source, narrow results and inspect the returned revision.
An agent working with Pi’s saved sessions needs to know when Pi writes them to disk.
In the [resolve\_target post](/blog/resolve-target-find-the-right-project.md), we found Pi’s source repository from its project name. The agent can now search that repository for the documentation and implementation behind session storage.
Our `search` tool finds relevant code and documentation from a topic, an API name or a description of the behavior being investigated. Each result gives the agent a location to inspect. It can use the names and paths it finds to make the next search more specific.
[GitHits search explained](https://www.youtube-nocookie.com/embed/Y7ZpLyYiyvU)
## Start with the behavior
GitHits searches repository source and documentation. An agent can identify the source by repository address or by the name and version of a package built from it. It can also search a hosted documentation site.
We call the identifier passed to the tool a **target**. For this investigation, `github:earendil-works/pi` identifies Pi’s repository on GitHub.
The agent can start with terms from the task:
```bash
githits search "coding agent session persistence" --in github:earendil-works/pi --limit 4
```
An agent connected through MCP can make the same `search` request:
```json
{
"target": "github:earendil-works/pi",
"query": "coding agent session persistence",
"limit": 4
}
```
In a lookup on November 3, 2026, the first result was [`packages/coding-agent/docs/session-format.md`](https://github.com/earendil-works/pi/blob/9c9ce8547e5a88cbe834a53e9a6d83a789d08e47/packages/coding-agent/docs/session-format.md#L1-L5). Its opening paragraph describes sessions as JSONL files, with one JSON object per line. It also explains that entries connect through `id` and `parentId` fields to form a tree. The next paragraph points to the `SessionManager` API.
## Follow the class named in the documentation
Functions, classes and interfaces are examples of named code elements, often called **symbols**. GitHits can return these definitions as search results. After finding `SessionManager` in the documentation, the agent can search for its definition:
```bash
githits search "SessionManager" --in github:earendil-works/pi@9c9ce854 --source symbol --limit 3
```
The `--source symbol` option asks for named code definitions. This request returned the `SessionManager` class in `packages/coding-agent/src/core/session-manager.ts`, spanning lines 988–2029.
The `@9c9ce854` suffix selects the commit reported by the first search. Keeping that revision means the documentation and code in this walkthrough come from the same repository state.
The agent can read sections of that file with `read` to find the methods involved in saving a session. In this case, reading the class revealed `_hasConversation`, `_persist` and `_appendEntry`.
## Narrow the search to the relevant code
Pi’s repository contains several packages. A search for session persistence can find code outside the coding agent as well. Once the agent knows the relevant directory, it can include that path in its query:
```bash
githits search "session persistence path:packages/coding-agent/src/" --in github:earendil-works/pi@9c9ce854 --source code --limit 3
```
`--source code` requests source-code results. The `path:` part limits matching to the coding agent’s source directory. This search returned locations in `session-manager.ts` and `agent-session.ts`.
The agent can narrow further when it knows the method and file:
```bash
githits search "_persist path:packages/coding-agent/src/core/session-manager.ts" --in github:earendil-works/pi@9c9ce854 --source code --limit 3
```
The first result identified `SessionManager._persist` at lines 1173–1190. It included source lines showing the persistence checks and the loop that writes session entries. The response also provided a command to read the complete method:
```bash
githits read github:earendil-works/pi@9c9ce854 packages/coding-agent/src/core/session-manager.ts --lines 1173-1190
```
The agent should keep the target, path and line range together when following a result. With a package target, paths are relative to the package’s source directory in the repository. With a repository target, paths are relative to the repository root.
The [search documentation](https://docs.githits.com/tools/code-navigation) covers other query filters, including language, definition name and file purpose.
## Read enough to answer the question
Reading `_persist` and the surrounding methods explains when the file is written:
* `_persist` returns immediately if file persistence is disabled or no session-file path is set.
* Before the first write, `_hasConversation` checks for a user or assistant message. Setup entries alone remain in memory.
* The first write creates the file and writes the accumulated entries as JSON lines.
* Later writes use `appendFileSync` to append the new entry.
The [implementation at revision 9c9ce854](https://github.com/earendil-works/pi/blob/9c9ce8547e5a88cbe834a53e9a6d83a789d08e47/packages/coding-agent/src/core/session-manager.ts#L1161-L1190) shows these branches. For a new session on this write path, the first user message is enough to trigger file creation. It does not have to wait for an assistant response.
The adjacent [`_appendEntry` method](https://github.com/earendil-works/pi/blob/9c9ce8547e5a88cbe834a53e9a6d83a789d08e47/packages/coding-agent/src/core/session-manager.ts#L1192-L1208) shows what happens if writing fails. It removes the new entry from memory, restores the previous position in the session tree and rethrows the error. The caller receives the failure, and later entries won’t refer to the unwritten entry as their parent.
## Search code and documentation through the same tool
The first query left the source selection open and returned documentation. The agent can also choose the kind of result it wants:
| Source option | What it returns | Example from this investigation |
| ------------- | ------------------------------ | ------------------------------------------ |
| `docs` | Documentation sections | The session file format |
| `symbol` | Named code definitions | The `SessionManager` class |
| `code` | Matching source-code locations | The `_persist` method and surrounding code |
A package name and version let GitHits find the repository source used to build that release. An agent inspecting a dependency can often get both from the application’s lockfile. It can also search any public repository on GitHub, GitLab, Codeberg or Launchpad without a published package.
Documentation searches can return files from the repository or pages from a hosted documentation site. The result identifies where the text came from and provides the address to read. Repository documentation can be tied to a commit, as in the Pi example. For a hosted page, the agent needs to check which release it describes. The [documentation guide](https://docs.githits.com/tools/documentation-access) explains how package and site searches connect to those pages.
## Use what the search returns
An unversioned repository search uses its default branch. An unversioned package search uses the latest release. When investigating an installed dependency, the agent should select the version the application uses and check the source revision reported in the result.
The result also reports limits on what was searched or returned. It may provide a next-page offset or indicate that indexing is still underway. If it supplies a `searchRef` and a follow-up action, that reference lets the agent check the progress of the existing search. Repeating the original query starts another search.
Once the agent has an exact error string or identifier to match, `grep` can find its occurrences. When it needs to understand a returned function or documentation section, `read` retrieves that content.
With GitHits connected, try asking your agent:
> Use GitHits to find how Pi writes sessions to disk. Read the code that creates the file and appends entries. Explain when the first write happens and what the caller does if writing fails.
[Product](/blog/tag/product.md) · [Agents](/blog/tag/agents.md) · [Code Navigation](/blog/tag/code-navigation.md)
Olli-Pekka Heinisuo — Co-founder, CTO
Keep exploring
* [The Solution](/the-solution.md)
* [Documentation](https://docs.githits.com/)
* [Changelog](https://docs.githits.com/changelog/overview)
Get started
## GitHits in one command
Install GitHits or refresh an existing setup with the same command.
`npx -y githits@latest init`
Or connect directly
* [Claude connector](https://claude.ai/directory/githits)
* [Cursor plugin](https://cursor.com/marketplace/githits)
* [Vercel connector](https://vercel.com/connect/githits)
* [Manus connector](https://manus.im/app#connectors/all/connector_8387945e-9687-4a71-86b4-8a220dbd5b6b)