Skip to content

Commit db92401

Browse files
Patel230Patel230
committed
Graphify integration: AGENTS.md + CLAUDE.md
1 parent 0c643dd commit db92401

8 files changed

Lines changed: 710 additions & 0 deletions

File tree

‎.claude/skills/gitnexus/gitnexus-cli/SKILL.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
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+
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.
9+
10+
> **Not analyzed yet, or `node .gitnexus/run.cjs` reports `Cannot find module`** (the gitignored runner is absent — e.g. a fresh clone or `git clean`)? (Re)generate it with `npx gitnexus analyze` from the project root. On **npm 11.x**, if `npx` crashes during install (`node.target is null`), install once with `npm i -g gitnexus` (then `gitnexus analyze`) or use `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939).
11+
12+
## Commands
13+
14+
### analyze — Build or refresh the index
15+
16+
```bash
17+
node .gitnexus/run.cjs analyze
18+
```
19+
20+
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.
21+
22+
| Flag | Effect |
23+
| -------------- | ---------------------------------------------------------------- |
24+
| `--force` | Force full re-index even if up to date |
25+
| `--embeddings` | Enable embedding generation for semantic search (off by default) |
26+
| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
27+
| `--pdg` | Build the program-dependence layers used by `explain` and `pdg_query` (taint, CDG, and REACHING_DEF). |
28+
29+
**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. 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.
30+
31+
### status — Check index freshness
32+
33+
```bash
34+
node .gitnexus/run.cjs status
35+
```
36+
37+
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.
38+
39+
### clean — Delete the index
40+
41+
```bash
42+
node .gitnexus/run.cjs clean
43+
```
44+
45+
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.
46+
47+
| Flag | Effect |
48+
| --------- | ------------------------------------------------- |
49+
| `--force` | Skip confirmation prompt |
50+
| `--all` | Clean all indexed repos, not just the current one |
51+
52+
### wiki — Generate documentation from the graph
53+
54+
```bash
55+
node .gitnexus/run.cjs wiki
56+
```
57+
58+
Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
59+
60+
| Flag | Effect |
61+
| ------------------- | ----------------------------------------- |
62+
| `--force` | Force full regeneration |
63+
| `--model <model>` | LLM model (default: minimax/minimax-m2.5) |
64+
| `--base-url <url>` | LLM API base URL |
65+
| `--api-key <key>` | LLM API key |
66+
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
67+
| `--gist` | Publish wiki as a public GitHub Gist |
68+
69+
### list — Show all indexed repos
70+
71+
```bash
72+
node .gitnexus/run.cjs list
73+
```
74+
75+
Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
76+
77+
## After Indexing
78+
79+
1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
80+
2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
81+
82+
## Troubleshooting
83+
84+
- **"Not inside a git repository"**: Run from a directory inside a git repo
85+
- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
86+
- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

‎.claude/skills/gitnexus/gitnexus-debugging/SKILL.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
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. query({search_query: "<error or symptom>"}) → Find related execution flows
20+
2. context({name: "<suspect>"}) → See callers/callees/processes
21+
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
22+
4. cypher({statement: "MATCH path..."}) → Custom traces if needed
23+
```
24+
25+
> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
26+
27+
## Checklist
28+
29+
```
30+
- [ ] Understand the symptom (error message, unexpected behavior)
31+
- [ ] query for error text or related code
32+
- [ ] Identify the suspect function from returned processes
33+
- [ ] context to see callers and callees
34+
- [ ] Trace execution flow via process resource if applicable
35+
- [ ] 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 | `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+
| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
49+
50+
## Tools
51+
52+
**query** — find code related to error:
53+
54+
```
55+
query({search_query: "payment validation error"})
56+
→ Processes: CheckoutFlow, ErrorHandling
57+
→ Symbols: validatePayment, handlePaymentError, PaymentException
58+
```
59+
60+
**context** — full context for a suspect:
61+
62+
```
63+
context({name: "validatePayment"})
64+
→ Incoming calls: processCheckout, webhookHandler
65+
→ Outgoing calls: verifyCard, fetchRates (external API!)
66+
→ Processes: CheckoutFlow (step 3/7)
67+
```
68+
69+
**cypher** — custom call chain traces:
70+
71+
```cypher
72+
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
73+
RETURN [n IN nodes(path) | n.name] AS chain
74+
```
75+
76+
**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
77+
78+
```
79+
trace({ from: "processCheckout", to: "fetchRates" })
80+
→ status: ok, hopCount: 3
81+
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
82+
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
83+
```
84+
85+
When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
86+
87+
## Example: "Payment endpoint returns 500 intermittently"
88+
89+
```
90+
1. query({search_query: "payment error handling"})
91+
→ Processes: CheckoutFlow, ErrorHandling
92+
→ Symbols: validatePayment, handlePaymentError
93+
94+
2. context({name: "validatePayment"})
95+
→ Outgoing calls: verifyCard, fetchRates (external API!)
96+
97+
3. READ gitnexus://repo/my-app/process/CheckoutFlow
98+
→ Step 3: validatePayment → calls fetchRates (external)
99+
100+
4. Root cause: fetchRates calls external API without proper timeout
101+
```

‎.claude/skills/gitnexus/gitnexus-exploring/SKILL.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +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. query({search_query: "<what you want to understand>"}) → Find related execution flows
22+
4. 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 `node .gitnexus/run.cjs analyze` in terminal.
27+
28+
## Checklist
29+
30+
```
31+
- [ ] READ gitnexus://repo/{name}/context
32+
- [ ] query for the concept you want to understand
33+
- [ ] Review returned processes (execution flows)
34+
- [ ] 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+
**query** — find execution flows related to a concept:
51+
52+
```
53+
query({search_query: "payment processing"})
54+
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
55+
→ Symbols grouped by flow with file locations
56+
```
57+
58+
**context** — 360-degree view of a symbol:
59+
60+
```
61+
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. query({search_query: "payment processing"})
72+
→ CheckoutFlow: processPayment → validateCard → chargeStripe
73+
→ RefundFlow: initiateRefund → calculateRefund → processRefund
74+
3. context({name: "processPayment"})
75+
→ Incoming: checkoutHandler, webhookHandler
76+
→ Outgoing: validateCard, chargeStripe, saveTransaction
77+
4. Read src/payments/processor.ts for implementation details
78+
```

0 commit comments

Comments
 (0)