gloggur 0.1.0

Symbol-level, incremental codebase indexer for semantic search and precedent retrieval.

Gloggur

Gloggur is a symbol-level, incremental codebase indexer for semantic search and precedent retrieval. It parses code into symbols, generates embeddings, stores them locally, and exposes a JSON-friendly CLI for integration with AI agents.

Features

• Tree-sitter parsing for multi-language symbol extraction
• Incremental indexing with SHA-256 hashing
• Pluggable embedding backends (local models, OpenAI, or Gemini)
• FAISS vector search with SQLite metadata
• Docstring audit with semantic similarity scoring
• JSON output for CLI automation

Installation

Preferred:

pipx install gloggur

Alternatives:

pip install gloggur

Optional:

pipx install "gloggur[openai]"
pipx install "gloggur[gemini]"
pipx install "gloggur[local]"

For local development worktrees, use the repo wrapper/bootstrap flow:

scripts/bootstrap_gloggur_env.sh
scripts/gloggur status --json

scripts/gloggur now runs a preflight check before launching the CLI:

• prefers .venv/bin/python when healthy
• otherwise falls back to system Python with repo-root PYTHONPATH
• returns structured --json failures with operation=preflight

Quickstart

Index a repository:

gloggur index . --json

Search for similar symbols:

gloggur search "streaming parser" --top-k 5 --json

Stream results as line-delimited JSON:

gloggur search "streaming parser" --top-k 50 --json --stream

Inspect docstrings (semantic similarity scoring):

gloggur inspect . --json

gloggur inspect skips unchanged files by default. Use --force to reinspect everything.

Check status:

gloggur status --json

Enable save-triggered indexing (one-time setup):

gloggur watch init . --json
gloggur watch start --daemon --json

Check or stop watcher:

gloggur watch status --json
gloggur watch stop --json

Clear cache:

gloggur clear-cache --json

Cache compatibility is automatic:

• If cache schema changes, Gloggur rebuilds .gloggur-cache/index.db automatically.
• If embedding provider/model changes, the next gloggur index ... run rebuilds cache and vectors automatically.

On-Save Indexing (Watch Mode)

Watch mode keeps the index updated in the background as files are saved.

• Filesystem events are debounced (watch_debounce_ms, default 300) to coalesce save bursts.
• Content hashing avoids re-parsing/re-embedding unchanged files.
• Deleted/changed symbol vectors are removed before upsert to prevent stale search hits.
• Runtime state is written to .gloggur-cache/watch_state.json by default.

Verification

Core behavior checks run in pytest (including smoke tests):

.venv/bin/pytest

Additional verification probes are available for provider/edge/performance checks:

# Run non-test verification phases (providers, edge cases, performance)
python scripts/run_suite.py

# Run specific phases
python scripts/run_provider_probe.py  # Embedding providers
python scripts/run_edge_bench.py  # Edge cases & performance

See docs/VERIFICATION.md for detailed documentation. See docs/AGENT_INTEGRATION.md for agent integration guidance.

Configuration

Create .gloggur.yaml or .gloggur.json in your repository:

embedding_provider: gemini
local_embedding_model: microsoft/codebert-base
openai_embedding_model: text-embedding-3-large
gemini_embedding_model: gemini-embedding-001
cache_dir: .gloggur-cache
watch_enabled: false
watch_path: .
watch_debounce_ms: 300
watch_mode: daemon
watch_state_file: .gloggur-cache/watch_state.json
watch_pid_file: .gloggur-cache/watch.pid
watch_log_file: .gloggur-cache/watch.log
docstring_semantic_threshold: 0.2
docstring_semantic_max_chars: 4000
supported_extensions:
  - .py
  - .js
  - .jsx
  - .ts
  - .tsx
  - .rs
  - .go
  - .java
excluded_dirs:
  - .git
  - node_modules
  - venv
  - .venv
  - .gloggur-cache
  - dist
  - build
  - htmlcov

Environment variables:

• GLOGGUR_EMBEDDING_PROVIDER
• GLOGGUR_LOCAL_MODEL
• GLOGGUR_OPENAI_MODEL
• OPENAI_API_KEY
• GLOGGUR_GEMINI_MODEL
• GLOGGUR_GEMINI_API_KEY
• GLOGGUR_CACHE_DIR
• GLOGGUR_WATCH_ENABLED
• GLOGGUR_WATCH_PATH
• GLOGGUR_WATCH_DEBOUNCE_MS
• GLOGGUR_WATCH_MODE
• GLOGGUR_DOCSTRING_SEMANTIC_MIN_CHARS
• GEMINI_API_KEY (or GOOGLE_API_KEY)

Output Schema

Search results are returned as JSON:

{
  "query": "...",
  "results": [
    {
      "symbol": "function_name",
      "kind": "function",
      "file": "path/to/file.py",
      "line": 42,
      "signature": "def function_name(arg1, arg2)",
      "docstring": "...",
      "similarity_score": 0.95,
      "context": "surrounding code snippet"
    }
  ],
  "metadata": {
    "total_results": 10,
    "search_time_ms": 45
  }
}

Development

scripts/bootstrap_gloggur_env.sh
scripts/gloggur status --json
.venv/bin/pytest

If bootstrap/preflight fails with --json, error payloads include:

• error_code: missing_venv, missing_python, missing_package, broken_environment
• message
• remediation steps
• detected_environment details