diff --git a/README.md b/README.md index ed4b09f4d..80cc94225 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@
Read this in other languages -🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇮🇳 हिन्दी | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇷 فارسی | 🇮🇹 Italiano | 🇵🇱 Polski | 🇳🇱 Nederlands | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇸🇪 Svenska | 🇬🇷 Ελληνικά | 🇷🇴 Română | 🇨🇿 Čeština | 🇫🇮 Suomi | 🇩🇰 Dansk | 🇳🇴 Norsk | 🇭🇺 Magyar | 🇹🇭 ภาษาไทย | 🇺🇿 Oʻzbekcha | 🇹🇼 繁體中文 | 🇵🇭 Filipino | 🇮🇱 עברית +English | 简体中文 | 日本語 | 한국어 | Deutsch | Français | Español | हिन्दी | Português | Русский | العربية | فارسی | Italiano | Polski | Nederlands | Türkçe | Українська | Tiếng Việt | Bahasa Indonesia | Svenska | Ελληνικά | Română | Čeština | Suomi | Dansk | Norsk | Magyar | ภาษาไทย | Oʻzbekcha | 繁體中文 | Filipino | עברית
@@ -64,16 +64,16 @@ That's it. You get **three files**: ``` graphify-out/ -├── graph.html open in any browser — click nodes, filter, search +├── graph.html open in any browser: click nodes, filter, search ├── GRAPH_REPORT.md the highlights: key concepts, surprising connections, suggested questions -└── graph.json the full graph — query it anytime without re-reading your files +└── graph.json the full graph: query it anytime without re-reading your files ``` The persisted graph includes `graph.schema_version` so integrations can detect incompatible format changes, plus `graph.graphify_version` identifying the Graphify release that produced it. -**Works in** Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and 15+ more — [pick your platform](#install). +**Works in** Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and 15+ more: [pick your platform](#install). --- @@ -81,11 +81,11 @@ Graphify release that produced it. Full guides and reference live at **[docs.graphify.com](https://docs.graphify.com)**: -- **[Quickstart](https://docs.graphify.com/quickstart)** — build your first graph -- **[CLI reference](https://docs.graphify.com/reference/overview)** — every command and flag -- **[Ask better graph questions](https://docs.graphify.com/guides/querying)** — querying patterns -- **[Configuration](https://docs.graphify.com/reference/configuration)** — environment variables and tuning -- **[Supported inputs](https://docs.graphify.com/concepts/supported-inputs)** — languages and file types +- **[Quickstart](https://docs.graphify.com/quickstart)**: build your first graph +- **[CLI reference](https://docs.graphify.com/reference/overview)**: every command and flag +- **[Ask better graph questions](https://docs.graphify.com/guides/querying)**: querying patterns +- **[Configuration](https://docs.graphify.com/reference/configuration)**: environment variables and tuning +- **[Supported inputs](https://docs.graphify.com/concepts/supported-inputs)**: languages and file types - **[Team workflows](https://docs.graphify.com/guides/team-workflows)** and **[PR review](https://docs.graphify.com/guides/pull-requests)** - **[Troubleshooting](https://docs.graphify.com/troubleshooting)** and **[How it works](https://docs.graphify.com/concepts/architecture)** @@ -189,7 +189,7 @@ curl -LsSf https://astral.sh/uv/install.sh | sh The official source repository is [Graphify-Labs/graphify](https://github.com/Graphify-Labs/graphify). -**Step 1 — install the package:** +**Step 1. Install the package:** ```bash # Recommended (isolated env; if 'graphify' isn't found after, run: uv tool update-shell): @@ -197,10 +197,10 @@ uv tool install graphifyy # Alternatives: pipx install graphifyy -pip install graphifyy # may need PATH setup — see note below +pip install graphifyy # may need PATH setup: see note below ``` -**Step 2 — register the skill with your AI assistant:** +**Step 2. Register the skill with your AI assistant:** ```bash graphify install @@ -257,7 +257,7 @@ for example `graphify claude install --project` or `graphify codex install --pro Codex users also need `multi_agent = true` under `[features]` in `~/.codex/config.toml` for parallel extraction. CodeBuddy uses the same Agent tool and PreToolUse hook mechanism as Claude Code. Factory Droid uses the `Task` tool for parallel subagent dispatch. OpenClaw and Aider use sequential extraction (parallel agent support is still early on those platforms). Trae uses the Agent tool for parallel subagent dispatch and does **not** support `PreToolUse` hooks, so AGENTS.md is the always-on mechanism. -`--platform agents` (alias `--platform skills`) targets the generic cross-framework [Agent-Skills](https://github.com/anthropics/skills) locations: the spec's user-global `~/.agents/skills/` (read by `npx skills` and spec-compliant frameworks) for a global install, and `./.agents/skills/` for a project (`--project`) install. The bare `graphify install` stays single-platform (Claude Code) by design — use the named `agents` platform when you want the skill discoverable by any framework that reads `.agents/skills`. +`--platform agents` (alias `--platform skills`) targets the generic cross-framework [Agent-Skills](https://github.com/anthropics/skills) locations: the spec's user-global `~/.agents/skills/` (read by `npx skills` and spec-compliant frameworks) for a global install, and `./.agents/skills/` for a project (`--project`) install. The bare `graphify install` stays single-platform (Claude Code) by design: use the named `agents` platform when you want the skill discoverable by any framework that reads `.agents/skills`. Pi has no `PreToolUse` hook, so `graphify pi guard install` registers a native Pi extension (via Pi's own `pi install `) that runs the installed `graphify hook-guard` before Pi's `read`, `grep`, `find` and search-style `bash` calls. Fresh/stale graph decisions and the `GRAPHIFY_HOOK_STRICT=1` once-per-session indexed-read denial come from that same policy, so Pi matches Claude Code's hook behavior; guidance arrives as a `` steering message. It needs Pi 0.58.4 or newer: earlier versions let a steering message skip the rest of a parallel tool-call batch. The package ships inside the Graphify installation, so install Graphify persistently (`uv tool install graphifyy` or `pipx install graphifyy`, not `uvx`), restart Pi after installing or upgrading, and remove it with `graphify pi guard uninstall`. Only local file targets are inspected; the hook needs `graphify` on an absolute `PATH` entry outside the project, is bounded to a two-second, 256 KiB-in/64 KiB-out call, and fails open. The same package also loads in [Oh My Pi](https://github.com/can1357/oh-my-pi): `omp plugin install "$(graphify pi guard path)"`. The registered path contains the Python version and venv, so re-run `graphify pi guard install` after changing either, and remove the old entry with `pi remove `. @@ -369,13 +369,13 @@ graphify export callflow-html # Mermaid architecture/call-flow HTML (auto-r /graphify add https://arxiv.org/abs/1706.03762 # fetch a paper and add it /graphify add # transcribe and add a video -graphify hook install # auto-rebuild on commit + branch checkout (run `graphify update .` after `git pull` — see "Recommended workflow" below) +graphify hook install # auto-rebuild on commit + branch checkout (run `graphify update .` after `git pull`: see "Recommended workflow" below) graphify merge-graphs a.json b.json # combine two graphs graphify prs # PR dashboard: CI state, review status, worktree mapping graphify prs 42 # deep dive on PR #42 with graph impact graphify prs --triage # AI ranks your review queue (uses whatever backend is configured) -graphify prs --conflicts # PRs sharing graph communities — merge-order risk +graphify prs --conflicts # PRs sharing graph communities: merge-order risk ``` See the [full command reference](#full-command-reference) below. @@ -391,7 +391,7 @@ graphify honors `.gitignore` and supports `--exclude` patterns and a project `.g Create a `.graphifyrc` in the scan root for settings that belong to the project rather than to one run. One `key=value` per line; lines beginning with `#` are comments. -**Ambiguous extensions.** Some extensions mean different languages in different projects: `.inc` is PHP on pfSense, Pascal in a Delphi tree, SQL or assembly elsewhere; `.h` is C or C++; `.m` is Objective-C or MATLAB. graphify has to pick one global default, and when it picks wrong the file does not fail — it parses as the wrong language and yields a handful of incidental nodes, so the graph looks populated while the real symbols are missing. Declare what the extension means in your repo: +**Ambiguous extensions.** Some extensions mean different languages in different projects: `.inc` is PHP on pfSense, Pascal in a Delphi tree, SQL or assembly elsewhere; `.h` is C or C++; `.m` is Objective-C or MATLAB. graphify has to pick one global default, and when it picks wrong the file does not fail: it parses as the wrong language and yields a handful of incidental nodes, so the graph looks populated while the real symbols are missing. Declare what the extension means in your repo: ``` # .graphifyrc @@ -431,12 +431,12 @@ Backends, API keys, hook behavior, and tuning are controlled by environment vari ## Privacy -- **Code files** — processed locally via tree-sitter. Nothing leaves your machine. A code-only corpus requires no API key — `graphify extract` runs fully offline. On a mixed repo, add `--code-only` to index just the code and skip the docs/PDFs/images that would otherwise need an LLM. -- **Video / audio** — transcribed locally with faster-whisper. Nothing leaves your machine. -- **Docs, PDFs, images** — sent to your AI assistant for semantic extraction (via the `/graphify` skill, using whatever model your IDE session runs). Headless `graphify extract` requires `GEMINI_API_KEY` / `GOOGLE_API_KEY` (Gemini), `MOONSHOT_API_KEY` (Kimi), `ANTHROPIC_API_KEY` (Claude), `OPENAI_API_KEY` (OpenAI), `DEEPSEEK_API_KEY` (DeepSeek), a running Ollama instance (`OLLAMA_BASE_URL`), AWS credentials via the standard provider chain (Bedrock - no API key needed, uses IAM), or the `claude` CLI binary (Claude Code - no API key needed, uses your Claude subscription). The `--dedup-llm` flag uses the same key. -- **Data residency** — `graphify extract` auto-detects which provider to use based on which API key is set (priority: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). For code with data-residency requirements, use `--backend ollama` (fully local) or pass an explicit `--backend` flag. Kimi (`MOONSHOT_API_KEY`) routes to Moonshot AI servers in China. +- **Code files**: processed locally via tree-sitter. Nothing leaves your machine. A code-only corpus requires no API key: `graphify extract` runs fully offline. On a mixed repo, add `--code-only` to index just the code and skip the docs/PDFs/images that would otherwise need an LLM. +- **Video / audio**: transcribed locally with faster-whisper. Nothing leaves your machine. +- **Docs, PDFs, images**: sent to your AI assistant for semantic extraction (via the `/graphify` skill, using whatever model your IDE session runs). Headless `graphify extract` requires `GEMINI_API_KEY` / `GOOGLE_API_KEY` (Gemini), `MOONSHOT_API_KEY` (Kimi), `ANTHROPIC_API_KEY` (Claude), `OPENAI_API_KEY` (OpenAI), `DEEPSEEK_API_KEY` (DeepSeek), a running Ollama instance (`OLLAMA_BASE_URL`), AWS credentials via the standard provider chain (Bedrock - no API key needed, uses IAM), or the `claude` CLI binary (Claude Code - no API key needed, uses your Claude subscription). The `--dedup-llm` flag uses the same key. +- **Data residency**: `graphify extract` auto-detects which provider to use based on which API key is set (priority: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). For code with data-residency requirements, use `--backend ollama` (fully local) or pass an explicit `--backend` flag. Kimi (`MOONSHOT_API_KEY`) routes to Moonshot AI servers in China. - **No telemetry**, no usage tracking, no analytics. -- **Query logging** — every `graphify query`, `graphify path`, `graphify explain`, and MCP `query_graph` call is logged to `~/.cache/graphify-queries.log` in JSON Lines format (timestamp, question, corpus, nodes returned, duration). Full subgraph responses are **not** stored by default. Set `GRAPHIFY_QUERY_LOG_DISABLE=1` to opt out, or `GRAPHIFY_QUERY_LOG=/dev/null` to silence without disabling the code path. +- **Query logging**: every `graphify query`, `graphify path`, `graphify explain`, and MCP `query_graph` call is logged to `~/.cache/graphify-queries.log` in JSON Lines format (timestamp, question, corpus, nodes returned, duration). Full subgraph responses are **not** stored by default. Set `GRAPHIFY_QUERY_LOG_DISABLE=1` to opt out, or `GRAPHIFY_QUERY_LOG=/dev/null` to silence without disabling the code path. --- @@ -454,11 +454,11 @@ Every command and flag, with examples: **[CLI reference](https://docs.graphify.c ## Learn more -- [docs.graphify.com](https://docs.graphify.com) — full documentation: guides, command reference, and integrations -- [How it works](docs/how-it-works.md) — the extraction pipeline, community detection, confidence scoring, benchmarks -- [ARCHITECTURE.md](ARCHITECTURE.md) — module breakdown, how to add a language -- [Optional integrations](docs/docker-mcp-sqlite.md) — Docker MCP Toolkit + SQLite -- [The Memory Layer](https://safishamsi.gumroad.com/l/qetvlo) — the book on the ideas behind graphify, the architecture end to end +- [docs.graphify.com](https://docs.graphify.com): full documentation: guides, command reference, and integrations +- [How it works](docs/how-it-works.md): the extraction pipeline, community detection, confidence scoring, benchmarks +- [ARCHITECTURE.md](ARCHITECTURE.md): module breakdown, how to add a language +- [Optional integrations](docs/docker-mcp-sqlite.md): Docker MCP Toolkit + SQLite +- [The Memory Layer](https://safishamsi.gumroad.com/l/qetvlo): the book on the ideas behind graphify, the architecture end to end --- @@ -466,12 +466,12 @@ Every command and flag, with examples: **[CLI reference](https://docs.graphify.c [**Graphify Cloud**](https://app.graphify.com/login) is the always-on layer built on top of graphify. Instead of a graph you rebuild on demand per folder, it keeps one live graph across your entire software development lifecycle: -- **80% fewer tokens** — always-on memory means your agents stop re-reading and re-explaining the codebase every session. -- **Monorepo and cross-repo** — one connected graph across every service and repository, not a graph per folder. -- **Formal verification** — check architectural and dependency invariants against the live graph. -- **Code review with a bird's-eye view of your SDLC** — see how a change ripples across the whole system before you merge. -- **SDLC connectors** — pull in Sentry, Jira, and more, so incidents, tickets, and code live in one graph. -- **Always-on** — updates continuously in the background across code, docs, and meetings. +- **80% fewer tokens**: always-on memory means your agents stop re-reading and re-explaining the codebase every session. +- **Monorepo and cross-repo**: one connected graph across every service and repository, not a graph per folder. +- **Formal verification**: check architectural and dependency invariants against the live graph. +- **Code review with a bird's-eye view of your SDLC**: see how a change ripples across the whole system before you merge. +- **SDLC connectors**: pull in Sentry, Jira, and more, so incidents, tickets, and code live in one graph. +- **Always-on**: updates continuously in the background across code, docs, and meetings. **[Start a free 14-day trial at app.graphify.com →](https://app.graphify.com/login)**