home / skills / adibfirman / dotfiles / gitnexus-cli

gitnexus-cli skill

safe

/claude/.claude/skills/gitnexus-cli

This skill helps you manage GitNexus CLI tasks like analyze, status, wiki, and list to keep repositories indexed and documented.

npx playbooks add skill adibfirman/dotfiles --skill gitnexus-cli

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.2 KB

---
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

All commands work via `npx` — no global install required.

## Commands

### analyze — Build or refresh the index

```bash
npx gitnexus 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.

| Flag           | Effect                                                           |
| -------------- | ---------------------------------------------------------------- |
| `--force`      | Force full re-index even if up to date                           |
| `--embeddings` | Enable embedding generation for semantic search (off by default) |

**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
npx gitnexus 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
npx gitnexus 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
npx gitnexus 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
npx gitnexus 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

Overview

This skill exposes the gitnexus-cli commands for indexing and managing a GitNexus knowledge graph from a repository. It provides simple npx-based commands to analyze a repo, check index status, clean the index, generate a wiki, and list indexed repos. Use it to build repository context files and drive other GitNexus workflows.

How this skill works

All commands run with npx so no global install is required. analyze parses source files and writes a .gitnexus/ index plus CLAUDE.md and AGENTS.md context files; status reports index freshness and counts; clean removes the index; wiki uses an LLM to generate repository documentation; list shows registered repos. Flags allow forcing operations, toggling embeddings, selecting LLM models, and controlling concurrency or scope.

When to use it

First time setting up GitNexus for a project to create the initial index.
After large code changes or merges to refresh the knowledge graph.
When gitnexus://repo/{name}/context reports the index is stale.
Before generating project documentation or a wiki from the codebase.
To remove or reset GitNexus state when the index is corrupt or obsolete.

Best practices

Run npx gitnexus analyze from the repository root so files are discovered correctly.
Use --force for a full re-index when incremental updates appear stale.
Omit --embeddings if you want faster indexing; enable embeddings only when semantic search is needed.
Store API keys for wiki generation in ~/.gitnexus/config.json and set --model or --base-url for custom LLMs.
Check npx gitnexus status before regenerating docs to avoid unnecessary work.

Example use cases

Index this repo: run npx gitnexus analyze to build the graph and context files.
Reanalyze the codebase after a major refactor with npx gitnexus analyze --force.
Generate a project wiki with npx gitnexus wiki --model minimax/m2.5 and an API key.
Clean a broken index locally with npx gitnexus clean or wipe all indexes with npx gitnexus clean --all.
List every repository registered for GitNexus with npx gitnexus list for inventory or automation.

FAQ

Do I need to install anything globally?

No. All commands run via npx so no global installation is required.

Why is the index still stale after re-analyzing?

Restart the Claude Code / MCP server to pick up the updated .gitnexus index; re-run analyze with --force if issues persist.