xtrm-tools 2.0.0

package/cli/dist/index.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/cli/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "xtrm-cli",
+  "version": "2.0.0",
+  "description": "Claude Code tools installer (skills, hooks, MCP servers)",
+  "main": "./dist/index.js",
+  "type": "module",
+  "bin": {
+    "xtrm": "./dist/index.cjs"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "start": "node dist/index.cjs"
+  },
+  "dependencies": {
+    "boxen": "^8.0.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "comment-json": "^4.2.3",
+    "conf": "^12.0.0",
+    "dotenv": "^16.4.5",
+    "fs-extra": "^11.2.0",
+    "kleur": "^4.1.5",
+    "listr2": "^10.1.1",
+    "minimist": "^1.2.8",
+    "ora": "^9.3.0",
+    "project": "^0.1.6",
+    "prompts": "^2.4.2",
+    "tdd-guard": "^1.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.3.0",
+    "tdd-guard-vitest": "^0.1.6",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/config/.env.example

@@ -0,0 +1,40 @@
+# MCP Servers Environment Variables
+# 
+# IMPORTANT: DO NOT edit this file directly!
+# Copy your environment variables to: ~/.config/jaggers-agent-tools/.env
+# 
+# The CLI will automatically create and manage this file during sync.
+#
+# To get started:
+# 1. Run the sync command: npx ./cli
+# 2. The CLI will create ~/.config/jaggers-agent-tools/.env if missing
+# 3. Edit that file and add your API keys
+# 4. Re-run sync to apply the changes
+
+# =============================================================================
+# MCP: Context7 (Documentation Lookup)
+# =============================================================================
+# Get your API key from: https://context7.com/
+# Required for context7 MCP server to function
+CONTEXT7_API_KEY=ctx7sk-your-api-key-here
+
+# =============================================================================
+# MCP: Serena (Code Analysis)
+# =============================================================================
+# Optional: Override auto-detected project name
+# If not set, Serena will auto-detect from current working directory
+# SERENA_PROJECT_NAME=my-project
+
+# =============================================================================
+# MCP: Omni Search Engine (Optional)
+# =============================================================================
+# No environment variables required
+# Service must be running locally on http://127.0.0.1:8765/sse
+# See: https://github.com/Jaggerxtrm/omni-search-engine
+
+# =============================================================================
+# MCP: unitAI (Optional)
+# =============================================================================
+# No environment variables required
+# Requires Node.js with npx available
+# See: https://github.com/Jaggerxtrm/unitAI

package/config/hooks.json

@@ -0,0 +1,36 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "script": "skill-suggestion.py",
+        "timeout": 5000
+      }
+    ],
+    "SessionStart": [
+      {
+        "script": "serena-workflow-reminder.py"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read|Edit",
+        "script": "serena-workflow-reminder.py"
+      },
+      {
+        "matcher": "Bash",
+        "script": "type-safety-enforcement.py",
+        "timeout": 30000
+      },
+      {
+        "matcher": "Edit|Write",
+        "script": "type-safety-enforcement.py"
+      }
+    ]
+  },
+  "skillSuggestions": {
+    "enabled": true
+  },
+  "statusLine": {
+    "script": "statusline-starship.sh"
+  }
+}

package/config/mcp_servers.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "../vsync_repo/schemas/mcp_servers.schema.json",
+  "$metadata": {
+    "description": "Core MCP servers - installed by default for all agents",
+    "agents": ["claude-code", "gemini", "qwen", "antigravity"],
+    "version": "2.0.0"
+  },
+  "mcpServers": {
+    "serena": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/oraios/serena",
+        "serena",
+        "start-mcp-server",
+        "--context",
+        "ide-assistant"
+      ],
+      "env": {},
+      "_notes": {
+        "project": "Auto-detected from current working directory during usage",
+        "prerequisite": "Requires uvx (uv package manager)"
+      }
+    },
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
+      },
+      "_notes": {
+        "auth": "Requires API key - user will be prompted during sync",
+        "env_file": "Store key in .env or ~/.jaggers/.env"
+      }
+    },
+    "github-grep": {
+      "type": "http",
+      "url": "https://mcp.grep.app"
+    },
+    "deepwiki": {
+      "type": "http",
+      "url": "https://mcp.deepwiki.com/mcp"
+    }
+  }
+}

