gitnexus 1.3.8 → 1.3.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +194 -194
  2. package/dist/cli/ai-context.js +87 -87
  3. package/dist/cli/index.js +15 -25
  4. package/dist/cli/lazy-action.d.ts +6 -0
  5. package/dist/cli/lazy-action.js +18 -0
  6. package/dist/core/augmentation/engine.js +20 -20
  7. package/dist/core/embeddings/embedding-pipeline.js +26 -26
  8. package/dist/core/ingestion/ast-cache.js +3 -2
  9. package/dist/core/ingestion/cluster-enricher.js +16 -16
  10. package/dist/core/ingestion/pipeline.js +8 -0
  11. package/dist/core/ingestion/tree-sitter-queries.js +484 -484
  12. package/dist/core/ingestion/workers/parse-worker.js +4 -2
  13. package/dist/core/kuzu/kuzu-adapter.js +9 -9
  14. package/dist/core/kuzu/schema.js +287 -287
  15. package/dist/core/search/bm25-index.js +5 -5
  16. package/dist/core/search/hybrid-search.js +3 -3
  17. package/dist/core/wiki/graph-queries.js +52 -52
  18. package/dist/core/wiki/html-viewer.js +192 -192
  19. package/dist/core/wiki/prompts.js +82 -82
  20. package/dist/mcp/compatible-stdio-transport.d.ts +25 -0
  21. package/dist/mcp/compatible-stdio-transport.js +200 -0
  22. package/dist/mcp/local/local-backend.js +128 -128
  23. package/dist/mcp/resources.js +42 -42
  24. package/dist/mcp/server.js +18 -18
  25. package/dist/mcp/tools.js +86 -86
  26. package/hooks/claude/gitnexus-hook.cjs +155 -155
  27. package/hooks/claude/pre-tool-use.sh +79 -79
  28. package/hooks/claude/session-start.sh +42 -42
  29. package/package.json +96 -96
  30. package/scripts/patch-tree-sitter-swift.cjs +74 -74
  31. package/skills/gitnexus-cli.md +82 -82
  32. package/skills/gitnexus-debugging.md +89 -89
  33. package/skills/gitnexus-exploring.md +78 -78
  34. package/skills/gitnexus-guide.md +64 -64
  35. package/skills/gitnexus-impact-analysis.md +97 -97
  36. package/skills/gitnexus-pr-review.md +163 -163
  37. package/skills/gitnexus-refactoring.md +121 -121
  38. package/vendor/leiden/index.cjs +355 -355
  39. package/vendor/leiden/utils.cjs +392 -392
