graphify system — map your machine into a queryable knowledge graph

A small, read-only add-on for Graphify that adds a graphify system subcommand. Instead of pointing Graphify at a folder of code, it points it at the machine itself — host & specs (CPU/RAM/GPU/disks), installed programs and how they were installed, services and what starts at boot, settings, files/projects, and the local network — and writes it all into Graphify's native graph.json. Then explain / path / query / the interactive graph.html all work on your machine, and an AI agent (or you) can query a cached map instead of re-scanning the live system every time.

All credit goes to Graphify

Graphify (MIT, by @safishamsi) is the engine — extraction, graph build, clustering, search, and the visual viewer. Their system is great; this is just an adaptation that feeds machine facts into it. If this is useful to you, go star Graphify. See CREDITS.md.

Supported today: macOS and Windows. Linux is not included yet (see Platforms).

---

Why — the token savings

Asking an agent "what's installed / what services run / what's my network / where does X live" normally means running and parsing live system commands, which burns a lot of tokens. Querying a pre-built map is a tiny lookup. Measured examples from the original build:

Lookup	Live scan (≈ tokens)	Via the map (≈ tokens)	Reduction
Full system-details lookup	~49,000	~500	~100×
"What's installed + how"	~23,400	~90	~260×

Across typical system questions this lands around ~50–250× fewer tokens (and far faster, since it's a cached read rather than spawning/parsing system_profiler / Get-CimInstance / winget / launchctl / ifconfig / arp). Numbers vary by machine and query — treat them as the order of magnitude, not a promise.

---

What it captures

Node kinds: host, spec (cpu/ram/gpu), disk / volume, app + package_manager (install provenance), service + autostart, setting, file / dir, iface / peer (LAN + Tailscale fleet).

Edges: contains, has_spec, installed_by, runs, defined_by, autostarts_via, configured_by, connects_to.

So you can ask things like "is Docker installed and how?" (app -installed_by-> winget), "what runs at boot?" (autostart), "what's on the LAN?" (peer), or "where does this project live?" (file / dir).

Fidelity: this is a mid-level build

It's deliberately more than an overview but not exhaustive — enough to answer real questions cheaply without indexing every byte. You can move it either direction; we intentionally did not build settings/UI for this, but here's how:

• Dial it DOWN (lighter, faster, more overview-ish): lower --max-files and --max-depth; pass fewer (or no) --deep-roots — with none, you get the stable inventory (host/apps/services/network) and skip the file layer entirely; or delete a collector module you don't need from graphify/sysmap/ (the orchestrator simply skips absent collectors).
• Dial it UP (deeper, more thorough): raise --max-files / --max-depth, add more --deep-roots, and extend the collectors — e.g. have collect_apps record per-app file inventories or dependencies, collect_services capture more scheduled-task/trigger detail, collect_settings widen its (allowlisted) registry/defaults coverage, or collect_network enumerate listening ports/connections. Each collector is a self-contained module following the contract documented in graphify/sysmap/helpers.py, so deepening one is a local change.

---

Security — what it will and won't read

Names and non-secret scalars only. Collectors never read secret values: no Credential Manager / DPAPI blobs, no Wi-Fi keys/PSKs, no environment-variable secret values, no whole registry hives, no Keychain. The settings collector is a curated allowlist. Everything is run through Graphify's sanitizers, and every external command is wrapped so a missing tool degrades to nothing instead of crashing.

The generated map is private to you. graph.json / graph.html describe your real machine (apps, paths, IPs, hostnames, peers) — they are git-ignored here and you should not commit or share them.

Serving (Windows sysmap serve): binds to 127.0.0.1 by default. --lan (to view on your phone) binds to all interfaces and adds a Windows Firewall rule scoped to LocalSubnet (same-network devices only, never the internet); sysmap unshare removes it.

---

Install

You need Graphify installed first (graphify --help should work). These steps add the system feature to your existing Graphify install. Back up the package first — a graphify upgrade may overwrite it, after which you re-apply these files.

Find the installed package dir:

python3 -c "import graphify, os; print(os.path.dirname(graphify.__file__))"

macOS

PKG="$(python3 -c 'import graphify, os; print(os.path.dirname(graphify.__file__))')"
cp -r "$PKG" "${PKG}.backup"                          # back up first

cp macos/graphify/system_extract.py "$PKG"/
cp -r macos/graphify/sysmap "$PKG"/
( cd "$PKG" && patch -p1 < /path/to/macos/patches/__main__.py.patch )   # adds the `system` CLI arm

install -m 0755 macos/bin/sysmap /usr/local/bin/sysmap                  # the query wrapper (edit ROOTS inside)
mkdir -p ~/.claude/skills/system-map && cp macos/skill/SKILL.md ~/.claude/skills/system-map/SKILL.md

GRAPHIFY_OUT=~/.graphify/system graphify system --no-cluster            # build the map
sysmap stats                                                            # confirm

Windows (PowerShell)

$PKG = python -c "import graphify, os; print(os.path.dirname(graphify.__file__))"
Copy-Item -Recurse $PKG "$PKG.backup"                                   # back up first

Copy-Item windows\graphify\system_extract.py $PKG\
Copy-Item -Recurse windows\graphify\sysmap $PKG\
# Apply the system arm to __main__.py (git apply, or patch if you have it):
git apply --directory="$PKG\.." windows\patches\__main__.py.patch
#   (no git/patch? open windows\patches\__main__.py.patch — it adds `"system"` to _silent_cmds,
#    a usage block, and an `elif cmd == "system":` arm just before `elif Path(cmd).exists()`.)

# Wrapper on PATH (a dir already on PATH, e.g. %USERPROFILE%\.local\bin). Edit $CandidateRoots in sysmap.ps1.
Copy-Item windows\bin\sysmap.ps1, windows\bin\sysmap.cmd $env:USERPROFILE\.local\bin\
Copy-Item windows\bin\sysmap_query.py, windows\bin\sysmap_serve.py $env:USERPROFILE\.graphify\system\

# Skill
New-Item -ItemType Directory -Force $env:USERPROFILE\.claude\skills\system-map | Out-Null
Copy-Item windows\skill\SKILL.md $env:USERPROFILE\.claude\skills\system-map\SKILL.md

sysmap refresh    # builds the map at %USERPROFILE%\.graphify\system and opens nothing
sysmap stats

The __main__.py patch is pinned to the Graphify version it was generated against. If it doesn't apply cleanly to your version, the patch is small and human-readable — apply the three edits by hand (they're described at the top of the patch).

