mage-os-gitnexus

Pre-built GitNexus knowledge graph for Mage-OS (Magento 2 community fork). Ready-to-query MCP server via Docker — no 90-minute indexing required. No gitnexus installation needed on your machine.

⚠️ Commercial use requires a paid GitNexus license. GitNexus is PolyForm Noncommercial 1.0.0 — running it locally does not exempt commercial Magento work (agency, client, billable). See License for details. Free for personal/education/research/open-source use.

What's included

Three pre-built indexes, served together as a GitNexus group for cross-index queries:

Index	Scope
core/mageos	vendor/mage-os/ (Magento 2 core, 388 packages)
core/hyva	vendor/hyva-themes/ (10 default-theme packages) — optional
core/deps	Magento's PHP runtime dependencies — laminas/*, symfony/*, monolog/*, guzzlehttp/*, psr/*, league/flysystem*, colinmollenhour/*, ramsey/*, pelago/*, ezyang/*, elasticsearch/*, opensearch-project/*, duosecurity/*, creatuity/*, aligent/* — optional

• Class/interface/method graph with inheritance, calls, imports
• PHP scope-resolution with cross-file reference tracking
• XML-derived edges for plugins, observers, layout block↔template bindings, REST/frontend routes — see augmenter/. Magento wires most of its dependencies in XML (di.xml, events.xml, layout XML, webapi.xml, routes.xml) which PHP static analysis can't see. The bundled augmenter parses these and injects the missing edges; published index releases already have them baked in.
• Splitting by vendor isolates crashes during rebuild and lets users skip pieces they don't need
• The deps index closes the blind spot where Magento code calls into framework libraries (Symfony\Console, Laminas\Di, Monolog\Logger, etc.) — pair it with the matching Mage-OS version

See Available versions for stats per release, or augmenter/README.md for a worked example contrasting what queries look like with and without the XML augmentation.

What groups give you (and what they don't)

The three indexes are registered together as a GitNexus group named mageos-project. This is not the same thing as merging them into one graph. To avoid surprises:

What works — federated search across all three indexes via MCP. Set repo to @mageos-project in any gitnexus MCP tool (query, context, find_symbol, impact, …) and results are merged from mageos, hyva, and deps with reciprocal-rank-fusion ranking.

What does NOT work — direct PHP class/method call edges across index boundaries. When vendor/mage-os/.../SomeController.php calls Symfony\Console\Application::run():

• That call lives in the mageos lbug as an unresolved reference (target class isn't in the same graph)
• The Symfony\Console\Application definition lives in the deps lbug as a normal class node
• No edge exists between them — gitnexus group sync only bridges service-style contracts (HTTP/gRPC/Thrift/Topic/manifest), not shared-library class references. The shared_libs: true flag in gitnexus's group config is a placeholder; no PHP-aware cross-index symbol resolver is implemented upstream.

Practical impact — queries like "find all callers of Laminas\Di\Injector::resolve" return callers from within deps only, not from mage-os or hyva. Same for impact analysis traversing between mageos and deps. For most code-intelligence questions ("how does Quote::collectTotals work", "what plugins are on Cart") this isn't relevant — you're traversing within one index. But it's worth knowing.

Workarounds if cross-index symbol resolution matters for your work:

• Query each index by name explicitly (repo: mageos then repo: deps) and reconcile in your head
• Build a combined index locally (TARGET=all rebuild), then bypass the split-distribution flow with a single gitnexus index registration over the combined output. Costs ~13h rebuild, no crash isolation, ~800MB single archive — but full cross-call resolution. Not currently shipped as a default release; see Building indexes for your version and adapt the .gitnexusignore to whitelist all three vendor trees in one pass.
• Run gitnexus group sync manually if HTTP-route bridging would help your queries (e.g. you want webapi route ↔ frontend fetch() linking). It's not run at container startup because it adds 30-60s of latency for a feature that's a no-op outside HTTP boundaries. Attach to the container with docker exec -it <container> gitnexus group sync mageos-project --skip-embeddings --allow-stale.

Quick start

git clone https://github.com/ProxiBlue/mage-os-gitnexus.git
cd mage-os-gitnexus

# Default versions (latest tested), all three indexes bundled
docker build -t mage-os-gitnexus:latest .

# Or pick specific index versions
docker build \
  --build-arg MAGEOS_VERSION=2.3.0 \
  --build-arg HYVA_VERSION=1.4.6 \
  -t mage-os-gitnexus:my-tag .

# Mage-OS only (skip the Hyvä + deps downloads → smaller image)
docker build \
  --build-arg HYVA_VERSION=none \
  --build-arg INCLUDE_DEPS=0 \
  -t mage-os-gitnexus:mageos-only .

The image is decoupled from index content — the same image can bundle any combination of available Mage-OS, Hyvä, and runtime-deps index versions. The deps index is automatically paired with the Mage-OS version (release tag deps-<MAGEOS_VERSION>) since composer-pinned dep versions differ between Mage-OS releases. See Available versions for the list.

Add to .mcp.json (Claude Code, Cursor, or any MCP client):

{
  "mcpServers": {
    "gitnexus-mageos": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mage-os-gitnexus:latest"]
    }
  }
}

Running Claude Code inside DDEV / Lando / another container? docker run from inside that container generally won't work (no docker daemon access, or hits a different daemon than where you built the image). Use the HTTP transport instead — see Bonus: connect MCP to the same container for the http://host.docker.internal:4747/api/mcp setup.

File reads — matching your environment

The index stores relative paths (app/code/Foo.php, not /var/www/html/app/code/Foo.php), so it's portable across environments. The MCP server only needs to know where to look when it reads file contents via tools like read_file. Set PROJECT_ROOT to wherever your Mage-OS code lives inside the container:

{
  "mcpServers": {
    "gitnexus-mageos": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "PROJECT_ROOT=/var/www/html",
        "-v", "/path/to/your/mageos:/var/www/html",
        "mage-os-gitnexus:latest"
      ]
    }
  }
}

