code-graph-llm - npm Package Compare versions

Comparing version 3.2.1 to 3.3.0

index.js

@@ -453,2 +453,4 @@ #!/usr/bin/env node
     try {
+      const skillsDir = (platform) => path.join(this.home, `.${platform}`, 'skills');
+
       if (s === 'all' || s === 'projectmap') {
@@ -459,8 +461,10 @@ await this.removeFile('.cursor/rules/projectmap.mdc');
         await this.removeFile('.kiro/steering/projectmap.md');
-        await fsp.rm(path.join(this.home, `.${p}`, 'skills', 'projectmap'), { recursive: true, force: true });
+        await this.removeFile('.opencode/plugins/projectmap.js');
+        await fsp.rm(path.join(skillsDir(p), 'projectmap'), { recursive: true, force: true });
       }
+      
       if (s === 'all' || s === 'reflections') {
         await this.removeFile('.cursor/rules/reflections.mdc');
         await this.removeFile('.agent/rules/reflections.md');
-        await fsp.rm(path.join(this.home, `.${p}`, 'skills', 'reflections'), { recursive: true, force: true });
+        await fsp.rm(path.join(skillsDir(p), 'reflections'), { recursive: true, force: true });
       }
@@ -471,5 +475,14 @@
           'CLAUDE.md', 'GEMINI.md', 'AGENTS.md', '.clinerules', '.roomodes',
-          '.github/copilot-instructions.md', 'opencode.json', '.codex/hooks.json'
+          '.github/copilot-instructions.md', 'opencode.json'
         ];
         for (const f of filesToRemove) await this.removeFile(f);
+        
+        // Defensive folder cleanup
+        const folders = ['.claude', '.gemini', '.codex', '.opencode', '.agent', '.kiro'];
+        for (const f of folders) {
+          const fullPath = path.join(this.cwd, f);
+          if (fs.existsSync(fullPath) && (await fsp.readdir(fullPath)).length === 0) {
+            await fsp.rmdir(fullPath);
+          }
+        }
       }
@@ -515,2 +528,112 @@
 
+/**
+ * Manages sub-agent registrations and orchestrator integrations.
+ */
+class AgentManager {
+  constructor(cwd) {
+    this.cwd = cwd;
+    this.home = os.homedir();
+  }
+
+  async execute(platform, action) {
+    if (!platform) return console.error('[Code-Graph] Platform required. Usage: code-graph install-agent <platform>');
+    const p = platform.toLowerCase();
+    const act = (action || 'install-agent').toLowerCase();
+
+    if (act === 'install-agent') await this.install(p);
+    else if (act === 'uninstall-agent') await this.uninstall(p);
+    else console.error(`[Code-Graph] Unknown action: ${act}. Use install-agent or uninstall-agent.`);
+  }
+
+  async install(p) {
+    console.log(`[Code-Graph] Registering code-graph as sub-agent for ${p}...`);
+    try {
+      switch (p) {
+        case 'gemini': await this.installGeminiAgent(); break;
+        case 'claude':
+        case 'cursor': 
+          await this.installMCPServer(); 
+          break;
+        case 'kiro': await this.installKiroAgent(); break;
+        case 'antigravity': await this.installAntigravityAgent(); break;
+        default:
+          await this.installGenericPersona();
+      }
+      console.log(`[Code-Graph] Successfully registered sub-agent for ${p}.`);
+    } catch (err) {
+      console.error(`[Code-Graph] Agent registration failed for ${p}: ${err.message}`);
+    }
+  }
+
+  async uninstall(p) {
+    console.log(`[Code-Graph] Removing sub-agent for ${p}...`);
+    try {
+      switch (p) {
+        case 'gemini': await fsp.rm(path.join(this.home, '.gemini', 'subagents', 'code-graph'), { recursive: true, force: true }); break;
+        case 'claude':
+        case 'cursor': await this.removeFile('mcp-server-code-graph.json'); break;
+        case 'kiro': await fsp.rm(path.join(this.home, '.kiro', 'agents', 'code-graph'), { recursive: true, force: true }); break;
+        case 'antigravity': await fsp.rm(path.join(this.home, '.agent', 'subagents', 'code-graph'), { recursive: true, force: true }); break;
+        default: await this.removeFile('.code-graph-agent.md');
+      }
+      
+      // Defensive folder cleanup for global paths
+      const globalFolders = [
+        path.join(this.home, '.gemini', 'subagents'),
+        path.join(this.home, '.kiro', 'agents'),
+        path.join(this.home, '.agent', 'subagents')
+      ];
+      for (const f of globalFolders) {
+        if (fs.existsSync(f) && (await fsp.readdir(f)).length === 0) await fsp.rmdir(f);
+      }
+
+      console.log(`[Code-Graph] Successfully removed sub-agent for ${p}.`);
+    } catch (err) {
+      console.error(`[Code-Graph] Agent removal failed: ${err.message}`);
+    }
+  }
+
+  async removeFile(filename) {
+    const fullPath = path.join(this.cwd, filename);
+    if (fs.existsSync(fullPath)) await fsp.unlink(fullPath);
+  }
+
+  async installGeminiAgent() {
+    const agentDir = path.join(this.home, '.gemini', 'subagents', 'code-graph');
+    await fsp.mkdir(agentDir, { recursive: true });
+    const content = `# Code-Graph Agent\nRole: Specialized analyst for codebase mapping and memory persistence.\nCapabilities: Can run \`code-graph generate\` to refresh the project map and \`code-graph reflect\` to save lessons.\nUsage: Delegate architectural or environmental analysis to this agent.\n`;
+    await fsp.writeFile(path.join(agentDir, 'AGENT.md'), content);
+  }
+
+  async installMCPServer() {
+    const config = {
+      mcpServers: {
+        "code-graph": {
+          command: "node",
+          args: [fileURLToPath(import.meta.url), "generate"],
+          description: "Generates a compact codebase map for LLM context optimization."
+        }
+      }
+    };
+    await fsp.writeFile(path.join(this.cwd, 'mcp-server-code-graph.json'), JSON.stringify(config, null, 2));
+  }
+
+  async installKiroAgent() {
+    const agentDir = path.join(this.home, '.kiro', 'agents', 'code-graph');
+    await fsp.mkdir(agentDir, { recursive: true });
+    await fsp.writeFile(path.join(agentDir, 'AGENT.md'), `# Code-Graph\nSpecialist in project structure and navigation.\n`);
+  }
+
+  async installAntigravityAgent() {
+    const agentDir = path.join(this.home, '.agent', 'subagents', 'code-graph');
+    await fsp.mkdir(agentDir, { recursive: true });
+    await fsp.writeFile(path.join(agentDir, 'AGENT.md'), `# Code-Graph Sub-Agent\nHandles structural mapping and reflection.\n`);
+  }
+
+  async installGenericPersona() {
+    const content = `# SYSTEM PROMPT: Code-Graph Persona\nYour role is now to act as the Code-Graph Specialist. \n1. Use \`llm-code-graph.md\` to provide architectural overviews.\n2. Strictly follow the protocol in \`llm-agent-rules.md\`.\n3. Always suggest a \`code-graph reflect\` entry after resolving a non-obvious issue.\n`;
+    await fsp.writeFile(path.join(this.cwd, '.code-graph-agent.md'), content);
+  }
+}
+
 // --- CLI Entry Point ---
