codexa 1.0.0 → 1.0.1

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
-  <h1>Codexa</h1>
-  
-  <img width="1536" height="1024" alt="Image" src="https://github.com/user-attachments/assets/9d347801-9e39-494b-8645-17c0804223e3" />
+  <h1>
+    <img src="https://github.com/sahitya-chandra/codexa/blob/main/.github/assets/logo.png" alt="Codexa Logo" width="90" align="absmiddle"> Codexa
+  </h1>
   
   <p>
     <strong>A powerful CLI tool that ingests your codebase and allows you to ask questions about it using Retrieval-Augmented Generation (RAG).</strong>
@@ -48,7 +48,7 @@
 
 - 🔒 **Privacy-First**: All data processing happens locally by default
 - ⚡ **Fast & Efficient**: Local embeddings and optimized vector search
-- 🤖 **Multiple LLM Support**: Works with Ollama (local) and Groq (cloud)
+- 🤖 **Multiple LLM Support**: Works with Groq (cloud)
 - 💾 **Local Storage**: SQLite database for embeddings and context
 - 🎯 **Smart Chunking**: Intelligent code splitting with configurable overlap
 - 🔄 **Session Management**: Maintain conversation context across queries
@@ -68,7 +68,6 @@ Before installing Codexa, ensure you have the following:
   node --version  # Should be v20.0.0 or higher
   ```
 
-- **For Local LLM (Ollama)**: [Ollama](https://ollama.com/) must be installed
 - **For Cloud LLM (Groq)**: A Groq API key from [console.groq.com](https://console.groq.com/)
 
 ### Installation Methods
@@ -130,11 +129,9 @@ codexa --version
 
 ### LLM Setup
 
-Codexa requires an LLM to generate answers. You can use either Groq (cloud - recommended) or Ollama (local). Groq is recommended for its speed and reliability.
-
-#### Option 1: Using Groq (Cloud - Recommended)
+Codexa requires an LLM to generate answers. You can use Groq (cloud).
 
-Groq provides fast cloud-based LLMs with a generous free tier and is the recommended option for most users.
+Groq provides fast cloud-based LLMs with a generous free tier.
 
 **Step 1: Get a Groq API Key**
 
@@ -192,69 +189,11 @@ Codexa defaults to using Groq when you run `codexa init`. If you need to manuall
 - `llama-3.1-8b-instant` - Fast responses (recommended, default)
 - `llama-3.1-70b-versatile` - Higher quality, slower
 
-#### Option 2: Using Ollama (Local - Alternative)
-
-Ollama runs LLMs locally on your machine, keeping your code completely private. This is an alternative option if you prefer local processing.
-
-> ⚠️ **Note:** Models with more than 3 billion parameters may not work reliably with local Ollama setup. We recommend using 3B parameter models for best compatibility, or use Groq (Option 1) for better reliability.
-
-**Step 1: Install Ollama**
-
-- **macOS/Linux**: Visit [ollama.com](https://ollama.com/) and follow the installation instructions
-- **Or use Homebrew on macOS**:
-  ```bash
-  brew install ollama
-  ```
-
-**Step 2: Start Ollama Service**
-
-```bash
-# Start Ollama (usually starts automatically after installation)
-ollama serve
-
-# Verify Ollama is running
-curl http://localhost:11434/api/tags
-```
-
-**Step 3: Download a Model**
-
-Pull a model that Codexa can use:
-
-```bash
-# Recommended: Fast and lightweight - 3B parameters
-ollama pull qwen2.5:3b-instruct
-
-# Alternative 3B options:
-ollama pull qwen2.5:1.5b-instruct    # Even faster, smaller
-ollama pull phi3:mini                # Microsoft Phi-3 Mini
-
-# ⚠️ Note: Larger models (8B+ like llama3:8b, mistral:7b) may not work locally
-# If you encounter issues, try using a 3B model instead, or switch to Groq
-```
 
-**Step 4: Verify Model is Available**
-
-```bash
-ollama list
-```
-
-You should see your downloaded model in the list.
-
-**Step 5: Configure Codexa**
-
-Edit `.codexarc.json` after running `codexa init`:
-
-```json
-{
-  "modelProvider": "local",
-  "model": "qwen2.5:3b-instruct",
-  "localModelUrl": "http://localhost:11434"
-}
-```
 
 #### Quick Setup Summary
 
-**For Groq (Recommended):**
+**For Groq:**
 ```bash
 # 1. Get API key from console.groq.com
 # 2. Set environment variable
@@ -266,22 +205,7 @@ codexa init
 # 4. Ready to use!
 ```
 
-**For Ollama (Alternative):**
-```bash
-# 1. Install Ollama
-brew install ollama  # macOS
-# or visit ollama.com for other platforms
-
-# 2. Start Ollama
-ollama serve
 