Common paths:

• DDEV / typical Magento Docker: /var/www/html
• Plain Docker / Lando: /workspace (default — no env var needed)

If you don't mount source code, graph queries still work — only file-content tools fail.

Web UI

GitNexus has a web UI hosted at gitnexus.vercel.app that connects to a local HTTP backend over CORS. The frontend is the upstream's hosted page; your code and graph stay on your machine — only the JavaScript runs in your browser.

Start the backend with the bundled docker-compose.yml:

cd ~/workspace/proxiblue/mage-os-gitnexus

# Point at your Mage-OS project (in your shell or in a .env file next to docker-compose.yml)
export MAGEOS_PROJECT_PATH=/home/you/workspace/your-mageos-project

docker compose up gitnexus-ui

Then open https://gitnexus.vercel.app in your browser. The page auto-detects localhost:4747 and connects.

Or as a one-off docker run:

docker run --rm -p 4747:4747 \
  -e PROJECT_ROOT=/var/www/html \
  -v ~/workspace/your-mageos-project:/var/www/html:ro \
  mage-os-gitnexus:latest \
  serve --host 0.0.0.0

Key flags:

• -p 4747:4747 — host-side port mapping. The hosted UI probes localhost:4747 by default.
• --host 0.0.0.0 — passed to gitnexus, not Docker. It tells the server to listen on all container interfaces; the default localhost only binds the container's loopback, which Docker port-forwarding can't reach.
• :ro — read-only mount is fine; the server only needs to read files for the read_file-style tools.

Troubleshooting

"Bind for 127.0.0.1:4747 failed: port is already allocated" — something else on your host is using 4747. Diagnose with:

docker ps --filter publish=4747
ss -ltnp '( sport = :4747 )'   # or: lsof -i :4747

Common culprits:

• A previous docker compose up gitnexus-ui still running — docker compose down
• A DDEV / Lando override that forwards 4747 to your dev container (look for .ddev/docker-compose.gitnexus.yaml or similar in your Mage-OS project)
• A standalone gitnexus serve you started directly on the host

Either free 4747 or run our container on a different host port:

GITNEXUS_UI_PORT=4748 MAGEOS_PROJECT_PATH=/path/to/mageos docker compose up gitnexus-ui

If you change the port, the hosted UI page at gitnexus.vercel.app won't auto-find it — use the page's connection URL field to point at http://localhost:4748 explicitly.

"GUI says it can't connect / spinner forever" — most likely:

• Container failed to start (port conflict above) — check docker compose ps
• The container is up but you're hitting https:// instead of http://localhost:4747 from the browser console (verify in DevTools Network tab)
• A browser extension or VPN intercepting localhost — try a private window

