moons

name	moons
description	moons
user-invocable	true
allowed-tools	["Read","Write","Edit","Grep","Glob","Bash","Agent","Skill","TeamCreate","TeamDelete","TaskCreate","TaskGet","TaskList","TaskOutput","TaskStop","TaskUpdate","SendMessage"]

moons

Builds a structured knowledge graph with interactive visualization by leveraging chomp for codebase ingestion. Uses Agent Teams to isolate each phase into its own context window.

Invocation

/moons [<git-url>|update]

• No arguments: scan the local repo, build graph from scratch
• <git-url>: scan an external GitHub repo, offer to clone after
• update: re-scan local repo, diff against existing graph.json (single agent, no teams)

Procedure

1. Check for existing moons

If moons/graph.json exists AND the argument is NOT update:

• Tell the user moons is already initialized
• Suggest /moons update to re-scan, or delete moons/ to start fresh
• Stop

2. Handle update mode (single agent, no teams)

If argument is update:

1. Run /chomp local via Skill tool
2. Find chunks at chomp/.rlm_state/chunks/
3. Extract graph data from chunks using subagents (same extraction rules as step 5 below)
4. Read existing moons/graph.json and diff:
   • New nodes not in old graph -> add
   • Old nodes not in new extraction -> remove
   • Changed nodes -> update desc
   • Same for edges
5. Write updated moons/graph.json and content files
6. Run python3 moons/sync.py
7. Print summary of changes
8. Stop (no teams needed)

3. Ensure chomp is initialized

Check if .claude/skills/chomp/SKILL.md exists. If not, invoke /chomp-init via the Skill tool.

4. Create the agent team

Determine the mode and repo name:

• Local mode: no argument. Repo name is local.
• External mode: argument is a git URL. Repo name is extracted from URL (e.g. https://github.com/user/my-repo -> my-repo).

Create an agent team with 4 teammates. Create tasks with dependencies:

Task 1: Ingest — no dependencies
Task 2: Build graph — depends on Task 1
Task 3: Build visualization — depends on Task 2
Task 4: Cleanup — depends on Tasks 1, 2, 3

Teammate: Ingestion

Spawn prompt:

You are the Ingestion teammate for the moons knowledge graph tool.

Your job: run chomp to ingest and analyze a codebase.

MODE: {local|external}
{If external: URL: <git-url>}

Steps:
1. Run the chomp skill:
   - Local mode: /chomp local
   - External mode: /chomp <git-url>
2. Let chomp finish completely (dump, chunk, bits, RLM analysis).
3. Verify chunks exist at chomp/.rlm_state/chunks/
4. Mark your task complete.

The Graph teammate will read the chunks after you finish.
Do NOT read source files directly — chomp handles all ingestion.
Say "scanning" or "analyzing" to the user, never "chomping."

Teammate: Graph

Spawn prompt:

You are the Graph teammate for the moons knowledge graph tool.

Your job: read the chunks produced by ingestion, extract a knowledge graph, and write graph.json + content files.

Wait for the Ingestion task to complete before starting.

Steps:

1. Find all chunk files:
   ls chomp/.rlm_state/chunks/*.txt chomp/.rlm_state/chunks/**/*.txt 2>/dev/null

2. For each chunk file, use a subagent with this query:

   Read the file at <chunk-path>.

   For each source file in this chunk, extract:
   a) A node: { "id": "<slugified-name>", "type": "<one of: code|note|concept|config|data|test|style|script>", "desc": "<1 sentence summary>" }
   b) Edges from this file: { "from": "<this-node-id>", "to": "<target-node-id>", "rel": "<references|imports|relates|supports|uses|contains>" }

   Rules:
   - Node IDs: slugify the filename without extension (e.g. src/index.ts -> src-index, README.md -> readme)
   - "imports" edges: explicit import/require/include statements
   - "references" edges: file paths mentioned in code, links in markdown
   - "uses" edges: runtime dependencies between modules
   - "contains" edges: parent directories or classes containing children
   - "relates"/"supports" edges: semantic relationships
   - Only create edges to files you can see exist in the filetree
   - Return ONLY valid JSON: { "nodes": [...], "edges": [...] }
   - Do not wrap in markdown code fences

   Launch subcalls in parallel. Collect all JSON results.

3. Merge all subcall results:
   - Deduplicate nodes by id
   - Convert flat edges into nested format: each node gets an edges array with { "to": "...", "rel": "..." }
   - Compute gravity for each node: (total edges touching this node) / (max edges on any node), clamped to [0.1, 1.0]
   - Set file to <type>/<id>.md for each node

4. Create moons/ directory. Write moons/graph.json:
   {
     "meta": {
       "version": "1.0",
       "description": "Project knowledge graph.",
       "node_types": ["...detected types..."],
       "edge_types": ["references", "imports", "relates", "supports", "uses", "contains"]
     },
     "nodes": [
       {
         "id": "slugified-name",
         "type": "detected-type",
         "desc": "1-2 sentence summary",
         "file": "type/name.md",
         "edges": [{ "to": "target-id", "rel": "references" }],
         "gravity": 0.5
       }
     ]
   }

