code-aura

CodeAura v3.1.0

Developer velocity engine. Hybrid BM25 + semantic code search with parent-document retrieval, parallel indexing, and AI-powered explanations.

Install

npm install -g codeaura

Or try without installing:

npx codeaura@latest setup ./your-project

Quick Start

# 1. First-time setup wizard
codeaura init

# 2. Or go directly
codeaura setup ./your-project
codeaura search "authentication middleware"

Commands

Command	Description
codeaura init	Interactive first-time setup wizard
codeaura setup <path>	Index a codebase (incremental)
codeaura setup <path> -f	Force full re-index
codeaura search "query"	Hybrid BM25 + semantic search
codeaura chat	AI conversation grounded in your code
codeaura serve	Start chart dashboard at localhost:3000
codeaura watch <path>	Hot-reload indexing on file changes
codeaura diff <path>	Preview what would be re-indexed
codeaura stats	Codebase analytics (language breakdown, file count)
codeaura explain <file>	AI explanation of any file
codeaura export "query" -f html	Export results as HTML with charts
codeaura doctor	System health check
codeaura clear	Clear index cache / chat history / API key
codeaura api-key	Manage GROQ API key

Search flags

codeaura search "query" --top 10        # return top 10
codeaura search "query" --no-rerank     # skip LLM re-ranking (faster)
codeaura search "query" --no-expand     # skip query expansion (faster)
codeaura search "query" --page 1        # pagination
codeaura search "query" -f markdown     # auto-export as markdown

Configuration

Create a .env file in the directory where you run codeaura:

# Required for AI features
GROQ_API_KEY=gsk_...

# Optional — real embeddings (falls back to local if not set)
HUGGINGFACE_API_KEY=hf_...

# Optional tuning
FILE_CONCURRENCY=8
PARENT_CHUNK_SIZE=1200
CHILD_CHUNK_SIZE=350

See .env.example for all options.

How it works

Indexing

• Scans your codebase with fast-glob (3-5× faster than readdir)
• MD5 hashes every file — only changed files are re-indexed
• Splits files into parent blocks (1200 chars) and child chunks (350 chars)
• Embeds child chunks via HuggingFace API (batched, 24 per call) or local fallback
• Stores in ChromaDB with full metadata (functions, classes, routes, imports)

Search

• Expands your query using an LLM for better recall
• Runs cosine similarity against all child chunk embeddings
• Runs BM25 keyword scoring on the same candidate set
• Fuses both rankings with Reciprocal Rank Fusion (RRF)
• Returns the parent block (full context) for each matched child
• Optional LLM re-ranker for final ordering

Requirements

• Node.js >= 18
• ChromaDB (optional — falls back to in-memory if not running)
• GROQ API key (free at console.groq.com)

Local Development

git clone https://github.com/harjas-romana/codeAura
cd codeAura/cleaned
chmod +x run.sh
./run.sh              # install + link + smoke test
./run.sh publish      # dry-run + publish to npm
./run.sh clean        # remove node_modules + cache

License

MIT — built by Harjas Singh