@gitsense/pi-brains

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