5. For each node, create moons/<type>/<id>.md:
   ## <id>

   <desc>

   **Source:** `<original file path>`

   Only create directories for types that have nodes: mkdir -p moons/<type>

6. Mark your task complete.

Teammate: Viz

Spawn prompt:

You are the Viz teammate for the moons knowledge graph tool.

Your job: build an interactive visualization website for the knowledge graph.

REPO NAME: {repo-name}

Wait for the Build Graph task to complete before starting.

Steps:

1. Read moons/graph.json to understand the graph structure (types, node count, edge count).

2. Read the template at ~/.claude/skills/moons/templates/index.html as your starting point.

3. Customize the template:
   - Replace {TITLE} with: {repo-name}
   - Replace {COLORS_JSON} with a JSON object mapping each detected type to a color.
     Palette in order: #e74c3c, #3498db, #2ecc71, #e67e22, #9b59b6, #f1c40f, #1abc9c, #95a5a6, #e91e63, #00bcd4
   - Replace {BASE_RADIUS_JSON} with a JSON object mapping each type to radius 10

4. Review the resulting HTML/JS and fix any issues you spot:
   - Verify search actually filters/highlights nodes
   - Verify legend toggle works (show/hide by type)
   - Verify tooltip and detail panel reference correct data fields
   - Verify D3 force simulation parameters are reasonable for the node count
   - Fix any bugs or improve UX where you see opportunities

5. Write the final result to moons/index.html.

6. Copy utility scripts:
   cp ~/.claude/skills/moons/templates/sync.py moons/sync.py
   cp ~/.claude/skills/moons/templates/query.py moons/query.py

7. Sync graph data into the HTML:
   python3 moons/sync.py

8. Mark your task complete.

The visualization must support:
- D3 force-directed graph with zoom and drag
- Search box that highlights matching nodes (by id, desc, or type)
- Legend with clickable type filters
- Hover tooltips showing node info
- Click detail panel with edges (outgoing and incoming)
- Stats display (node count, edge count)
- Dark theme (#0a0a1a background)

Teammate: Cleanup

Spawn prompt:

You are the Cleanup teammate for the moons knowledge graph tool.

Your job: remove temporary files created during the build process.

Wait for ALL other tasks (Ingest, Build Graph, Build Visualization) to complete before starting.

Steps:

1. Remove the RLM state directory:
   rm -rf chomp/.rlm_state/

2. Verify the chomp dump file still exists (do NOT delete it):
   ls chomp/*.md
   This file is kept for future /bite queries.

3. Verify moons/ directory is self-contained:
   ls moons/
   It should contain: graph.json, index.html, sync.py, query.py, and type subdirectories with .md files.

4. Mark your task complete.

5. Lead: post-team tasks

After all 4 tasks complete:

1. Update CLAUDE.md (first run only, not external mode pointing to different repo): Check if CLAUDE.md contains ## moons. If not, append:

   
   ## moons - knowledge graph
   
   This project has a knowledge graph in `moons/`. When the user mentions "moons" or asks you to "check moons," read `moons/graph.json` for project context. Do NOT invoke the `/moons` skill unless explicitly asked to build or update the graph.
   
   ### Reading the graph (default)
   - Read `moons/graph.json` when you need project context or the user says "check moons"
   - Use `python3 moons/query.py <command>` to query the graph
   - Update graph.json and summary files when you create or modify files
   - Run `python3 moons/sync.py` after changing graph.json
   
   ### Building / updating (only when asked)
   - `/moons` — scan local repo, build knowledge graph + visualization
   - `/moons <git-url>` — build knowledge graph from external repo, offer to clone after
   - `/moons update` — re-scan local repo, diff against existing graph.json
   

2. Serve and open:

   cd moons && python3 -c "
   import http.server, socketserver, threading, webbrowser
   with socketserver.TCPServer(('', 0), http.server.SimpleHTTPRequestHandler) as s:
       port = s.server_address[1]
       print(f'http://localhost:{port}/index.html')
       webbrowser.open(f'http://localhost:{port}/index.html')
       s.handle_request()
       s.handle_request()
   "
   

3. Report:

   • "Moons initialized. Visualization running at http://localhost:/index.html"
   • "Graph: moons/graph.json (N nodes, E edges)"
   • Node breakdown by type

4. Clean up the team via TeamDelete.

6. External mode: offer to clone

External mode only. After visualization opens, ask if the user wants to clone the repo into the working directory. If yes, git clone <git-url>.

Guardrails

• NEVER read source files directly. Always go through chomp.
• Chomp is internal infrastructure — say "scanning" or "analyzing" to the user, not "chomping."
• Do not paste large raw chunks into the main chat context.
• The moons/ directory is the persistent output.
• Agent Teams require CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS enabled in settings.
• Update mode uses a single agent — no teams needed for diffs.
• Each teammate gets a fresh context window — this is the key advantage over the old single-agent flow.