Pommel: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Pommel is a local-first semantic code search system designed to reduce context window consumption for AI coding agents. It maintains an always-current vector database of code embeddings, enabling targeted semantic searches instead of reading numerous files into context.

Status: v0.7.3 - Configurable timeouts for cold starts and slow connections

Code Search Priority

IMPORTANT: Use pm search BEFORE using Grep/Glob for code exploration.

When looking for:

• How something is implemented → pm search "authentication flow"
• Where a pattern is used → pm search "error handling"
• Related code/concepts → pm search "database connection"
• Code that does X → pm search "validate user input"

Only fall back to Grep/Glob when:

• Searching for an exact string literal (e.g., a specific error message)
• Looking for a specific identifier name you already know
• Pommel daemon is not running

Example workflow:

# First: semantic search to find relevant code
pm search "retry logic with backoff" --limit 5

# Then: read the specific files/lines returned
# Only use grep if you need exact string matching

Quick Start

# Initialize Pommel in a project
pm init --auto --claude --start

# Search the codebase semantically
pm search "database connection handling"
pm search "error handling patterns" --limit 5
pm search "CLI command setup" --json

# Check status
pm status

# Reindex after major changes
pm reindex

Architecture

AI Agent / Developer
        │
        ▼
    Pommel CLI (pm)  ──────► search, status, init, start, stop, reindex, config
        │
        ▼
    Pommel Daemon (pommeld)
    ├── File watcher (fsnotify, debounced)
    ├── Tree-sitter chunker (AST-aware)
    └── Embedding generator (Ollama client)
        │
        ▼
    SQLite + sqlite-vec (local vector DB)
        ▲
        │
    Jina Code Embeddings via Ollama (768-dim vectors)