package/config/mcp_servers_optional.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "../vsync_repo/schemas/mcp_servers.schema.json",
+  "$metadata": {
+    "description": "Optional MCP servers - user chooses during sync",
+    "agents": [
+      "claude-code",
+      "gemini",
+      "qwen",
+      "antigravity"
+    ],
+    "version": "2.0.0"
+  },
+  "mcpServers": {
+    "unitAI": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@jaggerxtrm/unitai"
+      ],
+      "env": {},
+      "_notes": {
+        "description": "Multi-agent workflow orchestration system",
+        "repository": "https://github.com/Jaggerxtrm/unitAI",
+        "prerequisite": "Requires npx (Node.js)"
+      }
+    },
+    "omni-search-engine": {
+      "type": "sse",
+      "url": "http://127.0.0.1:8765/sse",
+      "env": {},
+      "_notes": {
+        "description": "Local search engine with SSE transport",
+        "repository": "https://github.com/Jaggerxtrm/omni-search-engine",
+        "prerequisite": "Requires running omni-search-engine service on port 8765"
+      }
+    },
+    "gitnexus": {
+      "type": "stdio",
+      "command": "gitnexus",
+      "args": [
+        "mcp"
+      ],
+      "env": {},
+      "_notes": {
+        "description": "Knowledge graph over your codebase \u2014 call chains, blast radius, execution flows, semantic search",
+        "prerequisite": "Requires npm install -g gitnexus",
+        "install_cmd": "npm install -g gitnexus",
+        "post_install_message": "\u26a1 GitNexus must be indexed per project!\n   Run inside each project you want to use it with:\n\n     npx gitnexus analyze\n"
+      }
+    }
+  }
+}

package/config/settings.json

@@ -0,0 +1,70 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__serena__list_memories",
+      "mcp__serena__read_memory",
+      "mcp__serena__get_symbols_overview",
+      "mcp__serena__find_symbol",
+      "mcp__serena__replace_symbol_body",
+      "Bash(python -m py_compile:*)",
+      "Bash(tree:*)",
+      "Bash(podman exec:*)",
+      "mcp__serena__list_dir",
+      "mcp__yfinance-market-intelligence__get_volatility_metrics",
+      "mcp__yfinance-market-intelligence__get_amt_snapshot",
+      "mcp__yfinance-market-intelligence__get_market_overview",
+      "Skill(scan-context)",
+      "mcp__gmail__search_emails",
+      "mcp__gmail__read_email",
+      "mcp__gmail__batch_modify_emails",
+      "mcp__gmail__list_email_labels",
+      "mcp__plugin_serena_serena__get_symbols_overview"
+    ],
+    "defaultMode": "default"
+  },
+  "model": "sonnet",
+  "skillSuggestions": {
+    "enabled": true
+  },
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$HOME/.claude/skills/documenting/scripts/drift_detector.py\" hook",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Grep|Glob|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.claude/hooks/gitnexus/gitnexus-hook.cjs\"",
+            "timeout": 8000,
+            "statusMessage": "Enriching with GitNexus graph context..."
+          }
+        ]
+      }
+    ]
+  },
+  "enabledPlugins": {
+    "pyright-lsp@claude-plugins-official": true,
+    "serena@claude-plugins-official": true,
+    "superpowers@superpowers-marketplace": true,
+    "convosync@convocli-marketplace": true,
+    "commit-commands@claude-plugins-official": true,
+    "context7@claude-plugins-official": true,
+    "github@claude-plugins-official": true,
+    "hookify@claude-plugins-official": true,
+    "agent-sdk-dev@claude-plugins-official": true,
+    "feature-dev@claude-plugins-official": true,
+    "plugin-dev@claude-plugins-official": true,
+    "claude-mem@thedotmack": true,
+    "code-simplifier@claude-plugins-official": true
+  }
+}

package/hooks/README.md

