cortexhawk 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to CortexHawk are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/)
 
+## [3.1.1] - 2026-02-15
+
+### Fixed
+- `branch-guard` / `commit-guard` hooks: JSON parsing via `jq` with regex fallback — fixes false "hook error" on commands containing quotes or HEREDOC
+- `commit-guard`: multi-format commit message extraction (HEREDOC, single/double quotes)
+- `file-guard`: match on basename only — `*secret*`/`*credentials*` no longer false-positive on legitimate files (e.g., `oauth_service.py`); `.env.example`/`.env.sample`/`.env.template` whitelisted; `docker-compose*.yml` unblocked
+
 ## [3.1.0] - 2026-02-14
 
 ### Added
@@ -11,6 +18,9 @@ Format: [Keep a Changelog](https://keepachangelog.com/)
 - `--target auto`: auto-detects installed CLIs (claude, kimi, codex) and installs for all found — no need to specify which CLIs are available
 - `cortexhawk validate [path]`: post-install diagnostic that verifies skills/agents/commands/hooks discovery per target — checks manifest, file counts, settings.json validity, .gitignore coverage
 - npm distribution: `npm install -g cortexhawk` installs the CLI globally — auto-resolves `CORTEXHAWK_HOME` from symlinked binary, `self-update` detects npm install and suggests `npm update -g`
+- `/pulse --unused`: detects installed skills that don't match the project's tech stack — scans for technology markers, maps framework skills to stacks, reports potentially unused skills
+- `/chain --browse`: lists all available chain presets (built-in + custom from `.cortexhawk-chains.yml`) and recent chain runs from `docs/chains/`
+- `cortexhawk sync [path] [from]`: syncs modified skills across installed CLI targets — compares checksums, copies changed skills, skips generated content (cmd-*, hook-*, agent-*)
 
 ## [3.0.0] - 2026-02-14
 

package/README.md

@@ -2,7 +2,8 @@
 
 [![GitHub stars](https://img.shields.io/github/stars/Spechawk94/CortexHawk?style=flat-square)](https://github.com/Spechawk94/CortexHawk/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.0.0-green.svg?style=flat-square)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.1.0-green.svg?style=flat-square)](CHANGELOG.md)
+[![npm](https://img.shields.io/npm/v/cortexhawk?style=flat-square&color=red)](https://www.npmjs.com/package/cortexhawk)
 [![Skills](https://img.shields.io/badge/skills-36%20built--in%20%7C%2087k%2B%20via%20SkillsMP-orange.svg?style=flat-square)](https://skillsmp.com)
 [![Components](https://img.shields.io/badge/20%20agents%20%7C%2032%20commands%20%7C%209%20hooks%20%7C%207%20modes-purple.svg?style=flat-square)](#whats-inside)
 
@@ -10,19 +11,28 @@ An open-source, community-driven development toolkit for Claude Code.
 
 CortexHawk provides a modular collection of optimized agents, skills, commands, hooks, and behavioral modes that transform Claude Code into a full-stack development team. Every prompt has been written for maximum efficiency — less token bloat, sharper instructions, better agent coordination.
 
-### What's New in v3.0
+### What's New in v3.1
+
+- **`npm install -g cortexhawk`** — available on npm, auto-resolves source from symlinked binary
+- **`cortexhawk` CLI wrapper** — clean subcommands (init, install, update, doctor, validate, search, snapshot, etc.) instead of `bash install.sh --flags`
+- **`--target auto`** — auto-detects installed CLIs (claude, kimi, codex) and installs for all found
+- **`cortexhawk validate`** — post-install diagnostic verifying skills/agents discovery per target
+
+<details>
+<summary>v3.0 changes</summary>
 
 - **`--init` wizard overhaul** — reordered flow with git workflow config, auto `git init` + `.gitignore` creation, branching strategies (direct-main, dev-branch, git-flow)
 - **`/bootstrap --smart`** — researcher agent scans roadmap, compares stacks, recommends, then scaffolds
 - **Post-install gitignore** — auto-adds `.claude/`, `.kimi/`, `.codex/` to `.gitignore`, asks about `docs/`
 - **`--update` checksum detection** — compares file checksums instead of just version numbers to detect changes
 - **Kimi CLI overhaul** — agents, commands, hooks all converted to skills; AGENTS.md at project root; MCP optional; auto `.envrc` for local install
-- **Codex CLI fixes** — config.toml format fixes (flat model key, save-all persistence)
 - **`--demo` flag** — sandbox project in `/tmp/` with intentional bugs for testing
 - **`/upgrade` command** — check for updates, show changelog diff, propose `--update`
 - **`--publish-skill`** — publish local skills to GitHub with auto-generated README
 - **Cursor CLI removed** — too unstable for maintained support
 
+</details>
+
 ## Quick Start
 
 ```bash

package/commands/chain.md

@@ -11,7 +11,7 @@ Execute a declared sequence of agents with automatic context passing. Topic: `$A
 
 **Custom presets**: Define in `.cortexhawk-chains.yml` at project root — custom presets override built-in presets with the same name
 
-**Flags**: `--gate` = pause between steps | `--copy` = physical copy to plans/ | `--replay <slug>` = re-run a previous chain
+**Flags**: `--gate` = pause between steps | `--copy` = physical copy to plans/ | `--replay <slug>` = re-run a previous chain | `--browse` = list all available presets + recent chains
 
 **Mapping**: plan=planner, build=implementer, test=tester, review=reviewer, scan=security-auditor, debug=debugger, doc=docs-manager, ship=git-manager, refactor=code-simplifier, research=researcher
 
@@ -38,6 +38,15 @@ When detected in a step's output:
 2. Save as `{N}a-{delegated-agent}.md` (sub-step)
 3. Feed original output + delegation result to the next step
 
+## Browse mode (`--browse`)
+
+List all available chains from 3 sources:
+1. **Built-in presets** — default, security, ship (table: name, sequence, description)
+2. **Custom presets** — read `.cortexhawk-chains.yml` if present (table: name, sequence, description, gate)
+3. **Recent chains** — scan `docs/chains/*/SUMMARY.md`, extract date/slug/sequence/result (table: date, slug, sequence, status — last 10)
+
+Output all 3 tables. End with usage hint: `/chain <preset> <topic>`
+
 ## Rules
 
 - Max 8 agents per chain (delegations count toward this limit)

package/commands/pulse.md

@@ -7,7 +7,7 @@ description: Project health dashboard — code quality metrics at a glance.
 
 Activate the **project-manager** agent in health-check mode. Scope: `$ARGUMENTS`
 
-**Flags**: `--history Nd` = show metrics trends over N days (e.g., `--history 7d`, `--history 30d`)
+**Flags**: `--history Nd` = show metrics trends over N days | `--unused` = detect potentially unused skills
 
 ## Standard mode (no flag)
 
@@ -44,3 +44,13 @@ Avg: [tokens/day] tokens/day, [duration] min/session
 ```
 
 If scope is specified, limit checks to those files/directories.
+
+## Unused skills mode (`--unused`)
+
+Detect installed skills that don't match the project's tech stack.
+
+1. **List installed skills** from `.claude/skills/` (or target equivalent)
+2. **Detect stack** — scan for: `package.json`/`*.ts` → js/ts, `requirements.txt`/`*.py` → python, `go.mod` → go, `Cargo.toml` → rust, `Dockerfile` → docker, `*.svelte` → svelte, `next.config.*` → nextjs, `tailwind.config.*` → tailwind
+3. **Map framework skills** — `frameworks/react` → js, `frameworks/nextjs` → nextjs, `frameworks/sveltekit` → svelte, `frameworks/fastapi` → python, `frameworks/python` → python, `frameworks/typescript` → ts, `frameworks/tailwindcss` → tailwind, `devops/docker` → docker
+4. **Universal skills** (security/\*, quality/\*, testing/\*, meta/\*, databases/\*, workflow/\*, optimization/\*) → always relevant, skip
+5. **Output** — table with skill, required stack, OK/UNUSED status. Count unused. Suggest `cortexhawk install --profile autodetect`

package/cortexhawk

@@ -250,6 +250,91 @@ do_validate() {
     fi
 }
 
+# --- sync command ---
+do_sync() {
+    local project_root="${1:-.}"
+    local from_target="${2:-}"
+
+    # Detect installed targets
+    local targets=()
+    [ -f "$project_root/.claude/.cortexhawk-manifest" ] && targets+=("claude")
+    [ -f "$project_root/.kimi/.cortexhawk-manifest" ] && targets+=("kimi")
+    [ -f "$project_root/.codex/.cortexhawk-manifest" ] && targets+=("codex")
+
+    if [ "${#targets[@]}" -lt 2 ]; then
+        yellow "Sync requires at least 2 targets installed. Found: ${targets[*]:-none}"
+        exit 1
+    fi
+
+    # Determine source target
+    if [ -z "$from_target" ]; then
+        from_target="${targets[0]}"
+    fi
+
+    # Map target to skills directory
+    target_skills_dir() {
+        case "$1" in
+            claude) echo "$project_root/.claude/skills" ;;
+            kimi)   echo "$project_root/.kimi/skills" ;;
+            codex)  echo "$project_root/.agents/skills" ;;
+        esac
+    }
+
+    local src_dir
+    src_dir=$(target_skills_dir "$from_target")
+    if [ ! -d "$src_dir" ]; then
+        red "Source skills dir not found: $src_dir"
+        exit 1
+    fi
+
+    echo "CortexHawk Sync"
+    echo "==============="
+    echo "  Source: $from_target ($src_dir)"
+    echo "  Targets: ${targets[*]}"
+    echo ""
+
+    local synced=0
+    for target in "${targets[@]}"; do
+        [ "$target" = "$from_target" ] && continue
+        local dst_dir
+        dst_dir=$(target_skills_dir "$target")
+        [ ! -d "$dst_dir" ] && continue
+
+        # Sync each skill category/name
+        for skill_file in "$src_dir"/*/SKILL.md "$src_dir"/*/*/SKILL.md; do
+            [ ! -f "$skill_file" ] && continue
+            local rel_path="${skill_file#"$src_dir/"}"
+            local dst_file="$dst_dir/$rel_path"
+
+            # Skip generated skills (cmd-*, hook-*, agent-*, modes/)
+            case "$rel_path" in
+                cmd-*|hook-*|agent-*|modes/*) continue ;;
+            esac
+
+            # Compare checksums
+            if [ -f "$dst_file" ]; then
+                local src_md5 dst_md5
+                src_md5=$(md5sum "$skill_file" 2>/dev/null | cut -d' ' -f1)
+                dst_md5=$(md5sum "$dst_file" 2>/dev/null | cut -d' ' -f1)
+                [ "$src_md5" = "$dst_md5" ] && continue
+            fi
+
+            # Copy
+            mkdir -p "$(dirname "$dst_file")"
+            cp "$skill_file" "$dst_file"
+            echo "  [SYNC] $rel_path → $target"
+            synced=$((synced + 1))
+        done
+    done
+
+    echo ""
+    if [ "$synced" -eq 0 ]; then
+        green "All targets already in sync."
+    else
+        green "Synced $synced file(s)."
+    fi
+}
+
 # Verify CortexHawk source exists
 check_home() {
     if [ ! -f "$INSTALL_SH" ]; then
@@ -276,6 +361,7 @@ show_help() {
     echo ""
     echo "Diagnostics:"
     echo "  validate [path]     Verify skills/agents discovery per target"
+    echo "  sync [path] [from]  Sync skills across installed CLI targets"
     echo "  doctor              Check installation health"
     echo "  stats               Show installation overview"
     echo "  quickstart          Getting-started guide"
@@ -336,6 +422,10 @@ case "$cmd" in
         shift
         do_validate "$@"
         ;;
+    sync)
+        shift
+        do_sync "$@"
+        ;;
     doctor)
         check_home
         shift

package/hooks/branch-guard.sh

@@ -7,7 +7,12 @@ if [ -n "$CORTEXHAWK_COMMAND" ]; then
   CMD="$CORTEXHAWK_COMMAND"
 else
   INPUT=$(cat)
-  CMD=$(printf '%s' "$INPUT" | grep -o '"command" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+  if command -v jq &>/dev/null; then
+    CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+  fi
+  if [[ -z "$CMD" ]]; then
+    CMD=$(printf '%s' "$INPUT" | grep -o '"command" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+  fi
 fi
 
 if [[ -z "$CMD" ]]; then

package/hooks/commit-guard.sh

@@ -7,7 +7,12 @@ if [ -n "$CORTEXHAWK_COMMAND" ]; then
   CMD="$CORTEXHAWK_COMMAND"
 else
   INPUT=$(cat)
-  CMD=$(printf '%s' "$INPUT" | grep -o '"command" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+  if command -v jq &>/dev/null; then
+    CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+  fi
+  if [[ -z "$CMD" ]]; then
+    CMD=$(printf '%s' "$INPUT" | grep -o '"command" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+  fi
 fi
 
 if [[ -z "$CMD" ]]; then
@@ -20,9 +25,17 @@ if ! echo "$CMD" | grep -qE 'git\s+commit'; then
 fi
 
 # Extract commit message from -m flag
-COMMIT_MSG=$(echo "$CMD" | grep -oP '(?<=-m\s["\x27]).*?(?=["\x27])' 2>/dev/null)
+# Handle: -m "msg", -m 'msg', -m "$(cat <<'EOF'\nmsg\nEOF\n)"
+COMMIT_MSG=$(echo "$CMD" | sed -n 's/.*-m[[:space:]]*"\$(cat <<.*//p' 2>/dev/null)
+if [[ -n "$COMMIT_MSG" ]]; then
+  # HEREDOC style — extract first non-empty line after the heredoc opener
+  COMMIT_MSG=$(echo "$CMD" | sed -n '/cat <</{n;p;}' | sed 's/^[[:space:]]*//' 2>/dev/null)
+fi
+if [[ -z "$COMMIT_MSG" ]]; then
+  COMMIT_MSG=$(echo "$CMD" | grep -oP "(?<=-m\s[\"'])(.+?)(?=[\"'](\s|$))" 2>/dev/null | head -1)
+fi
 if [[ -z "$COMMIT_MSG" ]]; then
-  COMMIT_MSG=$(echo "$CMD" | grep -oP '(?<=-m\s)(\S+)' 2>/dev/null)
+  COMMIT_MSG=$(echo "$CMD" | grep -oP '(?<=-m\s)\S+' 2>/dev/null | head -1)
 fi
 
 # Load git workflow config — skip conventional check if freeform

package/hooks/file-guard.sh

@@ -2,20 +2,28 @@
 # file-guard — Blocks Claude from accessing sensitive files
 # Hook type: PreToolUse (Read|Edit|Write)
 
+# Patterns matched against BASENAME only
 BLOCKED_PATTERNS=(
   ".env"
-  ".env.*"
   "*.pem"
   "*.key"
-  "*credentials*"
-  "*secret*"
   "id_rsa"
   "id_ed25519"
-  ".ssh/*"
   "*.p12"
   "*.pfx"
   "*.keystore"
-  "docker-compose*.yml"
+  "credentials.json"
+  "credentials.yml"
+  "credentials.yaml"
+)
+
+# Basename patterns that are .env.* but NOT .env.example/.env.sample/.env.template
+BLOCKED_ENV_GLOB=".env.*"
+ALLOWED_ENV_NAMES=(".env.example" ".env.sample" ".env.template")
+
+# Path patterns — only match directory components
+BLOCKED_PATH_PATTERNS=(
+  ".ssh/"
 )
 
 # Read file_path from stdin JSON (Claude Code hook protocol)
@@ -42,10 +50,35 @@ BASENAME=$(basename "$RESOLVED")
 # Also check against the full resolved path
 RELPATH="$RESOLVED"
 
+# Check basename against exact patterns
 for pattern in "${BLOCKED_PATTERNS[@]}"; do
-  if [[ "$BASENAME" == $pattern ]] || [[ "$RELPATH" == *$pattern ]]; then
+  if [[ "$BASENAME" == $pattern ]]; then
+    echo "BLOCKED: Access to '$FILE_ARG' denied by file-guard" >&2
+    echo "Matched pattern: '$pattern'" >&2
+    exit 2
+  fi
+done
+
+# Check .env.* files (allow .env.example/.env.sample/.env.template)
+if [[ "$BASENAME" == $BLOCKED_ENV_GLOB ]]; then
+  ALLOWED=false
+  for name in "${ALLOWED_ENV_NAMES[@]}"; do
+    if [[ "$BASENAME" == "$name" ]]; then
+      ALLOWED=true
+      break
+    fi
+  done
+  if [[ "$ALLOWED" == false ]]; then
+    echo "BLOCKED: Access to '$FILE_ARG' denied by file-guard" >&2
+    echo "Matched pattern: '$BLOCKED_ENV_GLOB'" >&2
+    exit 2
+  fi
+fi
+
+# Check path patterns (directory components)
+for pattern in "${BLOCKED_PATH_PATTERNS[@]}"; do
+  if [[ "$RELPATH" == *"$pattern"* ]]; then
     echo "BLOCKED: Access to '$FILE_ARG' denied by file-guard" >&2
-    echo "Resolved path: $RESOLVED" >&2
     echo "Matched pattern: '$pattern'" >&2
     exit 2
   fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortexhawk",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Open-source development toolkit for Claude Code — optimized agents, skills, commands, hooks, and modes",
   "bin": {
     "cortexhawk": "./cortexhawk"