graphify-pi

Pi extension and skill package for graphify.

It brings graphify's Claude-style graph-first workflow to pi:

• injects graphify guidance into the system prompt when graphify-out/ exists
• reminds the agent to read graph artifacts before broad raw search/read operations
• prefers graphify-out/wiki/index.md when present, then GRAPH_REPORT.md, then graph.json
• marks stale graphs when graphify-out/needs_update exists or code files changed in-session
• recommends graphify update . before relying on modified areas
• registers a native /graphify ... pi command that delegates to the graphify skill
• shows a small graphify status indicator in pi
• includes a /skill:graphify skill for build/update/query/path/explain/clone/merge/MCP workflows

Parity target

Current parity target: upstream safishamsi/graphify v0.5.x Claude integration and skill workflow.

See docs/PARITY.md for the detailed parity matrix, intentional non-goals, and maintenance checklist.

Short version:

| Area | Status | | --- | --- | | Always-on Claude-style graph reminder | Implemented in Pi extension | | Wiki/report/graph artifact preference | Implemented; Pi prefers wiki first | | needs_update and post-edit freshness | Implemented | | /graphify trigger | Implemented as Pi command | | Full graphify CLI workflow guidance | Implemented in Pi skill docs | | Upstream Python graph building internals | Inherited from installed graphifyy, not vendored | | Claude-specific files/hooks | Not applicable; Pi uses extensions/skills |

Install

From a local checkout:

pi install .

Or for just the current project:

pi install -l .

From npm:

pi install npm:graphify-pi

From git:

pi install git:github.com/juhas96/graphify-pi

Graphify itself is a Python package. If the graphify CLI is not installed:

uv tool install graphifyy
# or
pipx install graphifyy
# or
python3 -m pip install graphifyy

Usage

Native Pi command

/graphify .
/graphify update .
/graphify query "show the auth flow"
/graphify path "AuthModule" "Database"
/graphify explain "DigestAuth"
/graphify https://github.com/owner/repo

The command sends a user message instructing the agent to use the packaged graphify skill with your arguments.

Skill command

/skill:graphify .
/skill:graphify update .
/skill:graphify query "show the auth flow"

Direct CLI commands

graphify .
graphify update .
graphify . --wiki
graphify query "show the auth flow" --graph graphify-out/graph.json
graphify path "AuthModule" "Database" --graph graphify-out/graph.json
graphify explain "DigestAuth" --graph graphify-out/graph.json
graphify clone https://github.com/owner/repo
graphify merge-graphs repo-a/graphify-out/graph.json repo-b/graphify-out/graph.json --out graphify-out/cross-repo-graph.json
python -m graphify.serve graphify-out/graph.json

What the extension does

When a graph exists, the extension adds graph-first guidance equivalent to the Claude/OpenCode reminder:

graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files.

Pi adds more context than the simple Claude hook:

• wiki-first preference when graphify-out/wiki/index.md exists
• graph.json fallback when report/wiki are absent
• cross-module query guidance for graphify query, graphify path, and graphify explain
• targeted raw-file follow-up after graph artifact inspection
• stale graph warnings from needs_update or in-session code edits

Files

• extensions/graphify.ts — pi extension
• skills/graphify/SKILL.md — pi graphify skill
• docs/PARITY.md — parity matrix against upstream graphify Claude integration
• evals/graphify-agent.test.ts — deterministic extension behavior evals
• evals/run-live.ts — model-in-the-loop, rule-based live eval runner
• evals/run-judge.ts — LLM-as-judge eval runner for live traces
• evals/render-report.ts — compact leaderboard/report generator
• evals/judge-rubric.md — scoring rubric for the judge run
• evals/scenarios/*.json — live eval scenarios
• package.json — pi package manifest

Evals

Deterministic behavior evals:

npm run evals

LLM-driven evals:

npm run evals:live:dry
npm run evals:live
npm run evals:judge:dry
npm run evals:judge
npm run evals:report

Run the full pipeline:

npm run evals:full

Optional model selection:

PI_EVAL_MODEL=anthropic/claude-sonnet-4-20250514 npm run evals:live
PI_JUDGE_MODEL=anthropic/claude-sonnet-4-20250514 npm run evals:judge

Current deterministic eval coverage includes:

• graph-first prompt injection
• report-first orientation
• wiki-first orientation
• graph.json-only fallback
• redirect-loop prevention
• targeted raw-file follow-up
• stale graph status for graphify-out/needs_update
• stale graph status after code edits
• /graphify command delegation

Live scenarios cover:

• report-first orientation
• wiki-first orientation
• graph.json-only fallback
• graph.json-only adversarial search bait
• raw filename bait vs graph report
• refresh-loop triage with targeted code follow-up
• semantic routing triage with wiki + targeted router follow-up
• wiki ownership chain with targeted raw follow-up
• stale graph / needs_update guidance
• graph query/path command selection for relationship questions

Outputs:

• live trace summary: evals/results/last-live.json
• judge summary: evals/results/last-judge.json
• compact leaderboard/report: evals/results/last-report.md

Publishing

Dry-run the package contents:

npm run pack:check

Publish to npm:

npm publish

The package is configured to publish:

• extensions/
• skills/
• docs/
• README.md
• LICENSE

Local helper/reference folders such as upstream-graphify/ are not shipped.