Search: finding code and documentation in open-source projects

An agent working with Pi’s saved sessions needs to know when Pi writes them to disk.

In the resolve_target post, 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.

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:

githits search "coding agent session persistence" --in github:earendil-works/pi --limit 4

An agent connected through MCP can make the same search request:

{
  "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. 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:

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:

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:

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:

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

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