@@ -540,4 +663,28 @@
       case 'install-skills':
-        await new SkillManager(cwd).execute(args[0], args[1], args[2]);
+        await new SkillManager(cwd).execute(args[0], 'install-skills', args[1]);
         break;
+      case 'uninstall-skills':
+        await new SkillManager(cwd).execute(args[0], 'uninstall-skills', args[1]);
+        break;
+      case 'install-agent':
+        await new AgentManager(cwd).execute(args[0], 'install-agent');
+        break;
+      case 'uninstall-agent':
+        await new AgentManager(cwd).execute(args[0], 'uninstall-agent');
+        break;
+      case 'install':
+        await new SkillManager(cwd).execute(args[0], 'install-skills');
+        await new AgentManager(cwd).execute(args[0], 'install-agent');
+        break;
+      case 'uninstall':
+        await new SkillManager(cwd).execute(args[0], 'uninstall-skills');
+        await new AgentManager(cwd).execute(args[0], 'uninstall-agent');
+        break;
+      case 'uninstall-all':
+        console.log('[Code-Graph] Performing full cleanup...');
+        for (const p of platforms) {
+          await new SkillManager(cwd).execute(p, 'uninstall-skills');
+          await new AgentManager(cwd).execute(p, 'uninstall-agent');
+        }
+        break;
       case 'watch':
@@ -544,0 +691,0 @@ startWatcher(cwd);

llm-agent-project-learnings.md

@@ -18,2 +18,3 @@ # LLM_AGENT_PROJECT_LEARNINGS
 - [TOOLING: 2026-04-16] Upgraded to v3.2.0: "Universal Agent OS" release. Restored full surgical integration for Antigravity, Kiro, Codex, and OpenCode. Implemented segregated skill hooks for platforms that support them.
-- [TOOLING: 2026-04-16] Upgraded to v3.2.1: Exhaustive documentation of platform-specific installation details and integration table synchronization.
+- [TOOLING: 2026-04-16] Upgraded to v3.2.1: Exhaustive documentation of platform-specific installation details and integration table synchronization.
+- [TOOLING: 2026-04-16] Upgraded to v3.3.0: "Active Agent Orchestration" release. Added `install-agent` for explicit delegation, unified `install` commands, and automated `preuninstall` cleanup logic.