Privacy / compliance: the UI page (HTML + JS) is loaded from gitnexus.vercel.app, so the page's JavaScript can in principle log usage. The server in the container makes no outbound calls during normal operation (audited — only gitnexus publish ever talks to GitHub, and only when explicitly invoked). If the hosted UI is a concern for client-confidential work, stick to the MCP integration — graph queries through Claude Code never touch a hosted page.

Bonus: connect MCP to the same container

The serve container exposes both the web UI HTTP API and an MCP endpoint over StreamableHTTP at /api/mcp. If the UI service is already running, MCP clients can connect to it directly instead of spawning a fresh docker run per session.

Two patterns, depending on where your MCP client lives:

Option A — Claude Code on the host (docker exec stdio)

If Claude Code / Cursor runs natively on the host with docker access:

{
  "mcpServers": {
    "gitnexus-mageos": {
      "command": "docker",
      "args": ["exec", "-i", "mage-os-gitnexus-gitnexus-ui-1", "gitnexus", "mcp"]
    }
  }
}

Container name follows compose's <project>-<service>-<replica> convention; verify with docker ps --format '{{.Names}}'. Pin it explicitly via container_name: mageos-gitnexus in docker-compose.yml if you want stability across project-directory renames.

Option B — Claude Code inside DDEV / Lando / another container (HTTP)

If Claude Code runs inside your Mage-OS dev container (where it can't easily reach docker on the host), connect to the gitnexus container's StreamableHTTP MCP endpoint instead:

{
  "mcpServers": {
    "gitnexus-mageos": {
      "type": "http",
      "url": "http://host.docker.internal:4747/api/mcp",
      "description": "Pre-built GitNexus knowledge graph for Mage-OS (via host-side container)"
    }
  }
}

Requirements:

• The host-side gitnexus container must be running with port 4747 reachable on all interfaces — that's the default in our docker-compose.yml (0.0.0.0:4747->4747/tcp).
• host.docker.internal resolves to the host from inside containers — Docker Desktop has it built-in; DDEV configures it on Linux out of the box; Lando setups may need manual configuration.

Verify connectivity from inside your dev container before editing .mcp.json:

# Inside DDEV (or whichever container Claude Code runs in)
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' -m 3 http://host.docker.internal:4747/
# Expect: HTTP 200

If that 404s or times out, the gitnexus container isn't running or isn't reachable — bring it up with docker compose up -d gitnexus-ui on the host first.

Why prefer this over docker run from inside DDEV — invoking docker run from a DDEV container would either fail (no docker socket exposed) or run a wholly separate, empty docker daemon if a socket is exposed. The HTTP route avoids the docker-in-docker complexity entirely — the dev container just makes plain HTTP requests to the host.

Trade-offs vs docker run --rm -i:

• ✅ No container spin-up cost per MCP session start (warm process, warm lbug page cache)
• ✅ Works from inside DDEV without docker-in-docker plumbing
• ⚠️ Container must be running before Claude Code starts; if you docker compose down, MCP calls fail until you bring it back up. restart: unless-stopped in the compose handles daemon restarts / reboots.
• ⚠️ Single gitnexus process — if it crashes, all MCP clients lose the connection simultaneously (vs docker run which is isolated per session).

Adding your own code

Mount any number of code folders at /mounts/<name>. Each becomes a separate index, automatically linked with the Mage-OS graph for cross-index queries. No gitnexus needed on your host — the container handles all indexing.

XML augmentation for mounts: If a mount looks like a full Magento project (contains vendor/composer/autoload_psr4.php next to the mounted directory), the XML augmenter runs automatically after the first-time index so the mount's di.xml / events.xml / layout / etc. become queryable as graph edges. Disable with -e AUGMENT=0. Cross-mount references (e.g., a plugin in your custom mount targeting a core Magento class) cannot be linked — both endpoints would need to live in the same lbug. For full cross-augmentation, do a unified REBUILD=1 against your whole project instead.

Examples

Single custom module:

{
  "mcpServers": {
    "gitnexus-mageos": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/app/code/MyVendor:/mounts/myvendor",
        "mage-os-gitnexus:latest"
      ]
    }
  }
}

Multiple mounts — custom modules + third-party packages + theme:

