⚡ Quick Start

# Via nock-cli (recommended)
npm install -g @nockdev/cli
nock awf hsa start

# Or run standalone via npx
npx -y @nockdev/hsa@latest

# Or install globally
npm install -g @nockdev/hsa
nock-hsa

✨ Features

| Feature | Description | |:--------|:------------| | 🔍 Hybrid Search | BM25+ full-text + CodeGraph + HNSW vector search with automatic query expansion | | 🏆 Relevance Reranking | Multi-signal reranking (PageRank, recency, feedback) for search result quality | | 🧬 Knowledge Graph | Semantic edges between symbols — auto-built from imports, calls, and type relationships | | 🌳 Merkle Tree | O(log n) change detection — instant incremental re-indexing for large codebases | | 🎯 Context Compaction | Smart truncation strategies (simple, semantic, code-aware, skeleton, progressive, chunked) | | 💾 LRU Cache | Semantic caching with TTL + background revalidation | | 📚 Doc Fetcher | 84+ built-in library docs + llms.txt, npm README, local files, custom URLs | | 🔬 External Research | GitHub repo indexing, npm/PyPI package metadata, release notes, remote file reading | | 🔄 Cross-Model Cascade | Delegate tasks to Gemini, Claude, GPT models with dashboard-configurable routing | | 🎨 LiveCanvas | Visual feedback loop — dev server management, screenshots, visual regression, live CSS edits via CDP | | 🖌️ Design Intelligence | Design DNA extraction, WCAG health scoring (0-100), W3C DTCG token generation, image analysis | | 🌐 Browser Engine | Playwright-powered: screenshot, element inspection, page analysis | | 🧠 Session Governance | Intent declaration, drift detection, 3-level progress tracking, persistent anchors | | 🧬 Persistent Memory | Cross-session episodic memory with semantic recall — store decisions, patterns, errors | | 💥 Impact Analysis | Blast radius scoring with BFS dependency traversal, test coverage gap detection | | 📊 Web Dashboard | Real-time 3-tab SPA (Dashboard · Graph · Logs) at localhost:13100 | | 📋 Activity Ledger | Tool call tracking, latency measurement, per-tool usage statistics | | 📲 Notifications | Telegram Bot + Discord Webhook for session persistence and task completion alerts | | 🔒 Integrity | SHA-256 tamper detection across all 490+ bundled files | | 🖥️ Daemon Mode | Background process with HTTP transport + OAuth 2.1 |

🛠️ MCP Tools (16)

Core Analysis

| Tool | Actions | Description | |:-----|:--------|:------------| | hsa_search | context files skills docs | Hybrid code search, file glob, skill patterns, external library docs | | hsa_explore | repo_map snapshot | PageRank-ranked file overview, project structure snapshot | | hsa_detect | stack environment | Detect tech stack, frameworks, runtimes, package managers | | hsa_check_changes | — | Check file changes via Merkle tree diff, re-index BM25/CodeGraph | | hsa_trace_flow | trace impact | Trace code execution flow + blast radius analysis (scoring, test gaps) | | hsa_prefetch | — | Pre-load files/library docs into cache for faster retrieval | | hsa_feedback | — | Record file usefulness — improves future search ranking |

Session & Governance

| Tool | Actions | Description | |:-----|:--------|:------------| | hsa_session | persist track anchor drift intent | Session governance: context snapshots, progress tracking, drift detection | | hsa_memory | store recall list delete stats | Persistent cross-session episodic memory with semantic recall | | hsa_get_agent_config | bootstrap commands rules skills modules all | Load DOMYH agent configuration, rules, skills | | hsa_report | status export tasks | Engine health, cache stats, active task list | | hsa_delegate | prepare filter cascade cascade_read cascade_models cascade_cancel | Sub-agent delegation, cross-model cascade | | hsa_research | index overview read search list refresh delete pkg releases compare file | External repo research, package metadata, release notes, remote file reading | | hsa_guide | — | HSA optimal workflow guide |

Visual & Design

| Tool | Actions | Description | |:-----|:--------|:------------| | hsa_canvas | open capture diff update extract inspect close | LiveCanvas: dev server, screenshots, visual regression, live CSS edits | | hsa_design | analyze health tokens analyze_image | Design DNA extraction, WCAG health scoring, W3C DTCG tokens |

📚 Doc Fetcher — External Library Documentation

HSA can fetch, index, and search external library documentation. This powers the hsa_search(action: "docs") tool.

Supported Sources (Priority Order)

| Priority | Source | Example | |:---------|:-------|:--------| | 1 | llms.txt Registry (24 libraries) | nextjs, prisma, react | | 1.5 | Local docs folder ~/.nockdev/hsa/docs/{lib}.md | tailwindcss.md | | 2 | npm homepage probe /llms.txt | Auto-probed from npm registry | | 3 | npm README fallback | Packages with long READMEs | | — | Custom URL | Any https:// .md file | | — | Local file path | Any local .md, .txt, .mdx file |

Usage

# Search docs by library name (auto-resolves source)
hsa_search(action: "docs", query: "dark mode", doc_libraries: ["tailwindcss"])

# Search docs from a custom URL
hsa_search(action: "docs", query: "installation", doc_libraries: ["https://raw.githubusercontent.com/microsoft/playwright/main/README.md"])

# Search docs from a local file
hsa_search(action: "docs", query: "api reference", doc_libraries: ["/path/to/my-docs.md"])

# Prefetch library docs for faster search
hsa_prefetch(libs: ["nextjs", "prisma", "tailwindcss"])

Adding Custom Documentation

Place .md files in ~/.nockdev/hsa/docs/ named after the npm package:

# File name must match npm package name
~/.nockdev/hsa/docs/tailwindcss.md    # → hsa_search(docs, ["tailwindcss"])
~/.nockdev/hsa/docs/my-lib.md         # → hsa_search(docs, ["my-lib"])
~/.nockdev/hsa/docs/my-lib-docs.md    # → also matches "my-lib"

The file is automatically discovered when you search for that library name. No configuration needed.

Built-in Registry (84+ Libraries)

| Library | Source | |:--------|:-------| | Next.js | llms.txt | | React | llms.txt | | Svelte | llms.txt | | Vue.js | llms.txt | | Angular | llms.txt | | Nuxt | llms.txt | | Nuxt UI | llms.txt | | Astro | llms.txt | | Prisma | llms.txt | | Drizzle | llms.txt | | shadcn/ui | llms.txt | | Radix UI | llms.txt | | TanStack | llms.txt | | Vercel AI SDK | llms.txt | | Supabase | llms.txt | | Clerk | llms.txt | | Better Auth | llms.txt | | Stripe | llms.txt | | Resend | llms.txt | | Upstash | llms.txt | | Zustand | llms-full.txt | | Convex | llms.txt | | Sanity | llms.txt | | Mintlify | llms.txt | | Tailwind CSS | Local docs (bundled) |

️ Web Dashboard

nock awf hsa start    # Dashboard at http://localhost:13100/dashboard

| Page | Description | |:-----|:------------| | /dashboard | Real-time project stats, cache metrics, indexed skills | | /logs | Tool call history, search queries, performance traces | | /health | Health check endpoint for monitoring |

📋 Requirements

• Node.js ≥ 18.0.0

📄 License

MIT © NockDev