---

Usage

sysmap find <text>      search nodes (apps/services/settings/specs/files/network) — start here
sysmap explain <name>   one node + its connections (installed_by, contains, runs, configured_by…)
sysmap path <a> <b>     shortest path between two nodes
sysmap query <text>     looser natural-language search
sysmap stats            node counts by kind + last build time
sysmap refresh          full re-scan
sysmap remap            incremental update (change-detection)
sysmap viz              open the visual graph (file)

Windows also has, for viewing the visual graph in a browser / on your phone:

sysmap serve [port]     serve graph.html at http://127.0.0.1:8765 (this PC only)
sysmap serve --lan      serve to your LAN at http://<this-PC-IP>:8765 (adds a LocalSubnet firewall rule)
sysmap unshare          remove the LAN firewall rule

graph.html loads its viewer library (vis-network) from a CDN; sysmap serve rewrites it on the fly to serve the library locally (fetched once into the map dir) so a phone with no/blocked internet still renders, and injects a mobile viewport. The full map can be large (tens of thousands of nodes) and heavy on phones — a lighter view is just graphify system with fewer/no --deep-roots.

---

Platforms

Platform	Status
macOS	✅ included (macos/)
Windows	✅ included (windows/)
Linux	⬜ not yet

Adding Linux is mostly writing the 7 collectors against Linux tooling, reusing the OS-agnostic spine (system_extract.py + sysmap/helpers.py) unchanged: host/specs from /proc + lscpu + lspci / nvidia-smi; disks from lsblk -J; apps from dpkg/rpm/flatpak/snap/pip/pipx; services from systemctl list-units --type=service; settings from a curated allowlist (gsettings/dotfiles, no secrets); files via os.walk; network from ip -j addr / ip route / arp / tailscale status. Contributions welcome.

---

Repo layout

macos/                      windows/
  graphify/                   graphify/
    system_extract.py           system_extract.py    # orchestrator (OS-agnostic spine)
    sysmap/                      sysmap/
      helpers.py                  helpers.py          # ids, node/edge builders, subprocess wrappers
      collect_*.py (×7)           collect_*.py (×7)   # the per-domain collectors (OS-specific)
  patches/__main__.py.patch   patches/__main__.py.patch   # the `system` CLI arm
  bin/sysmap                  bin/sysmap.ps1, sysmap.cmd, sysmap_query.py, sysmap_serve.py
  skill/SKILL.md              skill/SKILL.md          # optional Claude Code skill
CREDITS.md  LICENSE  README.md  .gitignore

Built on Graphify — all credit there.