{"id":51079060,"url":"https://github.com/maxgfr/ultraindex","last_synced_at":"2026-06-23T16:33:08.097Z","repository":{"id":363520608,"uuid":"1263683558","full_name":"maxgfr/ultraindex","owner":"maxgfr","description":"Deterministically index a whole repo (code + docs) into a navigable encyclopedia — map + per-module entries + typed link-graph — so an AI can work in huge codebases without filling its context window. A skills.sh skill (generator + light navigator).","archived":false,"fork":false,"pushed_at":"2026-06-09T08:07:08.000Z","size":252,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T09:28:28.978Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxgfr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T07:10:52.000Z","updated_at":"2026-06-09T08:07:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maxgfr/ultraindex","commit_stats":null,"previous_names":["maxgfr/ultraindex"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/maxgfr/ultraindex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultraindex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultraindex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultraindex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultraindex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxgfr","download_url":"https://codeload.github.com/maxgfr/ultraindex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultraindex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34698696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-23T16:33:08.017Z","updated_at":"2026-06-23T16:33:08.089Z","avatar_url":"https://github.com/maxgfr.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ultraindex\n\n\u003e Deterministically index a whole repo (code **+** docs) into a navigable\n\u003e encyclopedia — a small map, per-module entries, and a typed link-graph — so an\n\u003e AI can work in huge codebases **without filling its context window**.\n\nOn a large project the model's context fills before it can find what matters.\n`ultraindex` scans the entire repo **with code** (a zero-dependency Node bundle —\nno `npm install`, no API keys, no LLM read of the repo) and writes a *layered*\nartifact you load piece by piece:\n\n```\n.ultraindex/\n  INDEX.md              # the map — always-loadable: summary, hubs, module table\n  encyclopedia/\n    \u003cmodule\u003e.md         # per-module entry: business view + code view + links + sources\n  graph.json            # the full typed link-graph (file + module level)\n  graph.mmd             # a Mermaid module diagram\n  manifest.json         # per-file hashes (staleness) + merge bookkeeping\n```\n\n## Install\n\nIt ships as **one [skills.sh](https://skills.sh) agent skill** with a committed\nzero-dependency bundle:\n\n```bash\nnpx skills add maxgfr/ultraindex             # this project\nnpx skills add maxgfr/ultraindex --global    # user-level, every project\n```\n\nThe skill installs self-contained (its `SKILL.md` + workflow references + the\ncommitted bundle), so it runs with `node` alone — no `npm install`, no API keys.\nWorks with Claude Code and the other agents the `skills` CLI supports.\n\nThe skill **auto-routes** by situation: no index → it builds one; stale index →\nit rebuilds (your prose survives); a task or question → it navigates, opening\nonly the files the index points at and answering with **grounded,\ncitation-checked** analysis (`dossier`/`ask` hand the agent the real source;\n`check` rejects any citation that doesn't resolve).\n\n## CLI\n\n```\nultraindex build   --repo \u003cdir\u003e [--out \u003cdir\u003e] [--include \u003cglob\u003e] [--exclude \u003cglob\u003e] [--no-mermaid]\nultraindex find    \"\u003cquery\u003e\" [--out \u003cdir\u003e] [--k \u003cn\u003e]\nultraindex embed   [--out \u003cdir\u003e] [--force]\nultraindex neighbors \u003cfile|module-slug\u003e [--out \u003cdir\u003e] [--depth \u003cn\u003e]\nultraindex map     [--out \u003cdir\u003e] [--module \u003cslug\u003e]\nultraindex status  [--out \u003cdir\u003e]\nultraindex dossier \u003cmodule-slug\u003e [--out \u003cdir\u003e] [--repo \u003cdir\u003e]\nultraindex ask     \"\u003cquestion\u003e\" [--out \u003cdir\u003e] [--repo \u003cdir\u003e] [--k \u003cn\u003e]\nultraindex check   [--out \u003cdir\u003e] [--repo \u003cdir\u003e] [--answer \u003cfile\u003e] [--semantic]\nultraindex verify  --answer \u003cfile\u003e [--repo \u003cdir\u003e] [--apply \u003cverdicts.json\u003e] [--max-verify \u003cn\u003e]\n```\n\n- **build** — scan + (re)write the index. Idempotent: regenerates the code view\n  and graph, **preserves** your enriched prose (matched by region key even across\n  module renames; truly-removed modules' prose is kept under `encyclopedia/_orphaned/`).\n- **find** — rank modules for a task and print the **exact files to open**.\n  Lexical by default (identifier splitting, light stemming, code-domain\n  synonyms); hybrid lexical + semantic when `vectors.json` exists (below).\n- **embed** — build/refresh `vectors.json` for semantic `find` (optional, needs\n  a provider — see below). Incremental: unchanged modules keep their vectors.\n- **neighbors** — walk the graph from a file or module.\n- **map** — print `INDEX.md` (or one module's entry) cheaply.\n- **status** — the enrichment work-queue: which modules to enrich next\n  (unenriched first, the tail last, most-connected first).\n- **dossier** — print a grounding packet for a module (its real key source + graph\n  neighbours) so you can write a cited analysis into its entry.\n- **ask** — assemble grounded evidence (real source of the relevant modules) for a\n  question, so you can answer it with citations.\n- **check** — report staleness + integrity + **grounding** (every `[file:line]`\n  citation in your prose must resolve). With `--answer \u003cfile\u003e`, validate that\n  answer's citations instead; add `--semantic` to also fold the verify gate.\n  Non-zero exit ⇒ stale, broken, or ungrounded.\n- **verify** — the high-assurance gate *above* `check --answer`: emit a\n  claim↔citation worklist, adjudicate each (supported / partial / refuted /\n  unsupported), then `--apply` reduces the verdicts to a pass/fail — so a cited\n  excerpt must actually *support* its claim, not merely resolve.\n\nDefault output is `\u003crepo\u003e/.ultraindex` (gitignored). Use `--out docs/ultraindex`\nto commit a PR-reviewable index — deterministic, byte-stable rebuilds keep diffs small.\n\n## How it works\n\nA **deterministic engine** (no model, no network) does the mechanical work:\n\n- **Scan** — gitignore-aware walk; per-file extraction of markdown (title /\n  headings / links) and code (exported symbols + signatures incl. `export default`\n  and barrel re-exports, top doc-comment, local imports).\n- **Resolve** — markdown relative links, and local imports for **JS/TS** (incl.\n  `tsconfig` path aliases — even Nx-style root `tsconfig.base.json` — and\n  **workspace packages** with their `exports` maps → in-repo source), **Python**,\n  **Go** (multi-module `go.mod` incl. `replace` directives), **Rust**\n  (`mod`/`use`, cross-crate), and **Java** (package → source-root mapping).\n  Unresolved local targets become **dangling** edges (surfaced, never silently\n  dropped); third-party/stdlib and asset imports are external (no edge).\n- **Graph** — typed edges (`doc-link`, `import`, conservative `mention`),\n  file-level and lifted to module level; degree centrality picks the hubs.\n- **Render** — a budgeted `INDEX.md`, per-module entries split into tool-owned\n  `ui:gen` regions and author-owned `ui:human` regions, plus `graph.json` /\n  `graph.mmd` / `manifest.json`.\n\nThen a **grounded AI layer** (the skills, via the agent) adds the *understanding*:\n`dossier`/`ask` hand the agent the real source, it writes business analysis /\nanswers that cite `[file:line]`, and `check` mechanically **rejects any citation\nthat doesn't resolve** — the anti-hallucination guard (ultradoc's model, applied\nto a local index). Citations inside code fences / inline code / markdown links\ndon't count, so a decorative cite can't satisfy the gate. For high-assurance\nanswers an optional **verify** gate goes further — `check --answer --semantic`\nfolds adjudicated verdicts and fails a claim whose cited excerpt refutes it (or,\nonce fully adjudicated, supports it nowhere), not merely that it resolves.\n\nripgrep is used when present (faster); without it a built-in scanner is used.\nWithout `git`, the manifest just omits the commit. Two builds of an unchanged repo\nare byte-identical (apart from `manifest.json`'s `builtAt` provenance timestamp).\n\n`find` is purely lexical but smarter than substring matching: queries split\ncamelCase/snake_case identifiers (`getUserProfile` finds `src/user/profile.ts`),\na conservative stemmer bridges plural/-ing variants, and a small code-domain\nsynonym table bridges `auth`↔`authentication`↔`login` — all deterministic,\noffline, dependency-free.\n\n## Semantic search (optional)\n\nLexical search can't bridge a real vocabulary gap (\"invoicing\" vs a module that\nonly ever says \"billing\"). The optional semantic layer embeds each module and\nmakes `find` **hybrid**: lexical and cosine rankings fused with Reciprocal Rank\nFusion. It is strictly additive — without it, nothing changes and the engine\nnever touches the network.\n\n```bash\ndocker compose up -d                                    # local Ollama, no API key, multi-arch\nexport ULTRAINDEX_EMBED_BASE_URL=http://localhost:11434/v1\nexport ULTRAINDEX_EMBED_MODEL=nomic-embed-text\nultraindex embed                                        # writes vectors.json (incremental)\nultraindex find \"invoicing\"                             # now hybrid — results carry semanticRank\n```\n\nAny OpenAI-compatible `POST /v1/embeddings` endpoint is a drop-in provider:\nhuggingface text-embeddings-inference on amd64/GPU hosts\n(`http://localhost:8080/v1`, `BAAI/bge-small-en-v1.5`), or a hosted API\n(`https://api.openai.com/v1`, `text-embedding-3-small`, plus\n`ULTRAINDEX_EMBED_API_KEY`). Instead of env vars you can write\n`\u003cout\u003e/semantic.json` (`{\"baseUrl\": …, \"model\": …}`) — but keep API keys in the\nenv, never in a committed `semantic.json` (mind `docs/ultraindex` indexes).\n\nDegradation is graceful: provider down ⇒ lexical-only results + a stderr\nwarning; no `vectors.json` ⇒ pure lexical, silent, zero network (delete the\nfile to switch the layer off). `check` warns when vectors drift stale.\n**Reproducibility caveat:** two artifacts are excluded from the byte-identical\nrebuild guarantee — `manifest.json` (its `builtAt` timestamp) and `vectors.json`\n(its floats depend on the provider/model).\n\n## Develop\n\n```\npnpm install\npnpm build        # tsup → scripts/ultraindex.mjs, mirrored into the skill dir\npnpm test         # vitest\npnpm typecheck\npnpm check:build  # asserts the committed bundles are reproducible\n```\n\nReleases are Conventional-Commit-driven via semantic-release (GitHub releases).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgfr%2Fultraindex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxgfr%2Fultraindex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgfr%2Fultraindex/lists"}