November 4, 2026 · 6 min read
Read: inspecting source code and documentation
Use GitHits read to inspect a function, follow its helpers and read documentation at the same revision. See what Pi's session writes return and when.
An agent using Pi’s session manager needs to know whether a returned message ID means the message was written to disk.
In the list post, we found Pi’s session-manager source, tests and documentation. The earlier grep post located appendMessage in that source. Our read tool retrieves its definition directly. The same tool can read a file range, repository documentation or a section of a hosted documentation page.
Read a method by name
Functions, methods and classes are named code elements, also called symbols. When the agent knows a symbol’s name, it can pass that name to read as a selector. It doesn’t need to search for the name again.
githits read github:earendil-works/pi@9c9ce854 packages/coding-agent/src/core/session-manager.ts --selector appendMessage
The repository identifier is the target. Its @9c9ce854 suffix selects the commit used in the earlier posts. The path identifies the file where appendMessage is declared.
An agent connected through MCP can make the same request:
{
"target": "github:earendil-works/pi@9c9ce854",
"path": "packages/coding-agent/src/core/session-manager.ts",
"selector": "appendMessage"
}
This returned lines 1215–1225 of a 2,029-line file. The response includes the path, returned line range and source revision, followed by the code.
appendMessage creates an entry with an ID, a parent ID, a timestamp and the message. It then calls _appendEntry(entry) and returns the ID. The write happens through that helper, so the agent needs its definition too.
Follow the calls that decide the answer
The agent can read _appendEntry from the same file:
githits read github:earendil-works/pi@9c9ce854 packages/coding-agent/src/core/session-manager.ts --selector _appendEntry
That method adds the entry to the in-memory session, then calls _persist. If _persist throws, _appendEntry removes the entry, restores the previous parent position and rethrows the error. The exception reaches appendMessage before it can return an ID.
Reading _persist shows when a write is attempted:
githits read github:earendil-works/pi@9c9ce854 packages/coding-agent/src/core/session-manager.ts --selector _persist
Its first condition returns immediately if persistence is disabled or there is no session-file path. For the first write, it also calls _hasConversation. Reading that helper shows it checks for a user or assistant message among the stored entries.
The four methods at this commit explain what the caller can infer:
| Condition | What happens |
|---|---|
| Persistence is disabled, or no file path is set | The entry stays in memory and appendMessage returns its ID |
| The first write is pending and there is no user or assistant message | Entries remain in memory until that condition is met |
| The first write can proceed | _persist creates the file and writes the accumulated entries |
| The initial write has completed | _persist appends the new entry to the file |
_persist throws | _appendEntry removes the new in-memory entry and propagates the error |
A returned ID can therefore refer to an entry kept in memory. An agent integrating with this API needs to check how the session manager was configured before treating the ID as confirmation of a file write.
Read nearby methods together
Symbol selection is useful when the agent knows a declaration name. Search and grep results also provide file paths and line numbers. If the required methods are close together, one range can include them all:
githits read github:earendil-works/pi@9c9ce854 packages/coding-agent/src/core/session-manager.ts --lines 1167-1225
This 59-line range covers _hasConversation, _persist, _appendEntry and appendMessage. An agent that already has those locations can read them together. After reading them individually, it can reuse the content it has.
Through MCP, the bounds are start_line and end_line. Both are inclusive:
{
"target": "github:earendil-works/pi@9c9ce854",
"path": "packages/coding-agent/src/core/session-manager.ts",
"start_line": 1167,
"end_line": 1225
}
Choose the range around the question. A write inside a try block may require the following catch and finally blocks. A call inside a branch may require the condition above it. If the answer depends on another method, follow that declaration.
MCP text reads return up to 150 lines by default and up to 300 with explicit bounds. A larger request reports truncation and where to continue. The CLI can return a complete file for piping. Those limits and the selector behavior are documented in the read reference.
Read documentation at the same revision
The same request shape works for documentation stored in the repository:
githits read github:earendil-works/pi@9c9ce854 packages/coding-agent/docs/session-format.md --lines 1-5
The opening of Pi’s session-format guide describes JSON Lines storage and the id and parentId fields that link entries into a tree. Keeping the same commit ties that description to the code we inspected.
Our read tool also opens hosted documentation pages found through search or list. A page URL opens the page, and a heading link selects a section. The documentation guide shows the supported forms.
Pi’s session-format guide lives in its repository, so we can read the guide and implementation from the same commit. A hosted API reference may describe a newer release than the one you’re using. Its version selector or release label helps establish which implementation the page describes.
Reading code with GitHits
Our read tool opens source files, named functions and classes, line ranges, and documentation pages or sections. It works with public repositories and the repository source behind packages, as well as hosted documentation.
In Pi, we started with appendMessage and followed the helpers that store an entry. Reading those methods showed why a returned ID can refer to a message held in memory and how a write error reaches the caller. We also read the session-format guide from the same commit to check how the entries are stored.
Agents already inspect local codebases this way: open a declaration, follow its calls and read the relevant branches. GitHits gives them that workflow for public dependency source and documentation too.
With GitHits connected, try asking your agent:
Use GitHits read to inspect Pi’s appendMessage method and the helpers that store an entry. Explain when it returns an ID without writing a file and what happens if a write throws. Keep the code and documentation on the same commit.
