gitnexus-cli

# GitNexus CLI Commands Commands below use `node .gitnexus/run.cjs <command>` — the project-local runner `gitnexus analyze` drops next to the index. It auto-selects an available runner at call time (global `gitnexus`, else `pnpm dlx`, else `npx`), so no package-manager assumption and no global install is required. > If the local runner is absent, use an already available GitNexus CLI with `analyze --index-only`. Follow project scope rules before refreshing. If no runner is available, use source and reference searches; installing or repairing GitNexus is a separate maintenance task unless already authorized. ## Commands ### analyze — Build or refresh the index ```bash node .gitnexus/run.cjs analyze --index-only ``` Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and preserves maintained CLAUDE.md / AGENTS.md entrypoints with `--index-only`. | Flag | Effect | | -------------- | ---------------------------------------------------------------- | | `--force` | Force full re-index even if up to date | | `--embeddings` | Enable embedding generation for semantic search (off by default) | | `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. | | `--pdg` | Build the program-dependence layers used by `explain` and `pdg_query` (taint, CDG, and REACHING_DEF). | **When to run:** When the task needs graph analysis and the relevant coverage is missing or stale, or when the user explicitly requests index maintenance. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout. ### status — Check index freshness ```bash node .gitnexus/run.cjs status ``` Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed. ### clean — Delete the index ```bash node .gitnexus/run.cjs clean ``` Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project. | Flag | Effect | | --------- | ------------------------------------------------- | | `--force` | Skip confirmation prompt | | `--all` | Clean all indexed repos, not just the current one | ### wiki — Generate documentation from the graph ```bash node .gitnexus/run.cjs wiki ``` Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use). | Flag | Effect | | ------------------- | ----------------------------------------- | | `--force` | Force full regeneration | | `--model <model>` | LLM model (default: minimax/minimax-m2.5) | | `--base-url <url>` | LLM API base URL | | `--api-key <key>` | LLM API key | | `--concurrency <n>` | Parallel LLM calls (default: 3) | | `--gist` | Publish wiki as a public GitHub Gist | ### list — Show all indexed repos ```bash node .gitnexus/run.cjs list ``` Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information. ## After Indexing 1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded 2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task ## Troubleshooting - **"Not inside a git repository"**: Run from a directory inside a git repo - **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server - **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding