---
name: gitnexus-cli
description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
---

# GitNexus CLI Commands

Use one command alias in the session so every CLI/MCP call stays on one version line. After `setup`, use `~/.gitnexus/config.json` as the CLI package spec source (`cliPackageSpec` first, then `cliVersion`). MCP wiring and skill install locations are scope-dependent (`project` vs `global`).

### setup — choose scope explicitly

```bash
gitnexus setup --scope project --agent codex --cli-spec @veewo/gitnexus@<version>
```

Rules:

- If user asks "setup this repository" / "本仓库 setup", use `--scope project`.
- `--scope project` updates repo-local files:
  - Codex MCP config: `.codex/config.toml`
  - Skills: `.agents/skills/gitnexus/`
- `--scope global` updates user-global files:
  - Codex MCP config: `~/.codex/config.toml`
  - Skills: `~/.agents/skills/gitnexus/`
- `--scope global` does not overwrite repo-local `.agents/skills` or `.codex/config.toml`.
- Never rely on setup defaults for scope; pass `--scope` explicitly to avoid global/project mismatch.

```bash
if command -v gitnexus >/dev/null 2>&1; then
  GN="gitnexus"
else
  GITNEXUS_CLI_SPEC="$(
    node -e 'const fs=require("fs");const os=require("os");const path=require("path");
    try {
      const raw=fs.readFileSync(path.join(os.homedir(),".gitnexus","config.json"),"utf8");
      const parsed=JSON.parse(raw);
      const spec=typeof parsed.cliPackageSpec==="string" && parsed.cliPackageSpec.trim()
        ? parsed.cliPackageSpec.trim()
        : typeof parsed.cliVersion==="string" && parsed.cliVersion.trim()
          ? `@veewo/gitnexus@${parsed.cliVersion.trim()}`
          : "";
      if (spec) process.stdout.write(spec);
    } catch {}'
  )"
  if [ -z "$GITNEXUS_CLI_SPEC" ]; then
    echo "Missing GitNexus CLI package spec in ~/.gitnexus/config.json. Run gitnexus setup --cli-spec <packageSpec> first." >&2
    exit 1
  fi
  GN="npx -y ${GITNEXUS_CLI_SPEC}"
fi
```

## Commands

### analyze — Build or refresh the index

```bash
$GN analyze
```

Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.

Analyze options are resolved with two-layer priority: **CLI arguments** > **stored options** in `meta.json.analyzeOptions`. On first run, pass CLI flags; they are persisted automatically for subsequent runs.

| Flag | Effect |
|------|--------|
| `--force` | Force full re-index even if up to date |
| `--no-reuse-options` | Do not reuse stored analyze options from previous index |
| `--embeddings` | Enable embedding generation (off by default) |
| `--extensions <list>` | Comma-separated file extensions (e.g. `.cs,.ts`) |
| `--scope <rules>` | Comma-separated scope path-prefix rules (e.g. `Assets/,Packages/com.veewo.*`) |
| `--repo-alias <name>` | Override indexed repository name with a stable alias |
| `--csharp-define-csproj <path>` | Load C# `DefineConstants` from `.csproj` for `#if` normalization |
| `--skills` | Generate repo-specific skill files from detected communities |
| `-v, --verbose` | Enable verbose ingestion warnings |

**Option persistence:** `--extensions`, `--scope`, `--repo-alias`, `--embeddings`, and `--csharp-define-csproj` are automatically saved to `meta.json.analyzeOptions` after a successful run. On subsequent runs, these stored values are reused unless you pass new CLI flags or use `--no-reuse-options`.

#### Scope rules

Scope rules control which files are included in the index. When no scope rules are stored, **all files** in the repo are indexed. Use `--scope` on first run to set scope rules; they are persisted automatically.

**Scope rule semantics:**
- Each rule is a **path prefix** — `Assets/` matches all files under `Assets/`
- Trailing `*` is a **wildcard prefix** — `Packages/com.veewo.*` matches `Packages/com.veewo.stat/...`
- No glob support: `Assets/**/*.cs` will not work
- Empty scope = full repo scan (all files)

```bash
# Scope to specific directories
$GN analyze --force --scope "Assets/,Packages/"

# Wildcard scope
$GN analyze --force --scope "Assets/NEON/Code,Packages/com.veewo.*"

# No --scope = full repo (or reuse stored scope rules)
$GN analyze --force
```

#### Unity project recommended parameters

Unity projects benefit from a specific combination of parameters to ensure correct C# parsing and optimal scope:

```bash
# Unity project — first-time index (recommended)
$GN analyze --force \
  --extensions ".cs,.meta" \
  --scope "Assets/,Packages/" \
  --repo-alias <repo-alias> \
  --csharp-define-csproj <path-to-Assembly-CSharp.csproj>

# Subsequent rebuilds (all options are reused automatically)
$GN analyze --force
```

| Parameter | Recommended value | Why |
|-----------|------------------|-----|
| `--extensions` | `.cs,.meta` | C# scripts + Unity `.meta` asset files for resource binding |
| `--scope` | `Assets/,Packages/` | Limit to Unity project directories; skip `Library/`, `Temp/`, `obj/` |
| `--csharp-define-csproj` | `path/to/Assembly-CSharp.csproj` | Normalize `#if` / `#elif` conditional compilation using project's `DefineConstants` |
| `--repo-alias` | e.g. `neonspark-core` | Stable alias for MCP repo lookup regardless of directory name |

**C# preprocessing detail:** Unity projects commonly use conditional compilation (`#if UNITY_EDITOR`, `#if NEON_DEBUG`, etc.). Without `--csharp-define-csproj`, tree-sitter parses each `#if` branch as-is, often producing incorrect AST for the active branch. The csproj path is persisted and reused automatically after first specification.

**Scope for large Unity repos:** For repos where only specific packages matter, narrow scope instead of indexing all of `Assets/`:

```bash
$GN analyze --force \
  --scope "Assets/NEON/Code,Packages/com.veewo.*" \
  --extensions ".cs,.meta" \
  --repo-alias neonspark-core
```

#### Other project examples

```bash
# Generic TypeScript project
$GN analyze --force --extensions ".ts,.tsx" --repo-alias my-project

# Subsequent rebuilds (stored options are reused automatically)
$GN analyze --force
```

#### Rebuild recovery — when analyze hangs or crashes

If `analyze --force` hangs (no progress after 5+ minutes) or crashes leaving a corrupted index:

```bash
# 1. Clean the corrupted index
$GN clean --force

# 2. Rebuild (re-specify CLI options since meta.json was deleted)
$GN analyze --force --extensions ".cs,.meta" --repo-alias neonspark-core
```

**When to clean before rebuild:**
- Previous run left `.gitnexus/csv/` with no `relations.csv` (crash mid-streaming)
- `.gitnexus/lbug.wal` exists but `lbug` is tiny (LadybugDB in unrecovered state)
- Any `analyze` run hangs indefinitely in the "Loading into LadybugDB..." phase
- After `gitnexus clean`, always run `analyze --force` to rebuild

**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.

### status — Check index freshness

```bash
$GN 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
$GN clean --force
```

Removes the entire `.gitnexus/` directory (including `meta.json` and all index data). After cleaning, you must re-specify analyze options on the next `analyze` run since stored options are deleted.

| Flag      | Effect                                            |
| --------- | ------------------------------------------------- |
| `--force` | Skip confirmation prompt                          |
| `--all`   | Clean all indexed repos, not just the current one |

### wiki — Generate documentation from the graph

```bash
$GN 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
$GN list
```

Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.

### query/context — Unity hydration mode

For Unity resource retrieval:

```bash
$GN context DoorObj --repo neonnew-core --file Assets/NEON/Code/Game/Doors/DoorObj.cs --unity-resources on --unity-hydration compact
```

```bash
$GN query "DoorObj binding" --repo neonnew-core --unity-resources on --unity-hydration compact
```

Rules:

- `--unity-hydration compact` is the default (fast path).
- If response `hydrationMeta.needsParityRetry=true`, rerun with `--unity-hydration parity`.
- `--unity-hydration parity` is completeness-first mode for advanced verification.

### Unity runtime process contract trigger

When CLI analysis targets Unity runtime process semantics (runtime chain closure/confidence), load:

- `_shared/unity-runtime-process-contract.md`

Runtime-process verification examples:

```bash
$GN query "Reload NEON.Game.Graph.Nodes.Reloads" --repo neonspark --unity-resources on --unity-hydration parity --runtime-chain-verify on-demand
```

```bash
$GN context ReloadNode --repo neonspark --unity-resources on --unity-hydration compact --runtime-chain-verify on-demand
```

### unity-ui-trace — Unity UI evidence tracing workflow

For full workflow details, load: `_shared/unity-ui-trace-contract.md`

```bash
$GN unity-ui-trace "Assets/NEON/VeewoUI/Uxml/BarScreen/Patch/PatchItemPreview.uxml" --goal asset_refs --repo neonspark
$GN unity-ui-trace "Assets/NEON/VeewoUI/Uxml/BarScreen/CoreScreen.uxml" --goal template_refs --repo neonspark
$GN unity-ui-trace "Assets/NEON/VeewoUI/Uxml/BarScreen/Patch/PatchItemPreview.uxml" --goal selector_bindings --selector-mode balanced --repo neonspark
```

## 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
- **`analyze --force` hangs or crashes**: Run `$GN clean --force` to remove the corrupted index, then `$GN analyze --force` (with your CLI options) to rebuild. Common corruption signatures: `.gitnexus/csv/` exists but `relations.csv` is missing; `.gitnexus/lbug.wal` exists while `lbug` is only a few KB.

## Runtime-Chain Closure Guard

- Treat runtime-chain outputs as two layers:
  - `verifier-core`: binary verifier result (`verified_full` | `failed`)
  - `policy-adjusted`: user-visible result after hydration policy is applied
- If `hydration_policy=strict` and `hydrationMeta.fallbackToCompact=true`, the result is downgraded policy-adjusted output and is not closure.
- In that downgraded state, rerun with parity before final conclusions.