Give Your Coding Agent Eyes

Coding agents usually start blind when a new session begins, requiring them to rediscover how features work. The AGENTS.md file is typically used to load all relevant information into each session, but it can be too sparse or too resource-intensive. A better approach is to use a catalog system where each feature in the project has a small note associated with it.

At startup, the agent loads only a table of paths and descriptions for each feature, without loading the actual content. When the agent encounters a task that matches a feature's description, it then reads the corresponding note for more details. The catalog needs to be regenerated periodically, such as every 20 commits or at the end of each sprint, to ensure it remains up-to-date with the current codebase.

The agent receives contextual information from a pi extension called pi-context, which hooks into the agent's startup routine. This extension walks up from the current working directory to find the project root via AGENTS.md or CLAUDE.md files, recursively scans directories for Markdown files, and keeps only those with a description frontmatter field. The catalog is then formatted and injected into the system prompt.

Each note in the catalog is organized by feature and limited to around 5 KB in size. The description acts as a trigger condition, determining when the agent should load the note based on the task at hand. This approach minimizes the amount of information the agent needs to process and allows for efficient retrieval of relevant information when needed.