@@ -0,0 +1,156 @@
+# Hooks
+
+Claude Code hooks that extend agent behavior with automated checks, suggestions, and workflow enhancements.
+
+## Overview
+
+Hooks intercept specific events in the Claude Code lifecycle to provide:
+- Proactive skill suggestions
+- Safety guardrails (venv enforcement, type checking)
+- Workflow reminders
+- Status information
+
+## Skill-Associated Hooks
+
+### skill-suggestion.py
+
+**Purpose**: Proactively suggests `/prompt-improving` or `/delegating` based on prompt analysis.
+
+**Trigger**: UserPromptSubmit
+
+**Skills**: 
+- `prompt-improving` - Suggested for short/generic prompts
+- `delegating` - Suggested for simple tasks or explicit delegation requests
+
+**Configuration**:
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [{
+      "hooks": [{
+        "type": "command",
+        "command": "/home/user/.claude/hooks/skill-suggestion.py",
+        "timeout": 5000  // Claude: seconds (5000s), Gemini: milliseconds (5s)
+      }]
+    }]
+  },
+  "skillSuggestions": {
+    "enabled": true
+  }
+}
+```
+
+### skill-discovery.py
+
+**Purpose**: Scans the `@skills/` directory for `SKILL.md` files and injects a summarized list of all available local skills into the agent's context at the start of a session.
+
+**Trigger**: SessionStart
+
+**Skills**: All skills found in the repository's `skills/` directory.
+
+**Configuration**:
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "/home/user/.claude/hooks/skill-discovery.py",
+        "timeout": 5000
+      }]
+    }]
+  }
+}
+```
+
+### serena-workflow-reminder.py
+
+**Purpose**: Enforces semantic workflow using "Using Serena LSP".
+
+**Triggers**: 
+- `SessionStart`: Injects skill context.
+- `PreToolUse` (Read|Edit): Blocks inefficient usage.
+
+**Skill**: `using-serena-lsp`
+
+**Configuration**:
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{ "type": "command", "command": "/home/user/.claude/hooks/serena-workflow-reminder.py" }]
+    }],
+    "PreToolUse": [{
+      "matcher": "Read|Edit",
+      "hooks": [{ "type": "command", "command": "/home/user/.claude/hooks/serena-workflow-reminder.py" }]
+    }]
+  }
+}
+```
+
+## Standalone Hooks
+
+### pip-venv-guard.py
+
+**Purpose**: Prevents accidental `pip install` outside virtual environments.
+
+**Trigger**: PreToolUse (Bash)
+
+**Configuration**:
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "/home/user/.claude/hooks/pip-venv-guard.py",
+        "timeout": 3000  // 3 seconds in milliseconds (both Claude & Gemini)
+      }]
+    }]
+  }
+}
+```
+
+### type-safety-enforcement.py
+
+**Purpose**: Enforces type safety checks in Python code before execution.
+
+**Trigger**: PreToolUse (Bash, Edit, Write)
+
+**Configuration**:
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash|Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "/home/user/.claude/hooks/type-safety-enforcement.py",
+        "timeout": 10000  // 10 seconds in milliseconds (both Claude & Gemini)
+      }]
+    }]
+  }
+}
+```
+
+### statusline.js
+
+**Purpose**: Displays custom status line information.
+**Trigger**: StatusLine
+
+## Installation
+
+1. Copy hooks to Claude Code directory:
+   ```bash
+   cp hooks/* ~/.claude/hooks/
+   ```
+
+2. Make scripts executable:
+   ```bash
+   chmod +x ~/.claude/hooks/*.py ~/.claude/hooks/*.js
+   ```
+
+3. Configure hooks in `~/.claude/settings.json`.
+
+4. Restart Claude Code.

package/hooks/agent_context.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+import json
+import sys
+import os
+
+class AgentContext:
+    def __init__(self):
+        try:
+            # Read JSON from stdin once
+            self.data = json.load(sys.stdin)
+        except Exception:
+            self.data = {}
+            
+        self.tool_name = self.data.get('tool_name')
+        self.tool_input = self.data.get('tool_input', {})
+        self.event = self.data.get('hook_event_name')
+        self.prompt = self.data.get('prompt', '')
+        
+        # Determine Agent Type
+        if self.tool_name in ['run_shell_command', 'read_file', 'write_file', 'replace']:
+            self.agent_type = 'gemini'
+        elif self.tool_name in ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep']:
+            self.agent_type = 'claude'
+        else:
+            # Fallback based on env vars
+            if os.environ.get('GEMINI_PROJECT_DIR'):
+                self.agent_type = 'gemini'
+            else:
+                self.agent_type = 'claude'
+
+    def is_shell_tool(self):
+        return self.tool_name in ['Bash', 'run_shell_command']
+
+    def is_write_tool(self):
+        return self.tool_name in ['Write', 'write_file']
+
+    def is_edit_tool(self):
+        return self.tool_name in ['Edit', 'replace']
+
+    def get_command(self):
+        return self.tool_input.get('command', '')
+
+    def get_file_path(self):
+        return self.tool_input.get('file_path', '')
+
+    def block(self, reason, system_message=None):
+        """Unified block response.
+
+        Only PreToolUse hooks support permissionDecision: deny.
+        For other hooks, use continue: false to block execution.
+        """
+        output = {}
+
+        if system_message:
+            output["systemMessage"] = system_message
+
+        # Only PreToolUse hooks support permissionDecision
+        if self.event == "PreToolUse":
+            output["hookSpecificOutput"] = {
+                "hookEventName": self.event,
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason
+            }
+        else:
+            # For non-PreToolUse hooks, use continue: false to block
+            output["continue"] = False
+            output["stopReason"] = reason
+
+        print(json.dumps(output))
+        sys.exit(0)
+
+    def allow(self, system_message=None, additional_context=None):
+        """Unified allow response.
+
+        For PreToolUse hooks: outputs permissionDecision in hookSpecificOutput
+        For other hooks (UserPromptSubmit, SessionStart, PostToolUse):
+          only systemMessage and/or additionalContext are valid
+        """
+        output = {}
+
+        if system_message:
+            output["systemMessage"] = system_message
+
+        # Build hookSpecificOutput if we have PreToolUse or additionalContext
+        if self.event == "PreToolUse" or additional_context:
+            hook_output = {"hookEventName": self.event}
+
+            # Only PreToolUse supports permissionDecision
+            if self.event == "PreToolUse":
+                hook_output["permissionDecision"] = "allow"
+
+            if additional_context:
+                hook_output["additionalContext"] = additional_context
+
+            output["hookSpecificOutput"] = hook_output
+
+        # Only print output if we have something to say
+        if output:
+            print(json.dumps(output))
+
+        sys.exit(0)
+
+    def fail_open(self):
+        """Standard fail-open behavior"""
+        sys.exit(0)

package/hooks/gitnexus/gitnexus-hook.cjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * GitNexus Claude Code Hook
+ *
+ * PreToolUse handler — intercepts Grep/Glob/Bash searches
+ * and augments with graph context from the GitNexus index.
+ *
+ * NOTE: SessionStart hooks are broken on Windows (Claude Code bug).
+ * Session context is injected via CLAUDE.md / skills instead.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Read JSON input from stdin synchronously.
+ */
+function readInput() {
+  try {
+    const data = fs.readFileSync(0, 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Check if a directory (or ancestor) has a .gitnexus index.
+ */
+function findGitNexusIndex(startDir) {
+  let dir = startDir || process.cwd();
+  for (let i = 0; i < 5; i++) {
+    if (fs.existsSync(path.join(dir, '.gitnexus'))) {
+      return true;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+/**
+ * Extract search pattern from tool input.
+ */
+function extractPattern(toolName, toolInput) {
+  if (toolName === 'Grep') {
+    return toolInput.pattern || null;
+  }
+
+  if (toolName === 'Glob') {
+    const raw = toolInput.pattern || '';
+    const match = raw.match(/[*\/]([a-zA-Z][a-zA-Z0-9_-]{2,})/);
+    return match ? match[1] : null;
+  }
+
+  if (toolName === 'Bash') {
+    const cmd = toolInput.command || '';
+    if (!/\brg\b|\bgrep\b/.test(cmd)) return null;
+
+    const tokens = cmd.split(/\s+/);
+    let foundCmd = false;
+    let skipNext = false;
+    const flagsWithValues = new Set(['-e', '-f', '-m', '-A', '-B', '-C', '-g', '--glob', '-t', '--type', '--include', '--exclude']);
+
+    for (const token of tokens) {
+      if (skipNext) { skipNext = false; continue; }
+      if (!foundCmd) {
+        if (/\brg$|\bgrep$/.test(token)) foundCmd = true;
+        continue;
+      }
+      if (token.startsWith('-')) {
+        if (flagsWithValues.has(token)) skipNext = true;
+        continue;
+      }
+      const cleaned = token.replace(/['"]/g, '');
+      return cleaned.length >= 3 ? cleaned : null;
+    }
+    return null;
+  }
+
+  return null;
+}
+
+function main() {
+  try {
+    const input = readInput();
+    const hookEvent = input.hook_event_name || '';
+
+    if (hookEvent !== 'PreToolUse') return;
+
+    const cwd = input.cwd || process.cwd();
+    if (!findGitNexusIndex(cwd)) return;
+
+    const toolName = input.tool_name || '';
+    const toolInput = input.tool_input || {};
+
+    if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Bash') return;
+
+    const pattern = extractPattern(toolName, toolInput);
+    if (!pattern || pattern.length < 3) return;
+
+    // Resolve CLI path relative to this hook script (same package)
+    // hooks/claude/gitnexus-hook.cjs → dist/cli/index.js
+    // augment CLI writes result to stderr (KuzuDB's native module captures
+    // stdout fd at OS level, making it unusable in subprocess contexts).
+    const { spawnSync } = require('child_process');
+    let result = '';
+    try {
+      const child = spawnSync(
+        'gitnexus',
+        ['augment', pattern],
+        { encoding: 'utf-8', timeout: 8000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      result = child.stderr || '';
+    } catch { /* graceful failure */ }
+
+    if (result && result.trim()) {
+      console.log(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext: result.trim()
+        }
+      }));
+    }
+  } catch (err) {
+    // Graceful failure — log to stderr for debugging
+    console.error('GitNexus hook error:', err.message);
+  }
+}
+
+main();