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

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/manifest.json # mtime-based, breaks after git clone graphify-out/cost.json # local only

Development setup

Clone the repo and install in editable mode:

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

Install in editable mode with all optional extras:

pip install -e ".[all]"

Verify the editable install:

Optional extras

Install only what you need:

---

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

```

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.

---

Create a virtual environment (Python 3.10+ required):

python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate

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 --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 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

graphify claude install / uninstall
graphify codex install / uninstall
graphify opencode install
graphify cursor install / uninstall
graphify gemini install / uninstall
graphify copilot install / uninstall
graphify aider install / uninstall
graphify claw install / uninstall
graphify droid install / uninstall
graphify trae install / uninstall
graphify trae-cn install / uninstall
graphify hermes install / uninstall
graphify kiro install / uninstall
graphify antigravity install / uninstall

graphify extract ./docs                        # headless LLM extraction for CI (no IDE needed)
graphify extract ./docs --backend gemini       # explicit backend: gemini, kimi, claude, openai, deepseek, ollama, bedrock, or claude-cli
graphify extract ./docs --backend gemini --model gemini-3.1-pro-preview
graphify extract ./docs --backend ollama       # local Ollama (set OLLAMA_BASE_URL / OLLAMA_MODEL) - no API key needed for loopback
GRAPHIFY_OLLAMA_NUM_CTX=32768 graphify extract ./docs --backend ollama   # override KV-cache window (auto-sized by default)
GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama    # unload model after each chunk (saves VRAM on small GPUs)
graphify extract ./docs --backend bedrock      # AWS Bedrock via IAM - no API key, uses AWS credential chain
graphify extract ./docs --backend claude-cli   # route through Claude Code CLI - no API key, uses your Claude subscription
graphify extract ./docs --max-workers 16       # AST parallelism (also GRAPHIFY_MAX_WORKERS)
graphify extract ./docs --token-budget 30000   # smaller semantic chunks for local/small models
graphify extract ./docs --max-concurrency 2    # fewer parallel LLM calls (useful for local inference)
graphify extract ./docs --api-timeout 900      # longer HTTP timeout for slow local models (default 600s)
graphify extract ./docs --google-workspace     # export .gdoc/.gsheet/.gslides via gws before extraction
graphify extract ./docs --no-cluster           # raw extraction only, skip clustering
graphify extract ./docs --force                # overwrite graph.json even if new graph has fewer nodes (use after refactors or to clear ghost duplicates)
graphify extract ./docs --dedup-llm            # LLM tiebreaker for ambiguous entity pairs (uses same API key)
graphify extract ./docs --global --as myrepo   # extract and register into the cross-project global graph
GRAPHIFY_MAX_OUTPUT_TOKENS=32768 graphify extract ./docs --backend claude  # raise output cap for dense corpora

graphify export callflow-html                       # graphify-out/<project>-callflow.html
graphify export callflow-html --max-sections 8      # cap generated architecture sections
graphify export callflow-html --output docs/arch.html
graphify export callflow-html ./some-repo/graphify-out

graphify global add graphify-out/graph.json myrepo   # register a project graph into ~/.graphify/global.json
graphify global remove myrepo                         # remove a project from the global graph
graphify global list                                  # show all registered repos + node/edge counts
graphify global path                                  # print path to the global graph file

graphify prs                              # PR dashboard: CI, review, worktree, graph impact
graphify prs 42                           # deep dive on PR #42
graphify prs --triage                     # AI triage ranking (auto-detects backend from env)
graphify prs --worktrees                  # worktree → branch → PR mapping
graphify prs --conflicts                  # PRs sharing graph communities (merge-order risk)
graphify prs --base main                  # filter to PRs targeting a specific base branch
graphify prs --repo owner/repo            # run against a different GitHub repo
GRAPHIFY_TRIAGE_BACKEND=kimi graphify prs --triage   # use a specific backend for triage

graphify clone https://github.com/karpathy/nanoGPT
graphify merge-graphs a.json b.json --out merged.json
graphify --version                                    # print installed version
graphify watch ./src
graphify check-update ./src
graphify update ./src
graphify update ./src --no-cluster  # skip reclustering, write raw AST graph only
graphify update ./src --force       # overwrite even if new graph has fewer nodes
graphify cluster-only ./my-project
graphify cluster-only ./my-project --graph path/to/graph.json  # custom graph location
graphify cluster-only ./my-project --resolution 1.5            # more, smaller communities
graphify cluster-only ./my-project --exclude-hubs 99           # exclude p99 degree nodes from partitioning

---

Git workflow

• Active development happens on the v8 branch.
• Commit style: fix: <description> / feat: <description> / docs: <description>
• Before opening a PR, 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

**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, 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? Use uv tool install graphifyy or pipx install graphifyy — both put the CLI on PATH automatically. With plain pip, add ~/.local/bin (Linux) or ~/Library/Python/3.x/bin (Mac) to your PATH, or run python -m graphify.

Troubleshooting

graphify: command not found after pip install graphifyy pip installs scripts to a user bin directory that may not be on your PATH. Fix: - macOS: add ~/Library/Python/3.x/bin to your PATH in ~/.zshrc - Linux: add ~/.local/bin to your PATH in ~/.bashrc - Or use uv tool install graphifyy / pipx install graphifyy — both manage PATH automatically.

python -m graphify works but graphify command doesn't Your shell's PATH doesn't include the Python scripts directory. Use uv or pipx instead of plain pip.

/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) This happens when semantic and AST extraction disagreed on the node ID format. 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

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 and PDFs require an LLM call. 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

---