-# 3. Pull model (use 3B models only)
-ollama pull qwen2.5:3b-instruct
-
-# 4. Update .codexarc.json to set "modelProvider": "local"
-codexa init
-# Then edit .codexarc.json to set modelProvider to "local"
-```
 
 ## Quick Start
 
@@ -427,38 +351,22 @@ export OPENAI_API_KEY="sk-your_key_here"  # If using OpenAI embeddings
 
 #### `modelProvider`
 
-**Type:** `"local" | "groq"`  
-**Default:** `"groq"` (recommended)
+**Type:** `"groq"`  
+**Default:** `"groq"`
 
 The LLM provider to use for generating answers.
 
-- `"groq"` - Uses Groq's cloud API (recommended, requires `GROQ_API_KEY`)
-- `"local"` - Uses Ollama running on your machine (alternative option)
+- `"groq"` - Uses Groq's cloud API (requires `GROQ_API_KEY`)
 
 #### `model`
 
 **Type:** `string`  
-**Default:** `"llama-3.1-8b-instant"` (groq, recommended) or `"qwen2.5:3b-instruct"` (local)
+**Type:** `string`  
+**Default:** `"llama-3.1-8b-instant"`
 
 The model identifier to use.
 
-**Common Groq Models (Recommended):**
-- `llama-3.1-8b-instant` - Fast responses (default, recommended)
-- `llama-3.1-70b-versatile` - Higher quality, slower
-
-**Common Local Models (Alternative):**
-- `qwen2.5:3b-instruct` - Fast, lightweight - **3B parameters**
-- `qwen2.5:1.5b-instruct` - Even faster, smaller - **1.5B parameters**
-- `phi3:mini` - Microsoft Phi-3 Mini - **3.8B parameters**
 
-> ⚠️ **Warning:** Models with more than 3 billion parameters (like `llama3:8b`, `mistral:7b`) may not work reliably with local Ollama setup. If you encounter issues, please try using a 3B parameter model instead, or switch to Groq.
-
-#### `localModelUrl`
-
-**Type:** `string`  
-**Default:** `"http://localhost:11434"`
-
-Base URL for your local Ollama instance. Change this if Ollama runs on a different host or port.
 
 #### `embeddingProvider`
 
@@ -562,7 +470,7 @@ Number of code chunks to retrieve and use as context for each question. Higher v
 
 ### Example Configurations
 
-#### Groq Cloud Provider (Recommended - Default)
+#### Groq Cloud Provider (Default)
 
 ```json
 {
@@ -582,28 +490,14 @@ Number of code chunks to retrieve and use as context for each question. Higher v
 export GROQ_API_KEY="your-api-key"
 ```
 
-#### Local Development (Alternative)
 
-```json
-{
-  "modelProvider": "local",
-  "model": "qwen2.5:3b-instruct",
-  "localModelUrl": "http://localhost:11434",
-  "embeddingProvider": "local",
-  "embeddingModel": "Xenova/all-MiniLM-L6-v2",
-  "maxChunkSize": 200,
-  "chunkOverlap": 20,
-  "temperature": 0.2,
-  "topK": 4
-}
-```
 
 #### Optimized for Large Codebases
 
 ```json
 {
-  "modelProvider": "local",
-  "model": "qwen2.5:3b-instruct",
+  "modelProvider": "groq",
+  "model": "llama-3.1-8b-instant",
   "maxChunkSize": 150,
   "chunkOverlap": 15,
   "topK": 6,
@@ -731,8 +625,8 @@ When you run `codexa ask`:
                                ▼
 ┌─────────────────┐     ┌──────────────┐
 │   SQLite DB     │◀────│   LLM        │
-│   (Chunks +     │     │   (Ollama/   │
-│   Embeddings)   │     │    Groq)     │
+│   (Chunks +     │     │   (Groq)     │
+│   Embeddings)   │     │              │
 └─────────────────┘     └──────┬───────┘
                                │
                                ▼
@@ -745,50 +639,12 @@ When you run `codexa ask`:
 - **Chunker**: Splits code files into semantic chunks
 - **Embedder**: Generates vector embeddings (local transformers)
 - **Retriever**: Finds relevant chunks using vector similarity
-- **LLM Client**: Generates answers (Ollama local or Groq cloud)
+- **LLM Client**: Generates answers (Groq cloud)
 - **Database**: SQLite for storing chunks and embeddings
 
 ## Troubleshooting
 
-### "Ollama not reachable" Error
-
-**Problem:** Codexa can't connect to your local Ollama instance.
-
-**Solutions:**
-1. Ensure Ollama is running:
-   ```bash
-   ollama serve
-   ```
-2. Check if Ollama is running on the default port:
-   ```bash
-   curl http://localhost:11434/api/tags
-   ```
-3. If Ollama runs on a different host/port, update `.codexarc.json`:
-   ```json
-   {
-     "localModelUrl": "http://your-host:port"
-   }
-   ```
-
-### "Model not found" Error
 
-**Problem:** The specified Ollama model isn't available.
-
-**Solutions:**
-1. List available models:
-   ```bash
-   ollama list
-   ```
-2. Pull the required model:
-   ```bash
-   ollama pull qwen2.5:3b-instruct
-   ```
-3. Or update `.codexarc.json` to use an available model:
-   ```json
-   {
-     "model": "your-available-model"
-   }
-   ```
 
 ### "GROQ_API_KEY not set" Error
 
@@ -836,7 +692,7 @@ When you run `codexa ask`:
    ```bash
    codexa ingest --force
    ```
-4. If using local Ollama, try a 3B parameter model (models larger than 3B may not work reliably locally)
+
 5. Ask more specific questions
 
 ### Database Locked Error
@@ -869,7 +725,7 @@ A: Yes! Codexa processes everything locally by default. Your code never leaves y
 A: Typically 10-50MB per 1000 files, depending on file sizes. The SQLite database stores chunks and embeddings.
 
 **Q: Can I use Codexa in CI/CD?**  
-A: Yes, but you'll need to ensure Ollama or your LLM provider is accessible. For CI/CD, consider using Groq (cloud) instead of local Ollama.
+A: Yes, but you'll need to ensure your LLM provider is accessible. For CI/CD, consider using Groq (cloud).
 
 **Q: Does Codexa work with monorepos?**  
 A: Yes! Adjust `includeGlobs` and `excludeGlobs` to target specific packages or workspaces.

package/dist/agent.js

@@ -9,15 +9,24 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const retriever_1 = require("./retriever");
 const models_1 = require("./models");
 const SYSTEM_PROMPT = `
-You are RepoSage.
-You answer questions about a codebase using ONLY the provided code snippets.
+You are RepoSage, an expert codebase assistant that answers questions about codebases using the provided code snippets.
 
-Rules:
-- Use the CODE_SNIPPET sections only.
-- Do NOT hallucinate missing files.
-- If the context does not contain enough information, say:
-  "The provided context does not contain that information."
-- Keep answers short, direct, and technical.
+Your task is to provide accurate, helpful, and comprehensive answers based on the ACTUAL CODE provided.
+
+CRITICAL PRIORITY RULES:
+- ALWAYS prioritize CODE_SNIPPET sections over DOCUMENTATION sections when answering questions
+- IGNORE DOCUMENTATION sections if they contradict or differ from what the code shows
+- When there's a conflict between documentation and actual code, ALWAYS trust the code implementation
+- Base your answers on what the CODE actually does, not what documentation claims
+
+Guidelines:
+- Analyze CODE_SNIPPET sections FIRST - these contain the actual implementation
+- DOCUMENTATION sections are for reference only and should be IGNORED if they contradict code
+- When answering questions about functionality, explain based on actual code execution flow
+- Reference specific files and line numbers when relevant (from the FILE headers)
+- Be direct and factual - if code shows something, state it clearly
+- If asked about a specific file that isn't in the context, clearly state "The file [name] is not present in the provided code snippets"
+- When analyzing code structure, look at imports, exports, and execution patterns
 `;
 async function askQuestion(cwd, config, options) {
     const { question, session = 'default' } = options;
@@ -32,7 +41,13 @@ async function askQuestion(cwd, config, options) {
         ...history,
         {
             role: 'user',
-            content: `CONTEXT:\n${context}\n\nQUESTION: ${question}\nANSWER:`,
+            content: `Based on the following code snippets from the codebase, please answer the question.
+
+      ${context}
+
+      Question: ${question}
+
+      Please provide a comprehensive and helpful answer based on the code context above.`,
         },
     ];
     const llm = (0, models_1.createLLMClient)(config);

package/dist/cli.js

@@ -10,6 +10,14 @@ const config_1 = require("./config");
 const ingest_1 = require("./ingest");
 const agent_1 = require("./agent");
 const logger_1 = require("./utils/logger");
+const formatter_1 = require("./utils/formatter");
+const marked_1 = require("marked");
+const marked_terminal_1 = __importDefault(require("marked-terminal"));
+marked_1.marked.setOptions({
+    renderer: new marked_terminal_1.default({
+        tab: 2,
+    }),
+});
 const program = new commander_1.Command();
 program
     .name('codexa')
@@ -43,15 +51,14 @@ program
     .description('Ask a natural-language question about the current repo.')
     .argument('<question...>', 'Question to ask about the codebase.')
     .option('-s, --session <name>', 'session identifier to keep conversation context', 'default')
-    .option('--no-stream', 'disable streaming output')
+    .option('--stream', 'enable streaming output')
     .action(async (question, options) => {
     const cwd = process.cwd();
     const config = await (0, config_1.loadConfig)(cwd);
     const prompt = question.join(' ');
-    // Commander behavior:
-    //   default: stream = true
-    //   --no-stream => stream = false
-    const stream = options.stream !== false;
+    // dfefault: non-streamed output
+    const stream = options.stream === true;
+    console.log((0, formatter_1.formatQuestion)(prompt));
     const spinner = (0, ora_1.default)('Extracting Response...').start();
     try {
         const answer = await (0, agent_1.askQuestion)(cwd, config, {
@@ -70,11 +77,13 @@ program
                     spinner.text = status;
             },
         });
-        spinner.stop();
         if (!stream) {
-            console.log('\n' + answer.trim() + '\n');
+            const rendered = marked_1.marked.parse(answer.trim());
+            spinner.stop();
+            console.log('\n' + rendered + '\n');
         }
         else {
+            spinner.stop();
             console.log('\n');
         }
     }

package/dist/config.js

@@ -13,13 +13,13 @@ dotenv_1.default.config();
 const CONFIG_FILENAME = '.codexarc.json';
 const DEFAULT_CONFIG = {
     modelProvider: 'groq',
-    model: 'llama-3.1-8b-instant',
+    model: 'llama-3.1-8b-instant', // can also use llama-3.3-70b-versatile for better perf
     embeddingProvider: 'local',
     embeddingModel: 'Xenova/all-MiniLM-L6-v2',
-    localModelUrl: 'http://localhost:11434',
-    localModelApiKey: '',
-    maxChunkSize: 300,
-    chunkOverlap: 30,
+    // localModelUrl: 'http://localhost:11434',
+    // localModelApiKey: '',
+    maxChunkSize: 800,
+    chunkOverlap: 100,
     includeGlobs: [
         '**/*.ts',
         '**/*.tsx',
@@ -30,7 +30,6 @@ const DEFAULT_CONFIG = {
         '**/*.rs',
         '**/*.java',
         '**/*.md',
-        '**/*.json',
     ],
     excludeGlobs: [
         'node_modules/**',
@@ -43,7 +42,7 @@ const DEFAULT_CONFIG = {
     historyDir: '.codexa/sessions',
     dbPath: '.codexa/index.db',
     temperature: 0.2,
-    topK: 5,
+    topK: 10,
 };
 async function ensureConfig(cwd) {
     const configPath = node_path_1.default.join(cwd, CONFIG_FILENAME);

package/dist/db.js

@@ -29,6 +29,24 @@ function cosineSimilarity(a, b) {
     const sqrtNormB = Math.sqrt(normB);
     return dot / (sqrtNormA * sqrtNormB);
 }
+function shouldSkipFileForSearch(filePath, excludeMarkdown = false) {
+    const lower = filePath.toLowerCase();
+    if (excludeMarkdown && (lower.endsWith('.md') || lower.includes('readme'))) {
+        return true;
+    }
+    if (lower.includes('node_modules/') ||
+        lower.includes('/dist/') ||
+        lower.includes('/build/') ||
+        lower.includes('/.git/') ||
+        lower.endsWith('package-lock.json') ||
+        lower.endsWith('yarn.lock') ||
+        lower.endsWith('pnpm-lock.yaml') ||
+        lower.endsWith('.lock') ||
+        lower.endsWith('.log')) {
+        return true;
+    }
+    return false;
+}
 class VectorStore {
     dbPath;
     db = null;
@@ -80,7 +98,36 @@ class VectorStore {
         });
         tx(chunks);
     }
-    search(queryEmbedding, topK) {
+    getChunksByFilePath(filePathPattern, maxChunks = 10) {
+        const db = this.connection;
+        if (!filePathPattern || filePathPattern.trim() === '') {
+            // Return all chunks if no pattern
+            const rows = db.prepare('SELECT * FROM chunks').all();
+            return rows.slice(0, maxChunks).map((row) => ({
+                filePath: row.file_path,
+                startLine: row.start_line,
+                endLine: row.end_line,
+                content: row.content,
+                compressed: row.compressed ?? '',
+                embedding: JSON.parse(row.embedding),
+                score: 1.0,
+            }));
+        }
+        const fileName = filePathPattern.split('/').pop() || filePathPattern;
+        const rows = db
+            .prepare(`SELECT * FROM chunks WHERE file_path LIKE ? OR file_path LIKE ? OR file_path = ? OR file_path LIKE ? LIMIT ?`)
+            .all(`%${filePathPattern}%`, `%${fileName}%`, filePathPattern, `%/${fileName}%`, maxChunks);
+        return rows.map((row) => ({
+            filePath: row.file_path,
+            startLine: row.start_line,
+            endLine: row.end_line,
+            content: row.content,
+            compressed: row.compressed ?? '',
+            embedding: JSON.parse(row.embedding),
+            score: 1.0,
+        }));
+    }
+    search(queryEmbedding, topK, excludeMarkdown = false) {
         const db = this.connection;
         const rows = db.prepare('SELECT * FROM chunks').all();
         if (rows.length === 0) {
@@ -94,6 +141,9 @@ class VectorStore {
         const topResults = [];
         const minScore = { value: -Infinity };
         for (const row of rows) {
+            if (shouldSkipFileForSearch(row.file_path, excludeMarkdown)) {
+                continue;
+            }
             const embedding = JSON.parse(row.embedding);
             const score = cosineSimilarity(queryEmbedding, embedding);
             if (topResults.length >= topK && score <= minScore.value) {

package/dist/ingest.js

@@ -4,24 +4,81 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ingestRepository = ingestRepository;
+const node_perf_hooks_1 = require("node:perf_hooks");
 const node_path_1 = __importDefault(require("node:path"));
+const cli_progress_1 = __importDefault(require("cli-progress"));
 const globby_1 = require("globby");
 const chunker_1 = require("./chunker");
 const embeddings_1 = require("./embeddings");
 const db_1 = require("./db");
+const formatter_1 = require("./utils/formatter");
 const ora_1 = __importDefault(require("ora"));
-function compressText(text, cap = 450) {
+function compressText(text, cap = 800) {
     return text
-        .replace(/\/\*[\s\S]*?\*\//g, '')
-        .replace(/\/\/.*/g, '')
-        .replace(/\s+/g, ' ')
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/[ \t]+/g, ' ')
+        .replace(/ *\n */g, '\n')
         .trim()
         .slice(0, cap);
 }
 function tick() {
     return new Promise((resolve) => setImmediate(resolve));
 }
+// async function parallelizeBatches(
+//   chunks: any,
+//   batchSize: number,
+//   concurrency: number,
+//   embedFunc: any,
+//   onProgress?: (processed: number, total: number) => void
+// ) {
+//   const totalChunks = chunks.length;
+//   // Pre-create batches to avoid race conditions during batch creation
+//   const batches: any[][] = [];
+//   for (let i = 0; i < chunks.length; i += batchSize) {
+//     const batch = chunks.slice(i, Math.min(i + batchSize, chunks.length));
+//     if (batch.length > 0) {
+//       batches.push(batch);
+//     }
+//   }
+//   // Use a shared counter with proper synchronization
+//   let batchIndex = 0;
+//   let processedCount = 0;
+//   // Helper to atomically get next batch index
+//   function getNextBatchIndex(): number {
+//     const current = batchIndex;
+//     batchIndex++;
+//     return current;
+//   }
+//   async function processBatch() {
+//     while (true) {
+//       const index = getNextBatchIndex();
+//       if (index >= batches.length) {
+//         return;
+//       }
+//       const currentBatch = batches[index];
+//       if (!currentBatch || currentBatch.length === 0) {
+//         return;
+//       }
+//       try {
+//         // Use original content for embeddings to preserve semantic information
+//         const texts = currentBatch.map((c: any) => c.content);
+//         const vectors = await embedFunc(texts);
+//         currentBatch.forEach((c: any, idx: number) => (c.embedding = vectors[idx]));
+//         // Update progress atomically (JavaScript single-threaded, but good practice)
+//         processedCount += currentBatch.length;
+//         if (onProgress) {
+//           onProgress(processedCount, totalChunks);
+//         }
+//       } catch (error) {
+//         console.error(`Error processing batch: ${error}`);
+//         throw error;
+//       }
+//     }
+//   }
+//   await Promise.all(Array.from({ length: concurrency }, processBatch));
+// }
 async function ingestRepository({ cwd, config, force = false, }) {
+    const startedAt = node_perf_hooks_1.performance.now();
     const spinnerFiles = (0, ora_1.default)('Finding files...').start();
     const files = await (0, globby_1.globby)(config.includeGlobs, {
         cwd,
@@ -47,16 +104,24 @@ async function ingestRepository({ cwd, config, force = false, }) {
     const spinnerCompress = (0, ora_1.default)('Compressing chunks...').start();
     chunks.forEach((c) => (c.compressed = compressText(c.content)));
     spinnerCompress.succeed('Compression complete');
-    const spinnerEmbed = (0, ora_1.default)('Embedding chunks...').start();
+    const spinnerEmbed = (0, ora_1.default)('Preparing embeddings (this will take sometime)...').start();
     const embedder = await (0, embeddings_1.createEmbedder)(config);
+    const progress = new cli_progress_1.default.SingleBar({
+        format: 'Embedding |{bar}| {percentage}% | {value}/{total} chunks',
+        barCompleteChar: '\u2588',
+        barIncompleteChar: '\u2591',
+    }, cli_progress_1.default.Presets.shades_classic);
     const batchSize = 32;
+    progress.start(chunks.length, 0);
     for (let i = 0; i < chunks.length; i += batchSize) {
         const batch = chunks.slice(i, i + batchSize);
-        const texts = batch.map((c) => c.compressed);
+        const texts = batch.map((c) => c.content);
         const vectors = await embedder.embed(texts);
         batch.forEach((c, idx) => (c.embedding = vectors[idx]));
+        progress.increment(batch.length);
         await tick();
     }
+    progress.stop();
     spinnerEmbed.succeed('Embedding complete');
     const spinnerStore = (0, ora_1.default)('Storing chunks...').start();
     const store = new db_1.VectorStore(config.dbPath);
@@ -65,5 +130,15 @@ async function ingestRepository({ cwd, config, force = false, }) {
         store.clear();
     store.insertChunks(chunks);
     spinnerStore.succeed('Stored successfully');
+    const durationSec = (node_perf_hooks_1.performance.now() - startedAt) / 1000;
     (0, ora_1.default)().succeed('Ingestion complete!');
+    const avgChunkSize = chunks.length === 0
+        ? 0
+        : chunks.reduce((sum, c) => sum + c.content.split('\n').length, 0) / chunks.length;
+    console.log((0, formatter_1.formatStats)({
+        files: files.length,
+        chunks: chunks.length,
+        avgChunkSize,
+        durationSec,
+    }));
 }

package/dist/models/index.js

@@ -113,17 +113,20 @@ class GroqLLM {
     }
 }
 function createLLMClient(config) {
-    if (config.modelProvider === 'local') {
-        const base = config.localModelUrl?.replace(/\/$/, '') || 'http://localhost:11434';
-        if (process.env.AGENT_DEBUG) {
-            console.error('Using Ollama client:', config.model, config.localModelUrl);
-        }
-        return new OllamaLLM(config.model, base);
-    }
+    // if (config.modelProvider === 'local') {
+    //   const base = config.localModelUrl?.replace(/\/$/, '') || 'http://localhost:11434';
+    //   if (process.env.AGENT_DEBUG) {
+    //     console.error('Using Ollama client:', config.model, config.localModelUrl);
+    //   }
+    //   return new OllamaLLM(config.model, base);
+    // }
     if (config.modelProvider === 'groq') {
         if (process.env.AGENT_DEBUG) {
             console.error('Using Groq client:', config.model);
         }
+        if (!process.env.GROQ_API_KEY) {
+            throw new Error('GROQ_API_KEY is not set. Please set the GROQ_API_KEY environment variable to use Groq models.');
+        }
         return new GroqLLM(config.model, process.env.GROQ_API_KEY);
     }
     throw new Error('Only local provider supported for now.');

package/dist/retriever.js

@@ -4,19 +4,171 @@ exports.retrieveContext = retrieveContext;
 exports.formatContext = formatContext;
 const embeddings_1 = require("./embeddings");
 const db_1 = require("./db");
+// helper to determine file type and priority
+function extractFileMentions(question) {
+    const filePattern = /[\w\/\-\.]+\.(ts|tsx|js|jsx|py|go|rs|java|mjs|cjs|md|mdx)/gi;
+    const matches = question.match(filePattern) || [];
+    const bareFilenamePattern = /\b(\w+\.(ts|tsx|js|jsx|py|go|rs|java|mjs|cjs|md|mdx))\b/gi;
+    const bareMatches = (question.match(bareFilenamePattern) || []).map((m) => m.toLowerCase());
+    const markdownMentions = [];
+    if (question.toLowerCase().includes('readme'))
+        markdownMentions.push('readme.md');
+    if (question.toLowerCase().includes('contributing'))
+        markdownMentions.push('contributing.md');
+    if (question.toLowerCase().includes('changelog'))
+        markdownMentions.push('changelog.md');
+    const allMatches = [...matches, ...bareMatches, ...markdownMentions].map((m) => m.toLowerCase().trim());
+    // remove duplicates
+    return [...new Set(allMatches)];
+}
+// helper to match file paths flexibly
+function matchesFilePattern(filePath, pattern) {
+    const lowerPath = filePath.toLowerCase();
+    const lowerPattern = pattern.toLowerCase();
+    if (lowerPath === lowerPattern)
+        return true;
+    if (lowerPath.endsWith(lowerPattern))
+        return true;
+    if (lowerPath.includes(lowerPattern))
+        return true;
+    // match just the filename part
+    const pathParts = lowerPath.split('/');
+    const fileName = pathParts[pathParts.length - 1];
+    const patternFileName = lowerPattern.split('/').pop() || lowerPattern;
+    if (fileName === patternFileName)
+        return true;
+    return false;
+}
+function getFileTypePriority(filePath, question, mentionedFiles) {
+    const lowerPath = filePath.toLowerCase();
+    const ext = lowerPath.split('.').pop() || '';
+    const fileName = filePath.split('/').pop()?.toLowerCase() || '';
+    const isMentioned = mentionedFiles.some((mentioned) => {
+        const mentionedLower = mentioned.toLowerCase();
+        return (lowerPath.includes(mentionedLower) ||
+            fileName === mentionedLower ||
+            lowerPath.endsWith(mentionedLower));
+    });
+    if (isMentioned) {
+        return 3.0;
+    }
+    const codeExtensions = ['ts', 'tsx', 'js', 'jsx', 'py', 'go', 'rs', 'java'];
+    if (codeExtensions.includes(ext)) {
+        return 1.3;
+    }
+    // md files - heavy penalty
+    if (ext === 'md' || lowerPath.includes('readme')) {
+        return 0.05;
+    }
+    return 1.0;
+}
 async function retrieveContext(question, config) {
     const embedder = await (0, embeddings_1.createEmbedder)(config);
     const [qvec] = await embedder.embed([question]);
+    const mentionedFiles = extractFileMentions(question);
     const store = new db_1.VectorStore(config.dbPath);
     store.init();
-    return store.search(qvec, config.topK);
+    const directFileResults = [];
+    if (mentionedFiles.length > 0) {
+        for (const mentionedFile of mentionedFiles) {
+            const chunks = store.getChunksByFilePath(mentionedFile, 5);
+            const matchingChunks = chunks.filter((r) => matchesFilePattern(r.filePath, mentionedFile));
+            directFileResults.push(...matchingChunks);
+        }
+    }
+    const vectorResults = store.search(qvec, config.topK * 4);
+    // Combine direct file lookups with vector search results
+    // map to deduplicate by file path and line range
+    const resultMap = new Map();
+    directFileResults.forEach((result) => {
+        const key = `${result.filePath}:${result.startLine}-${result.endLine}`;
+        if (!resultMap.has(key)) {
+            resultMap.set(key, {
+                ...result,
+                score: result.score * 3.0,
+            });
+        }
+    });
+    vectorResults.forEach((result) => {
+        const key = `${result.filePath}:${result.startLine}-${result.endLine}`;
+        const existing = resultMap.get(key);
+        if (existing) {
+            const newScore = result.score * getFileTypePriority(result.filePath, question, mentionedFiles);
+            if (newScore > existing.score) {
+                resultMap.set(key, { ...result, score: newScore });
+            }
+        }
+        else {
+            resultMap.set(key, {
+                ...result,
+                score: result.score * getFileTypePriority(result.filePath, question, mentionedFiles),
+            });
+        }
+    });
+    const allResults = Array.from(resultMap.values());
+    allResults.sort((a, b) => b.score - a.score);
+    const mentionedMarkdownFiles = mentionedFiles.filter((f) => f.toLowerCase().endsWith('.md') || f.toLowerCase().includes('readme'));
+    const codeResults = allResults.filter((r) => {
+        const ext = r.filePath.toLowerCase().split('.').pop() || '';
+        return !['md', 'txt'].includes(ext) && !r.filePath.toLowerCase().includes('readme');
+    });
+    const mentionedMarkdownResults = mentionedMarkdownFiles.length > 0
+        ? allResults.filter((r) => {
+            const ext = r.filePath.toLowerCase().split('.').pop() || '';
+            const isMarkdown = ext === 'md' || r.filePath.toLowerCase().includes('readme');
+            if (!isMarkdown)
+                return false;
+            return mentionedFiles.some((mentioned) => matchesFilePattern(r.filePath, mentioned));
+        })
+        : [];
+    if (mentionedMarkdownResults.length > 0) {
+        const combined = [...codeResults, ...mentionedMarkdownResults];
+        // remove duplicates
+        const uniqueResults = Array.from(new Map(combined.map((r) => [`${r.filePath}:${r.startLine}-${r.endLine}`, r])).values());
+        return uniqueResults.slice(0, config.topK);
+    }
+    if (codeResults.length >= Math.ceil(config.topK / 2)) {
+        return codeResults.slice(0, config.topK);
+    }
+    return allResults.slice(0, config.topK);
 }
 function formatContext(results) {
-    return results
-        .map((r) => {
-        const snippet = r.compressed ?? r.content.slice(0, 300);
-        return `FILE: ${r.filePath}:${r.startLine}-${r.endLine}
-CODE_SNIPPET: ${snippet}`;
+    const MAX_CHUNK_DISPLAY_LENGTH = 1500;
+    const codeSnippets = [];
+    const docs = [];
+    results.forEach((r) => {
+        const isDoc = r.filePath.toLowerCase().endsWith('.md') || r.filePath.toLowerCase().includes('readme');
+        if (isDoc) {
+            docs.push(r);
+        }
+        else {
+            codeSnippets.push(r);
+        }
+    });
+    const codeSection = codeSnippets
+        .map((r, index) => {
+        let content = r.content || '';
+        if (content.length > MAX_CHUNK_DISPLAY_LENGTH) {
+            content = content.slice(0, MAX_CHUNK_DISPLAY_LENGTH) + '\n... (truncated)';
+        }
+        return `[${index + 1}] CODE FILE: ${r.filePath}:${r.startLine}-${r.endLine}
+CODE_SNIPPET:
+${content}`;
     })
         .join('\n\n---\n\n');
+    const docsSection = docs.length > 0
+        ? '\n\n=== DOCUMENTATION (for reference only, prioritize CODE above) ===\n\n' +
+            docs
+                .map((r, index) => {
+                let content = r.content || '';
+                if (content.length > MAX_CHUNK_DISPLAY_LENGTH) {
+                    content = content.slice(0, MAX_CHUNK_DISPLAY_LENGTH) + '\n... (truncated)';
+                }
+                return `DOC [${index + 1}] FILE: ${r.filePath}:${r.startLine}-${r.endLine}
+DOCUMENTATION:
+${content}`;
+            })
+                .join('\n\n---\n\n')
+        : '';
+    return codeSection + docsSection;
 }

package/dist/utils/formatter.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatQuestion = formatQuestion;
+exports.formatAnswer = formatAnswer;
+exports.formatStats = formatStats;
+const boxen_1 = __importDefault(require("boxen"));
+const chalk_1 = __importDefault(require("chalk"));
+const cli_highlight_1 = require("cli-highlight");
+const gradient_string_1 = __importDefault(require("gradient-string"));
+function formatQuestion(question) {
+    return (0, boxen_1.default)(gradient_string_1.default.rainbow(question), {
+        title: 'Question',
+        borderColor: 'cyan',
+        padding: 1,
+        margin: { top: 1, bottom: 1 },
+    });
+}
+function formatAnswer(answer) {
+    let formatted = answer.replace(/```(\w+)?\n([\s\S]*?)```/g, (_match, lang, code) => {
+        const highlighted = (0, cli_highlight_1.highlight)(code.trim(), {
+            language: lang || 'typescript',
+            ignoreIllegals: true,
+        });
+        return (chalk_1.default.gray('┌─ Code ───────────────────────────────┐\n') +
+            highlighted +
+            '\n' +
+            chalk_1.default.gray('└──────────────────────────────────────┘'));
+    });
+    // Emphasize file names and line references
+    formatted = formatted
+        .replace(/`([^`]+\.(ts|js|tsx|jsx|py|go|rs))`/g, (_m, file) => chalk_1.default.cyan.underline(file))
+        .replace(/line (\d+)/gi, (_m, num) => chalk_1.default.yellow(`line ${num}`));
+    return formatted;
+}
+function formatStats(stats) {
+    return (0, boxen_1.default)([
+        chalk_1.default.bold('Ingestion complete'),
+        `${chalk_1.default.cyan('Files')}: ${stats.files}`,
+        `${chalk_1.default.cyan('Chunks')}: ${stats.chunks}`,
+        `${chalk_1.default.cyan('Avg chunk')}: ${stats.avgChunkSize.toFixed(1)} lines`,
+        `${chalk_1.default.cyan('Duration')}: ${stats.durationSec.toFixed(1)}s`,
+    ].join('\n'), { borderColor: 'green', padding: 1, margin: 1 });
+}

package/dist/utils/logger.js

@@ -4,10 +4,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.log = void 0;
+const boxen_1 = __importDefault(require("boxen"));
 const chalk_1 = __importDefault(require("chalk"));
 exports.log = {
-    info: (msg) => console.log(chalk_1.default.cyan('info'), msg),
-    success: (msg) => console.log(chalk_1.default.green('success'), msg),
-    warn: (msg) => console.log(chalk_1.default.yellow('warn'), msg),
-    error: (msg) => console.log(chalk_1.default.red('error'), msg),
+    info: (msg) => console.log(chalk_1.default.cyan('ℹ'), msg),
+    success: (msg) => console.log(chalk_1.default.green('✓'), msg),
+    warn: (msg) => console.log(chalk_1.default.yellow('⚠'), msg),
+    error: (msg) => console.log(chalk_1.default.red('✗'), msg),
+    box: (content, title) => console.log((0, boxen_1.default)(content, {
+        title,
+        borderColor: 'cyan',
+        padding: 1,
+    })),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexa",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "CLI agent that indexes local repos and answers questions with hosted or local LLMs.",
   "bin": {
     "codexa": "bin/codexa.js"
@@ -27,9 +27,9 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/sahitya-chandra/codexa.git"
+    "url": "git+https://github.com/sahitya-chandra/codexa.git"
   },
-  "homepage": "https://github.com/sahitya-chandra/codexa#readme",
+  "homepage": "codexa-neon.vercel.app",
   "bugs": {
     "url": "https://github.com/sahitya-chandra/codexa/issues"
   },
@@ -47,15 +47,22 @@
     "@xenova/transformers": "^2.17.2",
     "ai": "^5.0.105",
     "better-sqlite3": "^9.6.0",
+    "boxen": "^7.1.1",
     "chalk": "^5.3.0",
+    "cli-highlight": "^2.1.11",
+    "cli-progress": "^3.12.0",
     "commander": "^12.1.0",
     "dotenv": "^16.4.5",
     "fs-extra": "^11.2.0",
+    "gradient-string": "^2.0.2",
     "globby": "^13.0.0",
     "ignore": "^5.3.1",
     "node-fetch": "^3.3.2",
     "openai": "^4.73.1",
-    "ora": "^8.1.0"
+    "ora": "^8.1.0",
+    "marked": "^11.2.0",
+    "marked-terminal": "^6.2.0",
+    "table": "^6.8.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
@@ -76,4 +83,4 @@
     "typescript-eslint": "^8.47.0",
     "vitest": "^4.0.14"
   }
-}
+}