llm-code-graph.md

@@ -8,3 +8,3 @@ # CODE_GRAPH_MAP
 - [CORE] index.js (↑7 ↓1) [TODO: |FIXME|BUG|DEPRECATED):?\s*(.*)/i,, bug: s or complex regex pitfalls., bug: s or version deprecations., bug: fix or failure.\n`;, bug: ,"] | desc: !usrbinenv node
-  - syms: [CONFIG [=], CodeParser [--- Core Services --- Handles extraction of symbols, edges, and metadata from source code.], ProjectInitializer [Scaffolds the initial agent-agnostic rule and reflection files.], ProjectMapper [Manages the project mapping and file generation.], ReflectionManager [Manages project reflections and lessons learned.], SUPPORTED_EXTENSIONS [: [], SkillManager [Manages platform-specific skills and agent integrations.], add [(context ? `${display} [${context}]` : display)], appendToFile [('CLAUDE.md', section)], execute [(platform, action, skill)], extract [(content)], init [(cwd)], install [-skills <platform> [projectmap|reflections]')], installGitHook [(cwd)], installGlobalSkill [('gemini', 'projectmap', skillContent)], installProjectMap [(p)], installReflections [(p)], main [|app|server|cli)\./i.test(path.basename(relPath))], processFile [(fullPath, relPath)], removeFile [('.cursor/rules/projectmap.mdc')], uninstall [-skills') await this.uninstall(p, s)], walk [(dir, ig)], writeFile [(path.join(this.cwd, CONFIG.MAP_FILE)], writeJson [('.claude/settings.json', { hooks: { preToolUse: [{ tools: ['glob', 'grep'], message: `Skill(ProjectMap)]]
+  - syms: [AgentManager [Manages sub-agent registrations and orchestrator integrations.], CONFIG [=], CodeParser [--- Core Services --- Handles extraction of symbols, edges, and metadata from source code.], ProjectInitializer [Scaffolds the initial agent-agnostic rule and reflection files.], ProjectMapper [Manages the project mapping and file generation.], ReflectionManager [Manages project reflections and lessons learned.], SUPPORTED_EXTENSIONS [: [], SkillManager [Manages platform-specific skills and agent integrations.], add [(context ? `${display} [${context}]` : display)], appendToFile [('CLAUDE.md', section)], execute [(platform, action, skill)], extract [(content)], init [(cwd)], install [-skills <platform> [projectmap|reflections]')], installAntigravityAgent [()], installGeminiAgent [()], installGenericPersona [()], installGitHook [(cwd)], installGlobalSkill [('gemini', 'projectmap', skillContent)], installKiroAgent [()], installMCPServer [()], installProjectMap [(p)], installReflections [(p)], main [|app|server|cli)\./i.test(path.basename(relPath))], processFile [(fullPath, relPath)], removeFile [('.cursor/rules/projectmap.mdc')], uninstall [-skills') await this.uninstall(p, s)], walk [(dir, ig)], writeFile [(path.join(this.cwd, CONFIG.MAP_FILE)], writeJson [('.claude/settings.json', { hooks: { preToolUse: [{ tools: ['glob', 'grep'], message: `Skill(ProjectMap)]]
 - [CORE] test/index.test.js (↑10 ↓0) | desc: 
@@ -11,0 +11,0 @@ - syms: []

package.json

 {
   "name": "code-graph-llm",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Compact, language-agnostic codebase mapper for LLM token efficiency.",
@@ -29,4 +29,5 @@ "main": "index.js",
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "preuninstall": "node index.js uninstall-all"
   }
 }

README.md

@@ -1,29 +0,72 @@
-# CODE-GRAPH (v3.2.1)
+# CODE-GRAPH (v3.3.0)
 
 A language-agnostic, ultra-compact codebase mapper and **agent memory system** designed specifically for LLM agents. It optimizes context and token usage while enabling agents to learn from their own mistakes across sessions.
 
-## 🚀 New in v3.2: Universal Agent OS
-- **Enhanced Platform Matrix:** Full surgical integration for Antigravity, Kiro, and Roo Code.
-- **Segregated Skill Hooks:** Isolated `preToolUse` and `beforeTool` hooks for Mapping vs. Reflections.
-- **Deep Steering:** Standardized `AGENTS.md` and `.cursor/rules/` for non-hookable platforms.
-- **Production-Ready Core:** Refactored Service-based architecture with full async support.
+## 🚀 New in v3.3: Active Agent Orchestration
+- **Active Sub-Agents:** Register `code-graph` as a specialized sub-agent for Gemini, Claude, and more.
+- **Unified Setup:** New `install` and `uninstall` commands for effortless full-system configuration.
+- **MCP Tool Support:** Expose mapping and reflection tools via Model Context Protocol (Claude/Cursor).
+- **Automated Cleanup:** Smart `preuninstall` hook removes all global and local data upon NPM uninstall.
 
-## 🛠️ The Code-Graph Skills
+## 🛠️ The Code-Graph Architecture
 
-Code-Graph provides two primary skills that can be installed independently or together (default).
+Code-Graph operates in two modes: **Passive Skills** and **Active Agents**.
 
-### 1. **Structural Mapping (`projectmap`)**
-*   **What it does:** Scans your project for symbols (classes, functions, interfaces) and builds a dense dependency graph (`imports`, `requires`, `inheritance`).
-*   **Skill Goal:** High-level architectural awareness and navigation.
-*   **Agent Benefit:** Prevents "hallucinating" file paths and reduces token usage by giving the agent a compact map (`llm-code-graph.md`) instead of raw file content.
+| Mode | Paradigm | Benefit | Command |
+| :--- | :--- | :--- | :--- |
+| **Unified** | Both | Complete setup of skills and agent. | `code-graph install <platform>` |
+| **Skills** | Passive Context | Injects the graph into the agent's existing loop. | `code-graph install-skills` |
+| **Agents** | Active Delegation | Registers `code-graph` as a specialized sub-agent. | `code-graph install-agent` |
 
-### 2. **Memory Persistence (`reflections`)**
-*   **What it does:** Logs non-obvious fixes, environment quirks, and architectural lessons into `llm-agent-project-learnings.md`.
-*   **Skill Goal:** Persistent project memory across sessions.
-*   **Agent Benefit:** Enables "Cross-Session Memory." If an agent fixes a bug in one session, the next agent reads the reflection and avoids the same pitfall.
+---
 
+### 1. Unified Installation (Recommended)
+Get the full Code-Graph experience by installing both skills and the active sub-agent in one command.
+
+```bash
+# Recommended: Standard full setup
+code-graph install gemini
+```
+
+**Uninstall** using `code-graph uninstall <platform>`.
+
 ---
 
-## 🚀 Automated Agent Integration
+### 2. Code-Graph Skills (Passive)
+**Skills** are "always-on" configurations. They ensure your agent *always* sees the codebase map before it acts.
 
+*   **ProjectMap Skill:** Architectural awareness and navigation via `llm-code-graph.md`.
+*   **Reflections Skill:** Persistent project memory via `llm-agent-project-learnings.md`.
+
+**Usage:**
+```bash
+# Install all skills for a platform
+code-graph install-skills gemini
+
+# Selective installation
+code-graph install-skills cursor projectmap
+```
+
+---
+
+### 2. Code-Graph Agents (Active)
+**Agents** are specialized personas. Instead of just reading a file, the main orchestrator (like Gemini CLI or Claude) can **delegate** complex mapping or analysis tasks to the Code-Graph agent.
+
+*   **Native Sub-Agents:** Gemini, Antigravity, and Kiro register `code-graph` as an expert in their global config.
+*   **MCP Servers:** Claude and Cursor use the Model Context Protocol to call `code-graph` as a live tool.
+*   **Persona Prompts:** Aider and others use a `.code-graph-agent.md` system prompt to "become" the specialist.
+
+**Usage:**
+```bash
+# Register code-graph as a sub-agent
+code-graph install-agent claude
+
+# The main agent can now say:
+# "Hey code-graph, analyze the dependency chain of the auth module."
+```
+
+---
+
+## 🚀 Platform Support Matrix
+
 Configure your agent to use these skills by running the `install-skills` command. **Both skills are installed by default.**
@@ -156,3 +199,17 @@
 
-## How it works
+## 🤖 Sub-Agent Registration
+
+Register `code-graph` as an active sub-agent to enable explicit delegation.
+
+| Platform | Command | Action Taken |
+| :--- | :--- | :--- |
+| **Gemini CLI** | `code-graph install-agent gemini` | Registers global agent in `~/.gemini/subagents/`. |
+| **Claude / Cursor** | `code-graph install-agent claude` | Creates `mcp-server-code-graph.json` (MCP tool config). |
+| **Antigravity** | `code-graph install-agent antigravity` | Registers agent in `~/.agent/subagents/`. |
+| **Kiro IDE/CLI** | `code-graph install-agent kiro` | Registers agent in `~/.kiro/agents/`. |
+| **Generic Agent** | `code-graph install-agent generic` | Generates `.code-graph-agent.md` persona prompt. |
+
+**Uninstall** using `uninstall-agent <platform>`.
+
+## 🛠️ Implementation Details
 1. **File Scanning:** Recursively walks the directory, ignoring patterns in `.gitignore`.
@@ -159,0 +216,0 @@ 2. **Context Extraction:** Scans for classes, functions, and variables while ignoring matches in comments.

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

54600

19.28%

Lines of code

784

20.43%

Number of lines in readme file

219

35.19%

No dependency changes