{
  "mcpServers": {
    "gitnexus-mageos": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/app/code/MyVendor:/mounts/myvendor",
        "-v", "/path/to/vendor/paypal/module-braintree:/mounts/braintree",
        "-v", "/path/to/vendor/stripe/module-payments:/mounts/stripe",
        "-v", "/path/to/app/design/frontend/MyTheme:/mounts/mytheme",
        "mage-os-gitnexus:latest"
      ]
    }
  }
}

How it works

On startup, the container:

1. Scans /mounts/ for mounted directories
2. Indexes each one independently (first run only — cached in <mount>/.gitnexus/)
3. Creates a GitNexus group linking all indexes together
4. Starts the MCP server with everything queryable

┌──────────────────────────────────────────────┐
│  Docker container                            │
│                                              │
│  /workspace/.gitnexus/lbug (pre-built)       │
│    └─ Mage-OS core: 189K nodes              │
│                                              │
│  /mounts/myvendor/.gitnexus/lbug (indexed)   │
│    └─ Your custom modules                    │
│                                              │
│  /mounts/braintree/.gitnexus/lbug (indexed)  │
│    └─ PayPal Braintree                       │
│                                              │
│  /mounts/mytheme/.gitnexus/lbug (indexed)    │
│    └─ Your theme                             │
│                                              │
│  Group: mageos-project                       │
│    ├─ core/mageos    → /workspace            │
│    ├─ custom/myvendor → /mounts/myvendor     │
│    ├─ custom/braintree → /mounts/braintree   │
│    └─ custom/mytheme  → /mounts/mytheme      │
│                                              │
│  gitnexus mcp (serves all via MCP)           │
└──────────────────────────────────────────────┘

Persistent indexes

Indexes are written inside each mount at <mount>/.gitnexus/. Since the mount points to your host filesystem, the index persists between container restarts. Re-indexing only happens on the first run.

Add .gitnexus/ to your .gitignore if you don't want to commit the index files.

What you can do

Ask your AI assistant natural language questions:

"Show me all relations for braintree payments" "What depends on ProductRepository?" "How does checkout payment processing work?" "What breaks if I change the Quote model?" "Show me all plugins on the Cart model"

The AI translates these to GitNexus MCP tool calls automatically.

Worked examples

• examples/paypal-checkout-flow.md — mapping every file and function involved in placing a PayPal order against the Mage-OS 2.3.0 index. Compares direct Cypher graph queries vs. symbol-context tracing vs. keyword search, with file/symbol counts and a token-cost comparison against an unstructured Explore-agent approach (~3-4× more expensive without the graph).

• augmenter/README.md — "show me all plugins on the Cart model" contrasted with and without the XML augmentation. Demonstrates how a question that requires multiple MCP calls + a filesystem grep fallback (and still misses results) reduces to a single deterministic Cypher query once Magento's XML wiring is in the graph.

Claude Code skills (recommended)

Two skill packs teach Claude Code (and compatible clients like Cursor) how to use this index effectively. Without them everything still works, but the AI tends to fall back to file-level imports + grep instead of using the proper graph queries — slower, less accurate, more tokens.

Skill 1: GitNexus tools (generic)

# Requires gitnexus installed locally
gitnexus analyze --skills

Generates .claude/skills/gitnexus/ with the latest skill files from the GitNexus project. Teaches the AI how to use query, context, impact, cypher, etc.

Skill 2: Magento XML augmentation (this repo)

Teaches the AI about the XML-derived edges in the mageos / hyva / deps indexes — plugin registrations, observer bindings, layout→template links, REST/frontend routes. Without it, the AI doesn't know to query WRAPS edges with reason='magento:di:plugin' and falls back to generic import-tracing.

# Option A — drop the skill into your project's .claude/skills/
mkdir -p .claude/skills/gitnexus-magento
curl -fSL https://raw.githubusercontent.com/ProxiBlue/mage-os-gitnexus/main/skills/gitnexus-magento/SKILL.md \
  -o .claude/skills/gitnexus-magento/SKILL.md

# Option B — clone or symlink (auto-updates with git pull on this repo)
ln -s /path/to/mage-os-gitnexus/skills/gitnexus-magento .claude/skills/gitnexus-magento

Restart Claude Code after either option so it picks up the new skill. To verify it loaded, ask: "do you have any skills about the gitnexus magento augmenter?" — the AI should mention the magento:di:plugin / magento:events:observer:* edge patterns.

