{"slug": "list-browsing-source-files-and-documentation", "title": "List: browsing source files and documentation", "summary": "GitHits released a `list` tool that lets coding agents browse a repository's source tree, documentation and tests, as demonstrated on the Pi coding agent at commit 9c9ce854. The tool takes a target identifier such as `github:earendil-works/pi@9c9ce854`, supports glob patterns like `packages/coding-agent/test/*session*` and `**/*.test.ts`, and offers a `--recursive` flag to expand directories, with the same request available through MCP using a `target`, `paths` and `limit` payload. The walkthrough shows an agent narrowing Pi's `test/session-manager/` directory to eight test files, including `save-entry.test.ts`, before reading the file to confirm it creates an in-memory session and checks entry IDs and positions in the session tree.", "body_md": "[Back to blog](https://githits.com/blog/)\n\nNovember 4, 2026 · 5 min read\n\n# List: browsing source files and documentation\n\nUse GitHits list to browse Pi's source tree, find session tests and documentation, and choose the files to inspect next.\n\nTo check Pi’s session storage, an agent needs its implementation, file-format guide and tests. These live in different directories. Our `list` tool shows the files and folders so the agent can find the parts it needs to inspect.\n\nThe [grep post](https://githits.com/blog/grep-find-exact-matches-in-source/) followed calls through Pi’s session manager. This time, we’ll browse the coding-agent directory to find the related tests and documentation.\n\n## Open a directory\n\nThe repository identifier passed to GitHits is called a **target**. In this example, `github:earendil-works/pi@9c9ce854` selects Pi’s repository at the commit used in the earlier posts.\n\n```\ngithits list github:earendil-works/pi@9c9ce854 packages/coding-agent --limit 30\n```\n\nThe directory listing includes these entries:\n\n```\npackages/coding-agent/CHANGELOG.md\npackages/coding-agent/README.md\npackages/coding-agent/docs/\npackages/coding-agent/examples/\npackages/coding-agent/package.json\npackages/coding-agent/src/\npackages/coding-agent/test/\npackages/coding-agent/vitest.config.ts\n```\n\nDirectories end in `/`. By default, the result shows the selected directory’s immediate children. Here we can see that tests live in `test/`, documentation in `docs/`, and implementation code in `src/`.\n\nThrough MCP, the same `list` request is:\n\n```\n{\n  \"target\": \"github:earendil-works/pi@9c9ce854\",\n  \"paths\": [\"packages/coding-agent\"],\n  \"limit\": 30\n}\n```\n\nOmitting `paths` lists the repository root. A package name and version can also select the repository source used to build that release. In that case, browsing starts at the package’s source directory within the repository. A published package isn’t required to browse a public repository.\n\n## Find the session tests\n\nThe agent knows the subject is session storage, so it can narrow the test filenames:\n\n```\ngithits list github:earendil-works/pi@9c9ce854 'packages/coding-agent/test/*session*' --limit 50\n```\n\nThe `*` characters form a **glob**, a pattern for matching paths. This pattern selects immediate children of `test/` whose names contain `session`. The results include `sdk-session-manager.test.ts`, `session-file-invalid.test.ts` and a `session-manager/` directory.\n\nExpanding that directory gives a smaller set of tests to inspect:\n\n```\ngithits list github:earendil-works/pi@9c9ce854 packages/coding-agent/test/session-manager/ --recursive --limit 50\npackages/coding-agent/test/session-manager/build-context.test.ts\npackages/coding-agent/test/session-manager/custom-session-id.test.ts\npackages/coding-agent/test/session-manager/file-operations.test.ts\npackages/coding-agent/test/session-manager/labels.test.ts\npackages/coding-agent/test/session-manager/load-entries.test.ts\npackages/coding-agent/test/session-manager/migration.test.ts\npackages/coding-agent/test/session-manager/save-entry.test.ts\npackages/coding-agent/test/session-manager/tree-traversal.test.ts\n```\n\n`--recursive` expands selected directories to include files below them. A glob can also specify deeper paths, such as `**/*.test.ts`. Glob depth is controlled by the pattern itself.\n\n## Inspect a file from the listing\n\n`save-entry.test.ts` looks relevant to saving sessions. Opening it shows what it actually tests:\n\n```\ngithits read github:earendil-works/pi@9c9ce854 packages/coding-agent/test/session-manager/save-entry.test.ts --lines 1-55\n```\n\nThe [test creates an in-memory session](https://github.com/earendil-works/pi/blob/9c9ce8547e5a88cbe834a53e9a6d83a789d08e47/packages/coding-agent/test/session-manager/save-entry.test.ts#L4-L54), adds messages and a custom entry, then checks their IDs and positions in the session tree. For file handling, the nearby [`file-operations.test.ts`](https://github.com/earendil-works/pi/blob/9c9ce8547e5a88cbe834a53e9a6d83a789d08e47/packages/coding-agent/test/session-manager/file-operations.test.ts#L23-L94) contains tests for loading valid files, missing headers and malformed JSON.\n\nBrowsing exposed both files. Reading their setup and assertions tells us which one covers the question we’re investigating.\n\n## Find the related source and guides\n\nA single request can select paths from several directories:\n\n```\ngithits list github:earendil-works/pi@9c9ce854 'packages/coding-agent/docs/*session*' 'packages/coding-agent/src/core/*session*' --limit 30\n```\n\nThis returned two guides, `session-format.md` and `sessions.md`, alongside six source files. The source results include `session-manager.ts`, `session-export.ts` and `agent-session.ts`.\n\nThe [session-format guide](https://github.com/earendil-works/pi/blob/9c9ce8547e5a88cbe834a53e9a6d83a789d08e47/packages/coding-agent/docs/session-format.md) describes how entries are stored. The source and test paths found above give us places to inspect how Pi creates, loads and traverses those entries.\n\nFor larger directories, `list` also supports language, file-classification and purpose filters. For example, `--language typescript` selects TypeScript files and `--intent test` selects files classified as tests. The [list reference](https://docs.githits.com/tools/code-navigation) documents the available filters.\n\n## Browse hosted documentation\n\n`list` also browses indexed documentation sites. A documentation search for Express returned `site:expressjs.com`, which can be used to browse its guides:\n\n```\ngithits list site:expressjs.com en/guide/ --limit 10\n```\n\nThe first page included guides for routing, middleware, error handling and database integration. Each page path can be opened with `read`, for example:\n\n```\ngithits read site:expressjs.com en/guide/error-handling\n```\n\nThat listing also returned a continuation cursor because more guides were available. Adding its value with `--after` retrieves the next page using the same target and filters. The `--limit` option controls page size, up to 500 entries per request.\n\nRepository documentation belongs to the selected commit. A hosted site’s pages can change as its maintainers update them. The [documentation guide](https://docs.githits.com/tools/documentation-access) explains browsing and reading both.\n\n## Finding the files worth opening\n\nOur `list` tool browses directories and documentation pages, matches path patterns, and filters source inventories by language or file purpose. Recursive listings expose nested files, and pagination makes larger inventories manageable.\n\nIn Pi, we found the coding agent’s source, documentation and test directories. We narrowed the session tests, inspected the difference between an in-memory entry test and file-loading tests, and found the related guides and implementation files.\n\nAgents already browse directory trees and filenames when working in a local codebase. GitHits gives them that way of exploring public repositories, dependency source and hosted documentation before opening the relevant content with `read`.\n\nWith GitHits connected, try asking your agent:\n\nUse GitHits list to find Pi’s session-manager tests and documentation. Open the tests that cover file loading and explain which cases they check. Keep the repository files on the same commit.", "url": "https://wpnews.pro/news/list-browsing-source-files-and-documentation", "canonical_source": "https://githits.com/blog/list-browse-source-and-documentation/", "published_at": "2026-11-04 00:00:00+00:00", "updated_at": "2026-11-04 11:26:46.689566+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["GitHits", "Pi", "earendil-works", "save-entry.test.ts", "MCP"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/list-browsing-source-files-and-documentation", "markdown": "https://wpnews.pro/news/list-browsing-source-files-and-documentation.md", "text": "https://wpnews.pro/news/list-browsing-source-files-and-documentation.txt", "jsonld": "https://wpnews.pro/news/list-browsing-source-files-and-documentation.jsonld"}}