graphify

Files (10)

• .graphify_version
• SKILL.md
• add-watch-hooks.md · references/
• cluster-only.md · references/
• exports.md · references/
• extraction-prompt.md · references/
• query.md · references/
• transcribe.md · references/
• troubleshooting.md · references/
• update.md · references/

SKILL.md (first lines)

# /graphify

Turn any folder of files into a navigable knowledge graph with community detection, an honest audit trail, and three outputs: interactive HTML, GraphRAG-ready JSON, and a plain-language GRAPH_REPORT.md.

## Usage

```
/graphify                                             # full pipeline on current directory → Obsidian vault
/graphify <path>                                      # full pipeline on specific path
/graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
/graphify <path> --update                             # incremental - re-extract only new/changed files
/graphify <path> --directed                            # build directed graph (preserves edge direction: source→target)
/graphify <path> --cluster-only                       # rerun clustering on existing graph
/graphify <path> --no-viz                             # skip visualization, just report + JSON
/graphify <path> --html                               # (HTML is generated by default - this flag is a no-op)
/graphify <path> --svg                                # also export graph.svg (embeds in Notion, GitHub)
/graphify <path> --graphml                            # export graph.graphml (Gephi, yEd)
/graphify <path> --neo4j                              # generate graphify-out/cypher.txt for Neo4j
/graphify <path> --neo4j-push bolt://localhost:7687   # push directly to Neo4j
/graphify <path> --wiki                               # build agent-crawlable wiki (index.md + one article per community)
/graphify <path> --obsidian --obsidian-dir ~/vaults/my-project  # write vault to custom path (e.g. existing vault)
/graphify <path> --mcp                                # start MCP stdio server for agent access
/graphify <path> --watch                              # watch folder, auto-rebuild on code changes (no LLM needed)
/graphify add <url>                                   # fetch URL, save to ./raw, update graph
/graphify add <url> --author "Name"                   # tag who wrote it
/graphify add <url> --contributor "Name"              # tag who added it to the corpus
/graphify query "<question>"                          # BFS traversal - broad context
/graphify query "<question>" --dfs                    # DFS - trace a specific path
/graphify query "<question>" --budget 1500            # cap answer at N tokens
/graphify path "AuthModule" "Database"                # shortest path between two concepts
/graphify explain "SwinTransformer"                   # plain-language explanation of a node
```

## What graphify is for

graphify is built around Andrej Karpathy's /raw folder workflow: drop anything into a folder — papers, tweets, screenshots, code, notes — and get a structured knowledge graph that shows you what you didn't know was connected.

Three things it does that your AI assistant alone cannot:
1. **Persistent graph** — relationships are stored in `graphify-out/graph.json` and survive across sessions. Ask questions weeks later without re-reading everything.
2. **Honest audit trail** — every edge is tagged EXTRACTED, INFERRED, or AMBIGUOUS. You know what was found vs invented.
3. **Cross-document surprise** — community detection finds connections between concepts in different files that you would never think to ask about directly.

Use it for:
- A codebase you're new to (understand architecture before touching anything)
- A reading list (papers + tweets + notes → one navigable graph)
- A research corpus (citation graph + concept graph in one)
- Your personal /raw folder (drop everything in, let it grow, query it)

## What You Must Do When Invoked

If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.

If no path was given, use `.` (current directory). Do not ask the user for a path.

## Mode dispatcher — pick the right reference before proceeding

Before running the full pipeline below, check the command for these flags / subcommands. If any match, read the listed `references/<file>.md` FIRST, then either return here for the remaining pipeline steps or stay in that reference until done.

| User invocation | Reference to read | Pipeline impact |
|-----------------|-------------------|-----------------|
| `--update` | `references/update.md` | incremental, then Steps 4–9 here |
| `--cluster-only` | `references/cluster-only.md` | skip Steps 1–3, then Steps 5–9 here |
| `query "..."` / `path A B` / `explain X` | `references/query.md` | query existing graph only, no pipeline |
| `add <url>` | `references/add-watch-hooks.md` | fetch + run `--update` |
| `--watch` | `references/add-watch-hooks.md` | background watcher, no pipeline |
| `hook install/uninstall/status` | `references/add-watch-hooks.md` | git hook setup |
| `claude install/uninstall` | `references/add-watch-hooks.md` | CLAUDE.md integration |
| `--svg` / `--graphml` / `--neo4j` / `--neo4j-push` / `--mcp` | `references/exports.md` | additive after Step 6 |
| Step 2 detects `video` files > 0 | `references/transcribe.md` | runs as Step 2.5 |
| PowerShell scrolling / extraction errors | `references/troubleshooting.md` | post-failure recovery |

**Default** (no special flags): proceed to Step 1 below.

Follow these steps in order. Do not skip steps.

### Step 1 — Ensure graphify is installed

```powershell
# Detect Python and install graphify if needed
@'
import graphify
'@ | Out-File -FilePath .graphify_step_1_ensure_graphify_is_installed_1.py -Encoding utf8
python .graphify_step_1_ensure_graphify_is_installed_1.py 2>$null
Remove-Item -ErrorAction SilentlyContinue .graphify_step_1_ensure_graphify_is_installed_1.py
if ($LASTEXITCODE -ne 0) {
    if (Get-Command uv -ErrorAction SilentlyContinue) {
        uv tool install --upgrade graphifyy -q 2>&1 | Select-Object -Last 3
    } else {
        pip install graphifyy -q 2>&1 | Select-Object -Last 3
    }
}
# Write interpreter path for all subsequent steps
@'
import sys; open('.graphify_python', 'w', encoding='utf-8').write(sys.executable)
'@ | Out-File -FilePath .graphify_step_1_ensure_graphify_is_installed_2.py -Encoding utf8
python .graphify_step_1_ensure_graphify_is_installed_2.py
Remove-Item -ErrorAction SilentlyContinue .graphify_step_1_ensure_graphify_is_installed_2.py
```

If the import succeeds, print nothing and move straight to Step 2.

### Step 2 — Detect files

```powershell
@'
import json
from graphify.detect import detect
from pathlib import Path
result = detect(Path('INPUT_PATH'))
print(json.dumps(result, ensure_ascii=False))
'@ | Out-File -FilePath .graphify_step_2_detect_files_3.py -Encoding utf8
python .graphify_step_2_detect_files_3.py > .graphify_detect.json
Remove-Item -ErrorAction SilentlyContinue .graphify_step_2_detect_files_3.py
```

Replace `INPUT_PATH` with the actual path the user provided. Do NOT cat or print the JSON — read it silently and present a clean summary instead:

```
Corpus: X files · ~Y words

From bigbulgogiburger/claude_jira_harness, MIT.

More from bigbulgogiburger/claude_jira_harness