Graphify AI编码助手

Prerequisites

macOS quick install (Homebrew):

brew install python@3.12 uv

Windows quick install:

winget install astral-sh.uv

Ubuntu/Debian: ```bash sudo apt install python3.12 python3-pip pipx

(pytest). uv installs the dev dependency group by default; pass --no-dev to

or install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh ```

---

Install

Official package: The PyPI package is graphifyy (double-y). Other graphify* packages on PyPI are not affiliated. The CLI command is still graphify.

Step 1 — install the package:

```bash

Team setup

graphify-out/ is meant to be committed to git so everyone on the team starts with a map.

Recommended .gitignore additions: ``` graphify-out/cost.json # local only

Development setup

The project uses uv for dev workflow. Install it once, then:

```bash git clone https://github.com/safishamsi/graphify.git cd graphify git checkout v8 # active development branch

Create the project venv and install graphify + all extras + the dev group

Recommended (isolated env; if 'graphify' isn't found after, run: uv tool update-shell):

uv tool install graphifyy

Optional extras

Install only what you need:

---

graphify-out/cache/ # optional: commit for speed, skip to keep repo small

```

manifest.json is now portable — keys are stored as relative paths and re-anchored on load, so committing it is safe and avoids a full rebuild on first checkout.

Workflow: 1. One person runs /graphify . and commits graphify-out/. 2. Everyone pulls — their assistant reads the graph immediately. 3. Run graphify hook install to auto-rebuild after each commit (AST only, no API cost). This also sets up a git merge driver so graph.json is never left with conflict markers — two devs committing in parallel get their graphs union-merged automatically. 4. When docs or papers change, run /graphify --update to refresh those nodes.

---

Environment variables

These are only needed for headless / CI extraction (graphify extract). When running via the /graphify skill inside your IDE, the model API is provided by your IDE session — no extra keys needed.

---

Full command reference

