HSS-CE: Indexador de Codebase para Agentes IA
Phuong38/hss-ce
Contexto estruturado de codebase para agentes IA com 50%+ menos tokens
Ver no GitHubMCP server offline-first que indexa e mapeia estruturas de código usando análise semântica-estrutural (PageRank + AST), otimizando recuperação de contexto para agentes de IA com eficiência de tokens. Gera arquitetura interativa, tours de onboarding e expõe API estruturada para navegação precisa de símbolos.
Instalação
npx convez-ai Phuong38/hss-ce1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Onboarding em codebases complexas com tours automáticos e mapas interativos
- Redução de consumo de tokens em agentes IA (Claude Code, Cursor, Aider) via queries estruturadas
- Navegação precisa de símbolos e dependências sem grep ruidoso ou leitura de arquivos inteiros
Veredito

Ferramenta sólida e bem-pensada para quem trabalha com agentes IA em codebases grandes. O foco em eficiência de tokens e segurança (redação automática de secrets) é prático. Limitação real: suporte a linguagens varia (AST completo para JS/Python, regex para outras).
README
A tradução para o português deste README ainda está na fila.
HSS-CE: Hybrid Semantic-Structural Context Engine
HSS-CE is a lightweight, offline-first codebase indexer and Model Context Protocol (MCP) server. It optimizes how developers and AI coding agents explore, map, and interact with complex codebases.
By calculating file significance using a simplified reference-count PageRank and parsing code structures (classes, functions, endpoints) using AST-aware parsing for Python and high-performance parser/regex engines for other languages, HSS-CE provides high-density context without wasting your token budget.
Honest Value Proposition: Why Use HSS-CE?
HSS-CE is not a magical AI assistant that writes code for you. It is a structured context provider that acts as a bridge between your codebase's architecture, yourself, and your AI tools.
1. For Developers (Onboarding & Navigation)
- Interactive Architecture Map: Generates a lightweight, dark-mode interactive HTML diagram (
architecture.html). You can visually search files, see directory-grouped modules, and click nodes to highlight immediate dependencies or see local symbols. - Onboarding Tours: Generates step-by-step markdown walkthroughs (
hss-ce tour) that order your codebase from critical entrypoints down to services and storage layers. This helps you understand a new codebase in minutes. - 100% Offline Summaries: Automatically extracts plain-English JSDoc, block comments, and Python docstrings to construct a codebase overview database, requiring zero API keys, network requests, or costs.
2. For AI Coding Agents (Context Optimization)
- Eliminate Token Waste: Coding agents (like Claude Code, Cursor, Aider) often read entire files or directory trees to understand import flows. HSS-CE exposes an MCP server that lets agents query precise skeletal structures and dependency trees under strict token budgets.
- Precise Symbol Navigation: Instead of performing noisy text searches (like raw
greporripgrep), agents use structured database queries to resolve exact function definitions and caller locations. - Automated Redaction (Secret Guard): Before packing codebase files to send to LLM context, HSS-CE automatically redacts credentials, private keys, and API tokens, preventing security leaks.
- Git-Aware Ignore System: Automatically respects
.gitignorerules in addition to local.hssceignorepatterns, ensuring build artifacts, dependencies, and temporary files are excluded from the index. - Cache-Aligned Context Packing: Re-orders context packs to place stable components (skeleton maps, system stats) at the beginning of the prompt and dynamic content (active files) at the very end. This maximizes LLM provider KV caching hits, saving up to 50%+ on prompt cost and latency.
- Smart JSON Compaction: Automatically minifies and compacts configuration files (like
package.jsondevDependencies) to strip noise and reduce token consumption. - Lazy Content Retrieval (CCR): Exposes a
read_file_contentMCP tool so agents can receive lightweight codebase skeletons first and load full contents dynamically on-demand, enabling lossless token efficiency.
3. Current Limitations & What It is Not
- Hybrid AST-Regex Parsing Engine: HSS-CE uses high-performance syntax parsers (Babel for JS/TS, Python AST module for Python) to resolve symbols, imports, and metadata accurately. For unsupported languages, it falls back to lightweight regex-based heuristic parsing. This balances parser speed, accuracy, and extensibility.
- Dependency on Code Quality: Local file summaries are parsed from comments/docstrings. If your codebase has zero comments, the summaries will be empty unless you explicitly run the remote LLM enrichment command (
hss-ce enrich).
Developer & Agent Workflows in Action
A. How a Developer Uses HSS-CE
Imagine you need to modify a database schema file src/db.js in a large codebase, but you don't know what might break.
- Open the generated
architecture.htmldashboard in your browser. - Search for
db.js. - Click the
db.jsnode. The graph automatically dims unrelated elements and highlights all service files that directly import it. - Read the symbols and summaries in the details panel to understand exactly what functions interact with the database.
B. How an AI Agent Uses HSS-CE (Under the Hood)
When you ask your agent (e.g. Claude Code or Cursor): "Find all callers of the authenticate function and tell me where it is defined", the agent bypasses slow search loops and makes a fast MCP tool call:
- Agent invokes
get_definition(symbol: "authenticate")→ HSS-CE queries SQLite and returns the exact file path and signature. - Agent invokes
get_callers(symbol: "authenticate")→ HSS-CE returns a clean list of files and lines referencing the function. - Agent invokes
get_dependency_path(fromFile: "src/main.js", toFile: "src/db.js")→ HSS-CE traces and lists the step-by-step import path between files. - Agent invokes
search_symbols(query: "auth")→ HSS-CE fuzzy matches against indexed symbols and returns definition details. - Agent invokes
search_code(query: "TODO: fix", isRegex: false)→ HSS-CE performs a lightning-fast SQLite FTS5 index search, ranking results by BM25 relevance and PageRank structural importance. - Agent invokes
check_index_drift()→ HSS-CE returns drift status to verify if index matches files on disk. - Agent invokes
get_change_impact(target: "src/db.js", depth: 3)→ HSS-CE recursively traces upstream imports to assess blast radius before modifying any code. - The agent reads only those specific files, completing the task with 90% fewer tokens and much higher accuracy.
Quick Start: Set Up a New Project (Single-Command Setup)
HSS-CE is designed to be set up on any target codebase with a single installation step.
1. Prerequisite
Ensure you have Node.js (v18+) and Git installed on your system.
2. Install and Configure
Option A: Run via NPX (Recommended - No Install Needed)
Run the configuration wizard directly without global installation issues:
npx --package hss-ce hss-ce-integrate
Option B: Install via NPM (Global)
Install globally to make the commands permanent:
npm install -g hss-ce
Note: On macOS/Linux, if you encounter EACCES permission errors, either run with sudo npm install -g hss-ce or use a Node manager like nvm.
Once installed, move into your target project directory and initialize it:
hss-ce-integrate
Option C: Install from Source (Git Clone)
If you prefer to clone and install the source code manually:
git clone https://github.com/phuonglt/hss-ce.git
cd hss-ce
bash install.sh
3. What the Installer Does Automatically
Once launched, the script will:
- Install all required dependencies.
- Register the global CLI commands (
hss-ceandhss-ce-integrate). - Launch the setup wizard to ask for the path of your target codebase.
- Auto-Index: Analyze your target codebase, calculate PageRank structural weights, and build the SQLite database (
.hss-ce/graph.db). - Auto-Doc: Generate a
CODEBASE.mdmarkdown map and an interactivearchitecture.htmldashboard in your target project directory. - Auto-Agent Setup: Write context instructions and rules (
.cursorrules,CLAUDE.md,.aider.instructions.md,.agents/rules/hss-ce.md) so your AI agents immediately know how to use HSS-CE. - Agent MCP Integration: Prompt you to automatically add HSS-CE to your favorite coding client (Claude Desktop, Cursor, Claude Code, Aider, or Antigravity).
- Git Hooks Setup: Installs background Git hooks (
post-checkoutandpost-merge) in your target repository to automatically trigger fast codebase indexing in the background whenever you switch branches or merge updates, keeping your database perfectly synced with your current branch.
CLI Reference Guide
If you prefer using the terminal manually, HSS-CE provides the following commands:
| Command | Usage | Description |
|---|---|---|
hss-ce index <path> | hss-ce index . | Scan codebase structure and build local index. Add -f to force re-scan. |
hss-ce watch <path> | hss-ce watch . | Monitor codebase files and sync index in real-time. Add --debounce=300 to set delay in ms. |
hss-ce map <path> | hss-ce map . --compact | Print PageRank-ordered file structure. Add --budget=1000 to limit tokens. |
hss-ce doc <path> | hss-ce doc . | Regenerate CODEBASE.md and architecture.html dashboard. |
hss-ce tour <path> | hss-ce tour . | Display a step-by-step onboarding walkthrough tour of the codebase. |
hss-ce query <path> <sym> | hss-ce query . validateUser | Instantly lookup definition and callers for a specific symbol. |
hss-ce path <path> <from> <to> | hss-ce path . src/cli.js src/db.js | Find directed dependency/import path chain from one file to another. |
hss-ce search <path> <query> | hss-ce search . auth | Fuzzy search symbol names matching query pattern. |
hss-ce search-code <path> <q> | hss-ce search-code . TODO --regex | Search text snippet/regex across indexed files. Add --regex for regex pattern. |
hss-ce pack <path> | hss-ce pack . --budget=2000 --format=markdown --progressive --sort=path | Package source/config/docs files into structured XML/Markdown for LLM context, with secret redacting. Supports progressive fallback compression to skeletons and deterministic sorting. |
hss-ce enrich <path> | hss-ce enrich . | (Optional) Fetch AI-generated summaries via Gemini API (requires GEMINI_API_KEY). |
hss-ce status <path> | hss-ce status . | Check if index has drifted from the local files on disk (modified/missing/untracked files). |
hss-ce impact <path> <target> | hss-ce impact . src/db.js | Trace recursive change impact blast radius (importers) for a file or symbol. Add --depth=N flag to set max traversal depth (default 5). |
HSS-CE vs. 2026 Context & Agent Landscapes
As of mid-2026, the AI agent ecosystem has evolved significantly. Below is a comparative analysis of HSS-CE against leading context and agent frameworks, along with our roadmap inspired by their architectures:
1. Comparative Analysis
| Feature | HSS-CE | Headroom (chopratejas/headroom) | CodeGraph (colbymchenry/codegraph) | Claude-Context (zilliztech/claude-context) |
|---|---|---|---|---|
| Parsing Engine | Hybrid (AST-aware for JS/TS & Python, regex fallback) | AST-aware (Languages-specific) | Tree-sitter AST (High accuracy) | AST-aware chunking |
| Search Method | SQLite FTS5 (Local keyword/BM25) | Heuristic compression & retrieval | SQLite query/Call-graph lookup | Semantic vector search (Milvus) |
| Context Compression | PageRank elision & Skeleton mode | SmartCrusher (JSON), CodeCompressor | Signature elision | Embedding-based filtering |
| Sync Mechanism | Git hooks / CLI commands | Filesystem events / Proxy | Native FS watchers | Merkle trees |
| Deployment | 100% Offline (Local CLI/MCP) | Proxy / MCP server | 100% Offline (Local MCP) | Hybrid/Cloud (Requires DB & Key) |
2. Key Architectural Lessons
- Tree-sitter AST Parsing: CodeGraph demonstrates that transitioning from regex parsing to Tree-sitter AST parsing significantly improves symbol resolution accuracy and cross-file import tracking, particularly for complex JS/TS/Python syntax.
- Context-Compressed Retrieval (CCR) & KV Caching: Headroom's prefix alignment and JSON
SmartCrushershow that optimization of LLM prompt caches is a critical factor in latency and cost reduction. - Semantic Local Search: Claude-Context's use of embeddings highlights the value of semantic search, which HSS-CE can adopt locally via lightweight libraries like
sqlite-vssto avoid external API calls.
3. HSS-CE Future Roadmap & Implementation Plan
-
Phase 1: AST-Aware Parsing (Completed for Python; Broader Tree-sitter Planned)
- Goal: Integrate AST parsers (Node.js Babel for JS/TS, python3
astmodule for Python) to resolve signatures, imports, inheritance, and decorator routes. - Testing: Verified with
tests/python_ast.test.jsand existing tests.
- Goal: Integrate AST parsers (Node.js Babel for JS/TS, python3
-
Phase 2: KV-Cache prefix alignment
- Goal: Implement deterministic prompt formatting to lock stable context chunks (e.g. system instructions, skeleton structures) at the beginning of prompt outputs.
-
Phase 3: Real-Time Sync Watcher (Completed)
- Goal: Add a local file watcher using
chokidarto automatically sync SQLite.hss-ce/graph.dbon file change events.
- Goal: Add a local file watcher using
Inspirations & Credits
HSS-CE draws inspiration and features from several exceptional open-source tools:
- Repomix / GitIngest: Inspires our XML context packaging and budget-bounded file packing with token calculations.
- Aider: Inspires our signature-only codebase skeleton mapping and token-budgeted structure elision.
- Graphify / CodeGraph: Inspires our structural codebase graph modeling, import tracking, and PageRank scoring.
- CodeCTX: Inspires our personalized context boost around user active files.
- Understand-Anything: Inspires our logical layering (entrypoint/service/storage), interactive visual dashboard highlighting, and guided onboarding tours.
- RTK (Rust Token Killer) & Headroom: Inspires our prompt cache KV-alignment, JSON compaction, and Content-Compressed Retrieval (CCR) strategies.
License
Licensed under the MIT License.