pi-brains gives 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

pi install npm:@gitsense/pi-brains

Start Pi in a workspace and run:

/brains

If GitSense (gsc) 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

Use this repo to see how project knowledge and agent behavior can ship with code.

git clone https://github.com/gitsense/gsc-rules-demos.git
cd gsc-rules-demos
pi install npm:@gitsense/pi-brains
pi

Then run /brains and ask Pi:

/brains
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 for prompts you can copy and paste.
• Detailed walkthrough — See the Pi Hands-On Guide 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

Use the GitSense Pi fork to try repository intelligence for Pi itself.

git clone https://github.com/gitsense/pi.git
cd pi
pi install npm:@gitsense/pi-brains
pi

Build the included Brains:

/brains build

Then ask Pi to use those Brains before it plans a change:

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:

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 <brain-name> | Build/import one local Brain manifest | | /brains build <manifest-path-or-url> | Build/import a Brain from a path or URL | | /brains build --force | Rebuild Brain manifests even if cached data exists | | /brains build help | Show Brain build help and current Brain status | | /brains insights | Show session status and brain data | | /brains rules | Show rule status and options | | /brains rules on | Enable rules checking | | /brains rules off | Disable rules checking | | /brains rules status | Show recent rule decisions | | /brains about | Show what GitSense can do | | /brains debug | Toggle debug logging | | /brains debug on | Enable debug logging | | /brains debug off | Disable debug logging | | /brains debug file | Show the debug log file path | | /brains dismiss | Dismiss the GitSense unavailable notice | | /brains help | Show available commands |

Current Boundaries

• File tracking is exact for structured read, edit, and write tools.
• Arbitrary shell file activity may be missing.
• Brain analysis and cross-session history require GitSense integration.
• Brains are guidance, not a replacement for source verification.

Development

npm install
npm run check
npm test

To try local changes in Pi, install this package from your checkout:

pi install /path/to/pi-brains
pi

Then run:

/brains

License

MIT