``` /graphify # run on current directory /graphify ./raw # run on a specific folder /graphify ./raw --mode deep # more aggressive relationship extraction /graphify ./raw --update # re-extract only changed files /graphify ./raw --directed # preserve edge direction /graphify ./raw --cluster-only # rerun clustering on existing graph /graphify ./raw --no-viz # skip HTML visualization /graphify ./raw --obsidian # generate Obsidian vault /graphify ./raw --wiki # build agent-crawlable markdown wiki /graphify ./raw --svg # export graph.svg /graphify ./raw --graphml # export for Gephi / yEd /graphify ./raw --neo4j # generate cypher.txt for Neo4j /graphify ./raw --neo4j-push bolt://localhost:7687 /graphify ./raw --falkordb # generate cypher.txt for FalkorDB /graphify ./raw --falkordb-push falkordb://localhost:6379 /graphify ./raw --watch # auto-sync as files change /graphify ./raw --mcp # start MCP stdio server

/graphify add https://arxiv.org/abs/1706.03762 /graphify add <video-url> /graphify add https://... --author "Name" --contributor "Name"

/graphify query "what connects attention to the optimizer?" /graphify query "..." --dfs --budget 1500 /graphify path "DigestAuth" "Response" /graphify explain "SwinTransformer"

graphify save-result --question "Q" --answer "A" --nodes Foo Bar --outcome useful # record how a Q&A turned out (work memory; outcome ∈ useful|dead_end|corrected) graphify reflect # aggregate graphify-out/memory/ outcomes into reflections/LESSONS.md graphify reflect --if-stale # no-op when LESSONS.md is already newer than every input (cheap to run each session) graphify reflect --out docs/LESSONS.md # write the lessons doc somewhere else graphify reflect --graph graphify-out/graph.json # also group lessons by community

graphify uninstall # remove from all platforms in one shot graphify uninstall --purge # also delete graphify-out/ graphify uninstall --project --platform codex # remove project-scoped install files only

graphify hook install # post-commit + post-checkout hooks graphify hook uninstall graphify hook status

Git workflow

• Active development happens on the v8 branch.
• Commit style: fix: <description> / feat: <description> / docs: <description>
• Before opening a PR, run uv run pytest tests/ -q and confirm it passes.
• Add a fixture file to tests/fixtures/ and tests to tests/test_languages.py for any new language extractor.

Alternatives:

pipx install graphifyy pip install graphifyy # may need PATH setup — see note below

**Step 2 — register the skill with your AI assistant:**

That's it. Open your AI assistant and type `/graphify .`

To install the assistant skill into the current repository instead of your user
profile, add `--project`:

Project-scoped installs write under the current directory, for example .claude/skills/graphify/SKILL.md or .agents/skills/graphify/SKILL.md (plus a references/ sidecar the skill loads on demand), and print a git add hint for files that can be committed. Per-platform commands that support project-scoped installs accept the same flag, for example graphify claude install --project or graphify codex install --project.

PowerShell note: Use graphify . not /graphify . — the leading slash is a path separator in PowerShell.

graphify: command not found? uv tool install / pipx install put the graphify command in their tool bin dir (~/.local/bin). If your shell can't find it right after install — common on a fresh macOS + zsh setup — that dir isn't on your PATH yet: run uv tool update-shell (or pipx ensurepath), then open a new terminal. With plain pip, add ~/.local/bin (Linux) or ~/Library/Python/3.x/bin (Mac) to your PATH, or run python -m graphify.

Running with uvx / uv tool run instead of installing? Name the package, not the command: uvx --from graphifyy graphify install. Plain uvx graphify … fails (No solution found … no versions of graphify) because uv tool run reads the first word as a package, and the package is graphifyy — the graphify command lives inside it.

Avoid pip install on Mac/Windows if possible. The skill resolves Python at runtime from graphify-out/.graphify_python; if that points to a different environment than where pip installed the package, you'll get ModuleNotFoundError: No module named 'graphify'. uv tool install and pipx install isolate the package in their own env and avoid this entirely.

Git hooks and uv tool / pipx: graphify hook install embeds the current interpreter path directly into the hook scripts at install time, so the post-commit hook fires correctly even in GUI git clients and CI runners where ~/.local/bin is not on PATH. If you reinstall or upgrade graphify, re-run graphify hook install to refresh the embedded path.

Troubleshooting

graphify: command not found after installing The CLI is installed but its bin directory isn't on your shell's PATH. Pick the fix for how you installed: - uv (uv tool install graphifyy): the command lands in uv's tool bin dir (~/.local/bin), which a fresh macOS/zsh setup often doesn't have on PATH. Run uv tool update-shell, then open a new terminal. (Find the dir with uv tool dir --bin.) - pipx (pipx install graphifyy): run pipx ensurepath, then open a new terminal. - pip (pip install graphifyy): pip installs scripts to a user bin dir that may not be on PATH — add ~/Library/Python/3.x/bin (macOS) or ~/.local/bin (Linux) to your PATH in ~/.zshrc/~/.bashrc, or just run python -m graphify.

uvx graphify … or uv tool run graphify … fails to resolve graphify The PyPI package is graphifyy; graphify is only the command it provides. uv tool run treats the first word as a package name, so it looks for a package called graphify and reports No solution found … no versions of graphify. Name the package explicitly: uvx --from graphifyy graphify install (same as uv tool run --from graphifyy graphify install). Or uv tool install graphifyy once and then call graphify directly.

python -m graphify works but graphify command doesn't Your shell's PATH doesn't include the bin directory the command was installed to. Prefer uv tool install / pipx install over plain pip, then run uv tool update-shell / pipx ensurepath and open a new terminal (see the install notes above).

/graphify . causes "path not recognized" in PowerShell PowerShell treats a leading / as a path separator. Use graphify . (no slash) on Windows.

Graph has fewer nodes after --update or rebuild If a refactor deleted files, the old nodes linger. Pass --force (or set GRAPHIFY_FORCE=1) to overwrite even when the rebuild has fewer nodes.

Graph has duplicate nodes for the same entity (ghost duplicates) Ghost duplicates (same symbol appearing twice — once from AST extraction with a source location, once from semantic extraction without) are now automatically merged at build time. If you see this in a graph built before v0.8.33, run a full re-extract to clean up:

graphify extract . --force

Ollama runs out of VRAM / context window exceeded The KV-cache window is auto-sized but may be too large for your GPU. Reduce it:

GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000

LLM returned invalid JSON / Unterminated string warnings The model's JSON response hit its output-token limit and was cut off mid-string. graphify auto-recovers (it splits the chunk and re-extracts the halves, and an oversized single document is first sliced at heading/paragraph boundaries so the whole file is still covered), so these warnings are noisy but not data loss. To reduce the churn, raise the output cap or shrink each chunk's output:

GRAPHIFY_MAX_OUTPUT_TOKENS=16384 graphify extract . --mode deep   # lift the cap
graphify extract . --mode deep --token-budget 4000                # smaller input chunks -> smaller output

Graph HTML is too large to open in a browser (>5000 nodes) Skip HTML generation and use the JSON directly:

graphify cluster-only ./my-project --no-viz
graphify query "..."

graph.json has conflict markers after two devs commit at once Run graphify hook install — it sets up a git merge driver that union-merges graph.json automatically so conflicts never happen.

Extraction returns empty nodes/edges for docs or PDFs Docs, PDFs, and images require an LLM call — code-only corpora need no key. Check that your API key is set and the backend is correct:

ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude

Skill version mismatch warning in your IDE Your installed graphify version is different from the skill file. Update:

uv tool upgrade graphifyy
graphify install  # overwrites the skill file

---