@@ -1,82 +1,82 @@
1
- ---
2
- name: gitnexus-cli
3
- 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\""
4
- ---
5
-
6
- # GitNexus CLI Commands
7
-
8
- All commands work via `npx` — no global install required.
9
-
10
- ## Commands
11
-
12
- ### analyze — Build or refresh the index
13
-
14
- ```bash
15
- npx gitnexus analyze
16
- ```
17
-
18
- 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.
19
-
20
- | Flag | Effect |
21
- | -------------- | ---------------------------------------------------------------- |
22
- | `--force` | Force full re-index even if up to date |
23
- | `--embeddings` | Enable embedding generation for semantic search (off by default) |
24
-
25
- **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
26
-
27
- ### status — Check index freshness
28
-
29
- ```bash
30
- npx gitnexus status
31
- ```
32
-
33
- 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.
34
-
35
- ### clean — Delete the index
36
-
37
- ```bash
38
- npx gitnexus clean
39
- ```
40
-
41
- 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.
42
-
43
- | Flag | Effect |
44
- | --------- | ------------------------------------------------- |
45
- | `--force` | Skip confirmation prompt |
46
- | `--all` | Clean all indexed repos, not just the current one |
47
-
48
- ### wiki — Generate documentation from the graph
49
-
50
- ```bash
51
- npx gitnexus wiki
52
- ```
53
-
54
- Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
55
-
56
- | Flag | Effect |
57
- | ------------------- | ----------------------------------------- |
58
- | `--force` | Force full regeneration |
59
- | `--model <model>` | LLM model (default: minimax/minimax-m2.5) |
60
- | `--base-url <url>` | LLM API base URL |
61
- | `--api-key <key>` | LLM API key |
62
- | `--concurrency <n>` | Parallel LLM calls (default: 3) |
63
- | `--gist` | Publish wiki as a public GitHub Gist |
64
-
65
- ### list — Show all indexed repos
66
-
67
- ```bash
68
- npx gitnexus list
69
- ```
70
-
71
- Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
72
-
73
- ## After Indexing
74
-
75
- 1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
76
- 2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
77
-
78
- ## Troubleshooting
79
-
80
- - **"Not inside a git repository"**: Run from a directory inside a git repo
81
- - **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
82
- - **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding
1
+ ---
2
+ name: gitnexus-cli
3
+ 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\""
4
+ ---
5
+
6
+ # GitNexus CLI Commands
7
+
8
+ All commands work via `npx` — no global install required.
9
+
10
+ ## Commands
11
+
12
+ ### analyze — Build or refresh the index
13
+
14
+ ```bash
15
+ npx gitnexus analyze
16
+ ```
17
+
18
+ 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.
19
+
20
+ | Flag | Effect |
21
+ | -------------- | ---------------------------------------------------------------- |
22
+ | `--force` | Force full re-index even if up to date |
23
+ | `--embeddings` | Enable embedding generation for semantic search (off by default) |
24
+
25
+ **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
26
+
27
+ ### status — Check index freshness
28
+
29
+ ```bash
30
+ npx gitnexus status
31
+ ```
32
+
33
+ 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.
34
+
35
+ ### clean — Delete the index
36
+
37
+ ```bash
38
+ npx gitnexus clean
39
+ ```
40
+
41
+ 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.
42
+
43
+ | Flag | Effect |
44
+ | --------- | ------------------------------------------------- |
45
+ | `--force` | Skip confirmation prompt |
46
+ | `--all` | Clean all indexed repos, not just the current one |
47
+
48
+ ### wiki — Generate documentation from the graph
49
+
50
+ ```bash
51
+ npx gitnexus wiki
52
+ ```
53
+
54
+ Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
55
+
56
+ | Flag | Effect |
57
+ | ------------------- | ----------------------------------------- |
58
+ | `--force` | Force full regeneration |
59
+ | `--model <model>` | LLM model (default: minimax/minimax-m2.5) |
60
+ | `--base-url <url>` | LLM API base URL |
61
+ | `--api-key <key>` | LLM API key |
62
+ | `--concurrency <n>` | Parallel LLM calls (default: 3) |
63
+ | `--gist` | Publish wiki as a public GitHub Gist |
64
+
65
+ ### list — Show all indexed repos
66
+
67
+ ```bash
68
+ npx gitnexus list
69
+ ```
70
+
71
+ Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
72
+
73
+ ## After Indexing
74
+
75
+ 1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
76
+ 2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
77
+
78
+ ## Troubleshooting
79
+
80
+ - **"Not inside a git repository"**: Run from a directory inside a git repo
81
+ - **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
82
+ - **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding
@@ -1,89 +1,89 @@
1
- ---
2
- name: gitnexus-debugging
3
- description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
4
- ---
5
-
6
- # Debugging with GitNexus
7
-
8
- ## When to Use
9
-
10
- - "Why is this function failing?"
11
- - "Trace where this error comes from"
12
- - "Who calls this method?"
13
- - "This endpoint returns 500"
14
- - Investigating bugs, errors, or unexpected behavior
15
-
16
- ## Workflow
17
-
18
- ```
19
- 1. gitnexus_query({query: "<error or symptom>"}) → Find related execution flows
20
- 2. gitnexus_context({name: "<suspect>"}) → See callers/callees/processes
21
- 3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
22
- 4. gitnexus_cypher({query: "MATCH path..."}) → Custom traces if needed
23
- ```
24
-
25
- > If "Index is stale" → run `npx gitnexus analyze` in terminal.
26
-
27
- ## Checklist
28
-
29
- ```
30
- - [ ] Understand the symptom (error message, unexpected behavior)
31
- - [ ] gitnexus_query for error text or related code
32
- - [ ] Identify the suspect function from returned processes
33
- - [ ] gitnexus_context to see callers and callees
34
- - [ ] Trace execution flow via process resource if applicable
35
- - [ ] gitnexus_cypher for custom call chain traces if needed
36
- - [ ] Read source files to confirm root cause
37
- ```
38
-
39
- ## Debugging Patterns
40
-
41
- | Symptom | GitNexus Approach |
42
- | -------------------- | ---------------------------------------------------------- |
43
- | Error message | `gitnexus_query` for error text → `context` on throw sites |
44
- | Wrong return value | `context` on the function → trace callees for data flow |
45
- | Intermittent failure | `context` → look for external calls, async deps |
46
- | Performance issue | `context` → find symbols with many callers (hot paths) |
47
- | Recent regression | `detect_changes` to see what your changes affect |
48
-
49
- ## Tools
50
-
51
- **gitnexus_query** — find code related to error:
52
-
53
- ```
54
- gitnexus_query({query: "payment validation error"})
55
- → Processes: CheckoutFlow, ErrorHandling
56
- → Symbols: validatePayment, handlePaymentError, PaymentException
57
- ```
58
-
59
- **gitnexus_context** — full context for a suspect:
60
-
61
- ```
62
- gitnexus_context({name: "validatePayment"})
63
- → Incoming calls: processCheckout, webhookHandler
64
- → Outgoing calls: verifyCard, fetchRates (external API!)
65
- → Processes: CheckoutFlow (step 3/7)
66
- ```
67
-
68
- **gitnexus_cypher** — custom call chain traces:
69
-
70
- ```cypher
71
- MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
72
- RETURN [n IN nodes(path) | n.name] AS chain
73
- ```
74
-
75
- ## Example: "Payment endpoint returns 500 intermittently"
76
-
77
- ```
78
- 1. gitnexus_query({query: "payment error handling"})
79
- → Processes: CheckoutFlow, ErrorHandling
80
- → Symbols: validatePayment, handlePaymentError
81
-
82
- 2. gitnexus_context({name: "validatePayment"})
83
- → Outgoing calls: verifyCard, fetchRates (external API!)
84
-
85
- 3. READ gitnexus://repo/my-app/process/CheckoutFlow
86
- → Step 3: validatePayment → calls fetchRates (external)
87
-
88
- 4. Root cause: fetchRates calls external API without proper timeout
89
- ```
1
+ ---
2
+ name: gitnexus-debugging
3
+ description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
4
+ ---
5
+
6
+ # Debugging with GitNexus
7
+
8
+ ## When to Use
9
+
10
+ - "Why is this function failing?"
11
+ - "Trace where this error comes from"
12
+ - "Who calls this method?"
13
+ - "This endpoint returns 500"
14
+ - Investigating bugs, errors, or unexpected behavior
15
+
16
+ ## Workflow
17
+
18
+ ```
19
+ 1. gitnexus_query({query: "<error or symptom>"}) → Find related execution flows
20
+ 2. gitnexus_context({name: "<suspect>"}) → See callers/callees/processes
21
+ 3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
22
+ 4. gitnexus_cypher({query: "MATCH path..."}) → Custom traces if needed
23
+ ```
24
+
25
+ > If "Index is stale" → run `npx gitnexus analyze` in terminal.
26
+
27
+ ## Checklist
28
+
29
+ ```
30
+ - [ ] Understand the symptom (error message, unexpected behavior)
31
+ - [ ] gitnexus_query for error text or related code
32
+ - [ ] Identify the suspect function from returned processes
33
+ - [ ] gitnexus_context to see callers and callees
34
+ - [ ] Trace execution flow via process resource if applicable
35
+ - [ ] gitnexus_cypher for custom call chain traces if needed
36
+ - [ ] Read source files to confirm root cause
37
+ ```
38
+
39
+ ## Debugging Patterns
40
+
41
+ | Symptom | GitNexus Approach |
42
+ | -------------------- | ---------------------------------------------------------- |
43
+ | Error message | `gitnexus_query` for error text → `context` on throw sites |
44
+ | Wrong return value | `context` on the function → trace callees for data flow |
45
+ | Intermittent failure | `context` → look for external calls, async deps |
46
+ | Performance issue | `context` → find symbols with many callers (hot paths) |
47
+ | Recent regression | `detect_changes` to see what your changes affect |
48
+
49
+ ## Tools
50
+
51
+ **gitnexus_query** — find code related to error:
52
+
53
+ ```
54
+ gitnexus_query({query: "payment validation error"})
55
+ → Processes: CheckoutFlow, ErrorHandling
56
+ → Symbols: validatePayment, handlePaymentError, PaymentException
57
+ ```
58
+
59
+ **gitnexus_context** — full context for a suspect:
60
+
61
+ ```
62
+ gitnexus_context({name: "validatePayment"})
63
+ → Incoming calls: processCheckout, webhookHandler
64
+ → Outgoing calls: verifyCard, fetchRates (external API!)
65
+ → Processes: CheckoutFlow (step 3/7)
66
+ ```
67
+
68
+ **gitnexus_cypher** — custom call chain traces:
69
+
70
+ ```cypher
71
+ MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
72
+ RETURN [n IN nodes(path) | n.name] AS chain
73
+ ```
74
+
75
+ ## Example: "Payment endpoint returns 500 intermittently"
76
+
77
+ ```
78
+ 1. gitnexus_query({query: "payment error handling"})
79
+ → Processes: CheckoutFlow, ErrorHandling
80
+ → Symbols: validatePayment, handlePaymentError
81
+
82
+ 2. gitnexus_context({name: "validatePayment"})
83
+ → Outgoing calls: verifyCard, fetchRates (external API!)
84
+
85
+ 3. READ gitnexus://repo/my-app/process/CheckoutFlow
86
+ → Step 3: validatePayment → calls fetchRates (external)
87
+
88
+ 4. Root cause: fetchRates calls external API without proper timeout
89
+ ```
@@ -1,78 +1,78 @@
1
- ---
2
- name: gitnexus-exploring
3
- description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
4
- ---
5
-
6
- # Exploring Codebases with GitNexus
7
-
8
- ## When to Use
9
-
10
- - "How does authentication work?"
11
- - "What's the project structure?"
12
- - "Show me the main components"
13
- - "Where is the database logic?"
14
- - Understanding code you haven't seen before
15
-
16
- ## Workflow
17
-
18
- ```
19
- 1. READ gitnexus://repos → Discover indexed repos
20
- 2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
21
- 3. gitnexus_query({query: "<what you want to understand>"}) → Find related execution flows
22
- 4. gitnexus_context({name: "<symbol>"}) → Deep dive on specific symbol
23
- 5. READ gitnexus://repo/{name}/process/{name} → Trace full execution flow
24
- ```
25
-
26
- > If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
27
-
28
- ## Checklist
29
-
30
- ```
31
- - [ ] READ gitnexus://repo/{name}/context
32
- - [ ] gitnexus_query for the concept you want to understand
33
- - [ ] Review returned processes (execution flows)
34
- - [ ] gitnexus_context on key symbols for callers/callees
35
- - [ ] READ process resource for full execution traces
36
- - [ ] Read source files for implementation details
37
- ```
38
-
39
- ## Resources
40
-
41
- | Resource | What you get |
42
- | --------------------------------------- | ------------------------------------------------------- |
43
- | `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
44
- | `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
45
- | `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
46
- | `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
47
-
48
- ## Tools
49
-
50
- **gitnexus_query** — find execution flows related to a concept:
51
-
52
- ```
53
- gitnexus_query({query: "payment processing"})
54
- → Processes: CheckoutFlow, RefundFlow, WebhookHandler
55
- → Symbols grouped by flow with file locations
56
- ```
57
-
58
- **gitnexus_context** — 360-degree view of a symbol:
59
-
60
- ```
61
- gitnexus_context({name: "validateUser"})
62
- → Incoming calls: loginHandler, apiMiddleware
63
- → Outgoing calls: checkToken, getUserById
64
- → Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
65
- ```
66
-
67
- ## Example: "How does payment processing work?"
68
-
69
- ```
70
- 1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
71
- 2. gitnexus_query({query: "payment processing"})
72
- → CheckoutFlow: processPayment → validateCard → chargeStripe
73
- → RefundFlow: initiateRefund → calculateRefund → processRefund
74
- 3. gitnexus_context({name: "processPayment"})
75
- → Incoming: checkoutHandler, webhookHandler
76
- → Outgoing: validateCard, chargeStripe, saveTransaction
77
- 4. Read src/payments/processor.ts for implementation details
78
- ```
1
+ ---
2
+ name: gitnexus-exploring
3
+ description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
4
+ ---
5
+
6
+ # Exploring Codebases with GitNexus
7
+
8
+ ## When to Use
9
+
10
+ - "How does authentication work?"
11
+ - "What's the project structure?"
12
+ - "Show me the main components"
13
+ - "Where is the database logic?"
14
+ - Understanding code you haven't seen before
15
+
16
+ ## Workflow
17
+
18
+ ```
19
+ 1. READ gitnexus://repos → Discover indexed repos
20
+ 2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
21
+ 3. gitnexus_query({query: "<what you want to understand>"}) → Find related execution flows
22
+ 4. gitnexus_context({name: "<symbol>"}) → Deep dive on specific symbol
23
+ 5. READ gitnexus://repo/{name}/process/{name} → Trace full execution flow
24
+ ```
25
+
26
+ > If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
27
+
28
+ ## Checklist
29
+
30
+ ```
31
+ - [ ] READ gitnexus://repo/{name}/context
32
+ - [ ] gitnexus_query for the concept you want to understand
33
+ - [ ] Review returned processes (execution flows)
34
+ - [ ] gitnexus_context on key symbols for callers/callees
35
+ - [ ] READ process resource for full execution traces
36
+ - [ ] Read source files for implementation details
37
+ ```
38
+
39
+ ## Resources
40
+
41
+ | Resource | What you get |
42
+ | --------------------------------------- | ------------------------------------------------------- |
43
+ | `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
44
+ | `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
45
+ | `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
46
+ | `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
47
+
48
+ ## Tools
49
+
50
+ **gitnexus_query** — find execution flows related to a concept:
51
+
52
+ ```
53
+ gitnexus_query({query: "payment processing"})
54
+ → Processes: CheckoutFlow, RefundFlow, WebhookHandler
55
+ → Symbols grouped by flow with file locations
56
+ ```
57
+
58
+ **gitnexus_context** — 360-degree view of a symbol:
59
+
60
+ ```
61
+ gitnexus_context({name: "validateUser"})
62
+ → Incoming calls: loginHandler, apiMiddleware
63
+ → Outgoing calls: checkToken, getUserById
64
+ → Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
65
+ ```
66
+
67
+ ## Example: "How does payment processing work?"
68
+
69
+ ```
70
+ 1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
71
+ 2. gitnexus_query({query: "payment processing"})
72
+ → CheckoutFlow: processPayment → validateCard → chargeStripe
73
+ → RefundFlow: initiateRefund → calculateRefund → processRefund
74
+ 3. gitnexus_context({name: "processPayment"})
75
+ → Incoming: checkoutHandler, webhookHandler
76
+ → Outgoing: validateCard, chargeStripe, saveTransaction
77
+ 4. Read src/payments/processor.ts for implementation details
78
+ ```
@@ -1,64 +1,64 @@
1
- ---
2
- name: gitnexus-guide
3
- description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
4
- ---
5
-
6
- # GitNexus Guide
7
-
8
- Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
9
-
10
- ## Always Start Here
11
-
12
- For any task involving code understanding, debugging, impact analysis, or refactoring:
13
-
14
- 1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
15
- 2. **Match your task to a skill below** and **read that skill file**
16
- 3. **Follow the skill's workflow and checklist**
17
-
18
- > If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
19
-
20
- ## Skills
21
-
22
- | Task | Skill to read |
23
- | -------------------------------------------- | ------------------- |
24
- | Understand architecture / "How does X work?" | `gitnexus-exploring` |
25
- | Blast radius / "What breaks if I change X?" | `gitnexus-impact-analysis` |
26
- | Trace bugs / "Why is X failing?" | `gitnexus-debugging` |
27
- | Rename / extract / split / refactor | `gitnexus-refactoring` |
28
- | Tools, resources, schema reference | `gitnexus-guide` (this file) |
29
- | Index, status, clean, wiki CLI commands | `gitnexus-cli` |
30
-
31
- ## Tools Reference
32
-
33
- | Tool | What it gives you |
34
- | ---------------- | ------------------------------------------------------------------------ |
35
- | `query` | Process-grouped code intelligence — execution flows related to a concept |
36
- | `context` | 360-degree symbol view — categorized refs, processes it participates in |
37
- | `impact` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |
38
- | `detect_changes` | Git-diff impact — what do your current changes affect |
39
- | `rename` | Multi-file coordinated rename with confidence-tagged edits |
40
- | `cypher` | Raw graph queries (read `gitnexus://repo/{name}/schema` first) |
41
- | `list_repos` | Discover indexed repos |
42
-
43
- ## Resources Reference
44
-
45
- Lightweight reads (~100-500 tokens) for navigation:
46
-
47
- | Resource | Content |
48
- | ---------------------------------------------- | ----------------------------------------- |
49
- | `gitnexus://repo/{name}/context` | Stats, staleness check |
50
- | `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores |
51
- | `gitnexus://repo/{name}/cluster/{clusterName}` | Area members |
52
- | `gitnexus://repo/{name}/processes` | All execution flows |
53
- | `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace |
54
- | `gitnexus://repo/{name}/schema` | Graph schema for Cypher |
55
-
56
- ## Graph Schema
57
-
58
- **Nodes:** File, Function, Class, Interface, Method, Community, Process
59
- **Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
60
-
61
- ```cypher
62
- MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
63
- RETURN caller.name, caller.filePath
64
- ```
1
+ ---
2
+ name: gitnexus-guide
3
+ description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
4
+ ---
5
+
6
+ # GitNexus Guide
7
+
8
+ Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
9
+
10
+ ## Always Start Here
11
+
12
+ For any task involving code understanding, debugging, impact analysis, or refactoring:
13
+
14
+ 1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
15
+ 2. **Match your task to a skill below** and **read that skill file**
16
+ 3. **Follow the skill's workflow and checklist**
17
+
18
+ > If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
19
+
20
+ ## Skills
21
+
22
+ | Task | Skill to read |
23
+ | -------------------------------------------- | ------------------- |
24
+ | Understand architecture / "How does X work?" | `gitnexus-exploring` |
25
+ | Blast radius / "What breaks if I change X?" | `gitnexus-impact-analysis` |
26
+ | Trace bugs / "Why is X failing?" | `gitnexus-debugging` |
27
+ | Rename / extract / split / refactor | `gitnexus-refactoring` |
28
+ | Tools, resources, schema reference | `gitnexus-guide` (this file) |
29
+ | Index, status, clean, wiki CLI commands | `gitnexus-cli` |
30
+
31
+ ## Tools Reference
32
+
33
+ | Tool | What it gives you |
34
+ | ---------------- | ------------------------------------------------------------------------ |
35
+ | `query` | Process-grouped code intelligence — execution flows related to a concept |
36
+ | `context` | 360-degree symbol view — categorized refs, processes it participates in |
37
+ | `impact` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |
38
+ | `detect_changes` | Git-diff impact — what do your current changes affect |
39
+ | `rename` | Multi-file coordinated rename with confidence-tagged edits |
40
+ | `cypher` | Raw graph queries (read `gitnexus://repo/{name}/schema` first) |
41
+ | `list_repos` | Discover indexed repos |
42
+
43
+ ## Resources Reference
44
+
45
+ Lightweight reads (~100-500 tokens) for navigation:
46
+
47
+ | Resource | Content |
48
+ | ---------------------------------------------- | ----------------------------------------- |
49
+ | `gitnexus://repo/{name}/context` | Stats, staleness check |
50
+ | `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores |
51
+ | `gitnexus://repo/{name}/cluster/{clusterName}` | Area members |
52
+ | `gitnexus://repo/{name}/processes` | All execution flows |
53
+ | `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace |
54
+ | `gitnexus://repo/{name}/schema` | Graph schema for Cypher |
55
+
56
+ ## Graph Schema
57
+
58
+ **Nodes:** File, Function, Class, Interface, Method, Community, Process
59
+ **Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
60
+
61
+ ```cypher
62
+ MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
63
+ RETURN caller.name, caller.filePath
64
+ ```