The skill file itself lives at skills/gitnexus-magento/SKILL.md in this repo and is human-readable — worth a skim even if you're not using Claude Code.

CLI queries

# Impact analysis
docker run --rm -i mage-os-gitnexus:latest impact ProductRepository --direction upstream

# Code exploration
docker run --rm -i mage-os-gitnexus:latest query "checkout payment processing"

# Symbol context
docker run --rm -i mage-os-gitnexus:latest context Product

Download indexes directly (no Docker)

If you already have gitnexus installed and want the pre-built databases. Each archive contains both lbug and meta.json — drop them into a .gitnexus/ directory and register with gitnexus.

MAGEOS=2.3.0
HYVA=1.4.6
# deps version is always the Mage-OS version
RELEASES=https://github.com/ProxiBlue/mage-os-gitnexus/releases/download

# Mage-OS core
mkdir -p indexes/mageos/.gitnexus
curl -fSL $RELEASES/mageos-$MAGEOS/gitnexus-index-mageos-$MAGEOS.tar.gz | tar xz -C indexes/mageos/.gitnexus/
gitnexus index indexes/mageos --name mageos

# Hyvä themes (skip if you don't use Hyvä)
mkdir -p indexes/hyva/.gitnexus
curl -fSL $RELEASES/hyva-$HYVA/gitnexus-index-hyva-$HYVA.tar.gz | tar xz -C indexes/hyva/.gitnexus/
gitnexus index indexes/hyva --name hyva

# Magento runtime PHP deps (laminas, symfony, monolog, …) — paired with the Mage-OS version
mkdir -p indexes/deps/.gitnexus
curl -fSL $RELEASES/deps-$MAGEOS/gitnexus-index-deps-$MAGEOS.tar.gz | tar xz -C indexes/deps/.gitnexus/
gitnexus index indexes/deps --name deps

# Group them for unified MCP queries
gitnexus group create mageos-project --force
gitnexus group add mageos-project core/mageos mageos
gitnexus group add mageos-project core/hyva hyva
gitnexus group add mageos-project core/deps deps

Available versions

Each index version is published as its own GitHub release. The release tag follows <target>-<version> and the asset is always gitnexus-index.tar.gz (contains lbug + meta.json).

Mage-OS indexes

Release tag	Mage-OS version	Files	Nodes	Edges
mageos-2.3.0	2.3.0	21,741	178,399	436,573

Hyvä indexes

Release tag	Hyvä default-theme version	Files	Nodes	Edges
hyva-1.4.6	1.4.6	3,451	10,776	21,889

Runtime-deps indexes

