Install · How it works · Try it yourself
**pi-brains** gives [Pi](https://github.com/earendil-works/pi) persistent, queryable guidance it can use while it works. Tell Pi what your domain knows, what rules to follow, what mistakes to avoid, or what context to pull in. pi-brains saves that guidance as durable GitSense records, then helps Pi query, apply, and verify it at the right moment. ## Install ```bash pi install npm:@gitsense/pi-brains ``` Start Pi in a workspace and run: ```text /brains ``` If [GitSense (`gsc`)](https://github.com/gitsense/gsc-cli) is not installed, `/brains` will show install instructions. ## How it works 1. **You teach** - Tell Pi what your domain knows, what rules to follow, what mistakes to avoid, or what context to pull in. 2. **It remembers** - pi-brains saves that guidance as focused GitSense records at the personal, repo, file, or topic level. 3. **It applies** - Pi queries those records when they matter: before it starts, before it edits, after it uses a tool, or when a session ends. ### What makes it different pi-brains is not trying to replace hooks, markdown instructions, or search. Hooks react to events. Markdown shares guidance. Search finds text. pi-brains gives Pi focused records it can query and apply while it works. | Approach | Best at | Limitation | | --- | --- | --- | | Hooks | Reacting to workflow events | Hard to teach, browse, and query as durable knowledge | | Markdown docs | Sharing human-readable guidance | Passive unless Pi knows when and where to read them | | Search | Finding matching text or similar passages | Returns matches, not scoped behavioral records | | pi-brains | Storing scoped guidance Pi can query, apply, and verify | Complements source and docs rather than replacing them | The result is not that Pi stops reading source. The result is that Pi gets a better starting point, then verifies important findings against source before acting. ### What rules can do Rules can do more than sit in a doc. They can catch accidental terminal habits, stop risky edits until Pi reads the right context, ask Pi to verify a result, or leave guidance for the next turn. ## Try It Yourself These repos are already set up so you can see how pi-brains works. ### Rules Demo - [`gsc-rules-demos`](https://github.com/gitsense/gsc-rules-demos) Use this repo to see how project knowledge and agent behavior can ship with code. ```bash git clone https://github.com/gitsense/gsc-rules-demos.git cd gsc-rules-demos pi install npm:@gitsense/pi-brains pi ``` Then ask Pi: ```text What rules are shipped with this repository? ``` Pi will walk you through the demo rules, notes, lessons, and triggers included in the repo. - **Quick examples to try** — See the [gsc-rules-demos README](https://github.com/gitsense/gsc-rules-demos#try-the-examples) for prompts you can copy and paste. - **Detailed walkthrough** — See the [Pi Hands-On Guide](https://github.com/gitsense/gsc-rules-demos/blob/main/docs/pi/hands-on.md) for setup notes and expected behavior. **What you'll learn:** rules can change how Pi behaves before it acts, notes can teach project-specific context, lessons can carry previous work into future sessions, and triggers can warn, block, or run checks around tool actions. ### Knowledge Demo - [`gitsense/pi`](https://github.com/gitsense/pi) Use the GitSense Pi fork to try repository intelligence for Pi itself. ```bash git clone https://github.com/gitsense/pi.git cd pi pi install npm:@gitsense/pi-brains pi ``` Build the included Brains: ```text /brains build ``` Then ask Pi to use those Brains before it plans a change: ```text I want to build a Pi extension. Before reading code, use the brains in this repo to find the docs, APIs, gotchas, and examples I should know about. ``` **What you'll learn:** Brains index repository knowledge so Pi can ask what is already known before spending context on source files. | Brain | What Pi learns before opening files | | --- | --- | | Docs | Which guide, section, or reference doc to read | | Code intent | Which files likely matter and why | | Dependency maps | Which files have high blast radius | | Implicit todos | Hidden debt, stubs, workarounds, or cleanup candidates | | Rules | What behavior must be followed | | Lessons | What previous work taught the team | For example, a broad request like this: ```text I want to improve search. Before deciding what to change, use the brains in this repo to identify any gotchas, then verify the important findings against source. ``` can become a focused plan: - "Search" may mean TUI fuzzy matching, autocomplete, session search, model filtering, or agent grep/find tools. - `packages/tui/src/fuzzy.ts` may be shared infrastructure with high blast radius. - Agent `grep.ts` and `find.ts` may be separate from TUI search. - A Brain may surface hidden maintenance work, such as an incomplete stub or deprecated compatibility path. - Pi can verify the relevant findings against source before proposing a plan. Grep finds text. Vector search finds similar passages. Brains give Pi structured, queryable knowledge it can use to decide where to spend context. ## Commands | Command | Description | | --- | --- | | `/brains` | Initialize GitSense expert context | | `/brains build` | Build/import all local Brain manifests from `.gitsense/manifests` | | `/brains build