Versions are pinned to the Mage-OS release they were built against. A Mage-OS 2.3.0 install has different laminas/* / symfony/* versions than 2.4.0, so deps-X.Y.Z only matches mageos-X.Y.Z. The Dockerfile pairs them automatically — there is no separate version arg.

Release tag	Paired with	Files	Nodes	Edges
deps-2.3.0	mageos-2.3.0	4,562	44,099	135,519

Packages indexed: laminas/*, symfony/*, monolog/*, guzzlehttp/*, psr/*, league/flysystem*, colinmollenhour/*, ramsey/*, pelago/*, ezyang/*, elasticsearch/*, opensearch-project/*, duosecurity/*, creatuity/*, aligent/*, composer/semver, composer/ca-bundle. ICU locale data, polyfill stubs, and test/fixture dirs are excluded.

Pick versions via Docker build args:

docker build \
  --build-arg MAGEOS_VERSION=2.3.0 \
  --build-arg HYVA_VERSION=1.4.6 \
  --build-arg INCLUDE_DEPS=1 \
  -t mage-os-gitnexus:my-tag .

Toggles:

• HYVA_VERSION=none — skip Hyvä (build a Mage-OS-only image)
• INCLUDE_DEPS=0 — skip runtime-deps (smaller image, but loses cross-references into framework libraries)

The Docker image tag is your choice — no longer tied to the Mage-OS version.

Building indexes for your version

Doesn't see your version in the Available versions table? The same Docker image can build an index against any Mage-OS / Hyvä installation. Run the build once locally (~60–90 min for Mage-OS, ~5–10 min for Hyvä), then either keep the index for personal use or contribute it back so others on your version benefit too.

Requirements

• A working Mage-OS project on disk with vendor/mage-os/ (and optionally vendor/hyva-themes/) installed via composer
• The mage-os-gitnexus:latest Docker image (built once from this repo)
• Roughly 8 GB of free RAM for the Node heap during indexing
• Time: ~60–90 min for Mage-OS, ~5–10 min for Hyvä

Run the build

TARGET picks which subtree to index — defaults to mageos, accepts hyva, deps, or all. Each target uses its own .gitnexusignore.<target> (shipped in the image) so vendor scopes never cross over.

# Mage-OS only (default, ~60–90 min)
docker run --rm -it \
  -e REBUILD=1 \
  -v /path/to/your/mageos/project:/project \
  -v mageos-index:/output \
  mage-os-gitnexus:latest

# Hyvä only (~5–10 min)
docker run --rm -it -e REBUILD=1 -e TARGET=hyva \
  -v /path/to/your/mageos/project:/project \
  -v mageos-index:/output \
  mage-os-gitnexus:latest

# Runtime PHP deps (laminas, symfony, monolog, etc.) — must match the Mage-OS version
# that's installed in /project. Roughly 8–10k PHP files, ~10–20 min.
docker run --rm -it -e REBUILD=1 -e TARGET=deps \
  -v /path/to/your/mageos/project:/project \
  -v mageos-index:/output \
  mage-os-gitnexus:latest

# All three, sequentially
docker run --rm -it -e REBUILD=1 -e TARGET=all \
  -v /path/to/your/mageos/project:/project \
  -v mageos-index:/output \
  mage-os-gitnexus:latest

What happens inside the container:

1. Mounts your project at /project
2. Copies .gitnexusignore.<target> over your project's ignore file (per target)
3. Runs gitnexus analyze --force against /project
4. Writes the resulting lbug + meta.json to /output/<target>/

The mageos-index Docker volume persists the output between runs so a crashed/aborted build doesn't lose earlier successes.

Tuning the build

If the build OOMs, runs out of file descriptors, or trips a tree-sitter native crash, these knobs help:

Variable	Default	What it does
TARGET	mageos	Which subtree to index: mageos, hyva, deps, or all
GITNEXUS_WORKERS	auto (all cores)	Parser worker pool size. 0 disables workers entirely (sequential, helps isolate native crashes)
GITNEXUS_HEAP_SIZE	32768	Node.js --max-old-space-size in MB
GITNEXUS_WORKER_TIMEOUT	60	Worker idle timeout (seconds) before retry
GITNEXUS_MAX_FILE_SIZE	512	Skip files larger than this (KB). Lower it to dodge problematic minified blobs
GITNEXUS_SUB_BATCH_BYTES	16777216	Worker sub-batch byte budget (16 MB default)
GITNEXUS_VERBOSE	0	Set to 1 for --verbose output (prints the file being parsed — useful for pinpointing crashes)
AUGMENT	1	Run the XML augmenter after gitnexus analyze to inject Magento di.xml / events / layout / webapi / routes edges into the lbug. Set to 0 to skip. Auto-skipped for TARGET=deps (pure framework libs have no Magento configs) and when the project lacks vendor/composer/autoload_psr4.php.

Example — defensive run when a crash is suspected:

docker run --rm -it \
  -e REBUILD=1 \
  -e TARGET=hyva \
  -e GITNEXUS_WORKERS=0 \
  -e GITNEXUS_VERBOSE=1 \
  -e GITNEXUS_MAX_FILE_SIZE=256 \
  -v /path/to/project:/project \
  -v mageos-index:/output \
  mage-os-gitnexus:latest

Package the result

When the build finishes, the index lives in the Docker volume. Package it for use or distribution:

MAGEOS=2.3.0   # the Mage-OS version you indexed against
HYVA=1.4.6     # the Hyvä default-theme version (composer show hyva-themes/magento2-default-theme)
# deps is always pinned to the Mage-OS version it was built against

# All three files (lbug + meta.json) go at the archive root
docker run --rm -v mageos-index:/in -v $(pwd):/out alpine sh -c "
  cd /in/mageos && tar czf /out/gitnexus-index-mageos-$MAGEOS.tar.gz lbug meta.json
  cd /in/hyva   && tar czf /out/gitnexus-index-hyva-$HYVA.tar.gz     lbug meta.json
  cd /in/deps   && tar czf /out/gitnexus-index-deps-$MAGEOS.tar.gz   lbug meta.json
"

The result is up to three tarballs in your current directory — one per target you built. The deps archive's version always matches the Mage-OS version, since composer-pinned dependency versions differ between Mage-OS releases.

Contributing your index back

If you've built an index for a Mage-OS or Hyvä version that isn't already in Available versions, please contribute it — many developers run the same vendor versions and rebuilding takes hours. Even a single donated index helps the next person to land on this repo.

The smoothest way is to bundle code changes and the artifacts together as a PR:

1. Fork ProxiBlue/mage-os-gitnexus and create a branch.
2. Publish your tarballs on a GitHub release in your fork (since the artifacts are too large for the repo itself):

   gh release create mageos-$MAGEOS gitnexus-index-mageos-$MAGEOS.tar.gz \
     --title "Mage-OS $MAGEOS index" \
     --notes "Pre-built GitNexus index for Mage-OS $MAGEOS. Built by <you> on <date>."
   gh release create hyva-$HYVA gitnexus-index-hyva-$HYVA.tar.gz \
     --title "Hyvä $HYVA index" \
     --notes "Pre-built GitNexus index for Hyvä default-theme $HYVA. Built by <you> on <date>."
   gh release create deps-$MAGEOS gitnexus-index-deps-$MAGEOS.tar.gz \
     --title "Mage-OS $MAGEOS runtime deps index" \
     --notes "Pre-built GitNexus index for the PHP runtime deps shipped with Mage-OS $MAGEOS. Built by <you> on <date>."

   The Dockerfile expects the asset filename to include the version (gitnexus-index-<target>-<version>.tar.gz) — matching the local file's name on upload keeps the URL pattern stable. Skip whichever targets you didn't rebuild.
3. Update the Available versions tables in this README to add your row(s) — include files / nodes / edges from your meta.json's stats object. Link the release tag to the release on your fork for now.
4. Open a pull request describing what you indexed (Mage-OS version, Hyvä version, which targets you built, any non-default .gitnexusignore tweaks, build time, host specs). Mention the upstream gitnexus@<version> your image used. Always pair deps-X.Y.Z with mageos-X.Y.Z — never publish a deps- release built against a different Mage-OS version than the tag suggests.
5. We'll review, then either re-publish the release on this repo and update the README links, or merge as-is if pointing at your fork is the cleanest path.

Don't have a GitHub release / can't host the artifacts? Open an issue titled "Index contribution: Mage-OS X.Y.Z" with the tarballs attached (GitHub allows up to 25 MB per attachment — Hyvä typically fits, Mage-OS + deps may need a transfer.sh, Dropbox, or S3 link). We'll cut the release on your behalf.

By contributing an index you're publishing generated data only — your project's source files are not in the archive. Inspect with tar tzf gitnexus-index-*.tar.gz before sharing to confirm only lbug + meta.json are inside.

Upstream fixes

The image uses gitnexus@1.6.6-rc.55+ which includes fixes for large PHP vendor trees previously shipped as patches:

• PR #1800 — OOM in deferred-calls
• PR #1801 — phtml scope extraction
• PR #1808 — OOM in namespace-siblings

License

Commercial use — paid license required

⚠️ GitNexus is licensed under PolyForm Noncommercial 1.0.0. Running it locally does not exempt you — the restriction is on the purpose of use, not the location.

If you use this image (or GitNexus directly) on paid Magento work — agency client projects, billable freelance, internal commercial development — you need a commercial GitNexus license, regardless of how you run it.

• Commercial pricing: ~$29 USD per user / month (SaaS or self-hosted). Enterprise tier adds multi-repo indexing and cross-repo impact analysis.
• License contact: founders@akonlabs.com or GitNexus Discord
• Confirmed by the GitNexus author in issue #1812.

Free use under PolyForm Noncommercial covers: personal projects, education, research, evaluation, and free/open-source community work.

This repository

The Dockerfile, scripts, .gitnexusignore files, augmenter source, examples, skills, and documentation in this repository are MIT licensed — see LICENSE.

The pre-built index data (.gitnexus/lbug, meta.json) is generated output — not subject to GitNexus's source license.

The Docker image installs GitNexus under the terms above. By using the Docker image you agree to GitNexus's PolyForm Noncommercial license and to obtain a commercial license if your use case is commercial.

Required Notice: Copyright Abhigyan Patwari (https://github.com/abhigyanpatwari/GitNexus)