Current version: v0.70.0 · Schema: v17 · Test suite: ~364 tests

This document is a concise reference for implemented features grouped by area. For the full development roadmap and planned phases see docs/PLAN.md.

• Indexing
• Search
• History / Temporal
• Change Detection
• Clustering
• Branch / Merge
• Analysis
• Visualization (HTML)
• HTTP API Server
• MCP Tools
• Protocol Servers (tools subcommand)
• Maintenance & DB
• Configuration
• Strategic Productization Backlog
• Planned / In Progress

All indexing is content-addressed: a blob (file snapshot) is embedded exactly once per SHA-1 hash, regardless of how many commits or paths reference it.

One database can hold embeddings from multiple embedding models simultaneously. Each embedding row is attributed to its embedding config via the embed_config table.

Chunking fallback chain: whole-file → function boundaries → fixed windows (1500 chars) → fixed windows (800 chars) when a blob exceeds the embedding model's context limit.

All search uses the text embedding model (not the code model) to embed queries (natural language is the common case).

Interactive single-file HTML outputs; no external dependencies required.

Start with gitsema tools serve [--port n] [--key token] [--ui].

Authentication: optional Bearer token via --key <token> / GITSEMA_SERVE_KEY. Per-repo scoped tokens can be minted with gitsema repos token add <repo-id> and are stored as SHA-256 hashes at rest (review7 §4.1) — the plaintext is never persisted in the database.

• Prometheus metrics (GET /metrics): exposes HTTP latency histograms, index size gauges, embedding error counters, query cache hit/miss counters, and Node.js default metrics. Protected by auth by default; set GITSEMA_METRICS_PUBLIC=1 to allow unauthenticated scraping.
• Rate limiting: per-token when auth is enabled, per-IP otherwise. Returns 429 Too Many Requests with Retry-After header. Configure via GITSEMA_RATE_LIMIT_RPM (default 300) and GITSEMA_RATE_LIMIT_BURST.
• OpenAPI spec (GET /openapi.json): machine-readable OpenAPI 3.1 spec generated from Zod route schemas.
• Swagger UI (GET /docs): interactive API explorer loaded from CDN.
• Deployment guide: docs/deploy.md covers systemd, Docker/Ollama sidecar, secrets, backups, model rotation, recommended settings, and team operations (token rotation, audit logging, backup/restore drills).
• Playbooks: docs/playbooks.md provides role-based quickstart recipes for solo developers, PR reviewers, security engineers, and release managers.

Start with gitsema tools mcp. All tools share the same core logic as the CLI.

Legacy top-level aliases gitsema mcp, gitsema lsp, and gitsema serve still work but emit a deprecation warning.

Model profiles allow different models to use different providers, base URLs, and API keys. Profiles are stored in .gitsema/config.json (local) or ~/.config/gitsema/config.json (global, --global).

Per-model settings override the global GITSEMA_PROVIDER / GITSEMA_HTTP_URL / GITSEMA_API_KEY environment variables, so Ollama and OpenAI models can coexist in the same index.

Example:

# Add OpenAI model with dedicated API key
gitsema models add text-embedding-3-small \
  --provider http --url https://api.openai.com --key sk-... --set-text

# Use Ollama for code, OpenAI for prose
gitsema models add nomic-embed-text --provider ollama --set-code

# Then index — the right provider is chosen per model automatically
gitsema index start

Persistent configuration lives in .gitsema/config.json (repo-level) or ~/.config/gitsema/config.json (global, --global).

gitsema config set provider http
gitsema config set model text-embedding-3-small
gitsema config set index.concurrency 8
gitsema config set hooks.enabled true   # auto-install git hooks
gitsema config list                     # show all active values + sources

Environment variables always override config-file values. See README.md for the full env-var reference.

Detailed rationale is documented in docs/review4.md. High-value productizations proposed from the current codebase:

1. Add experts parity to MCP and HTTP (/analysis/experts + MCP tool). ✅ Phase 61
2. Add a machine-readable capabilities manifest across CLI/MCP/HTTP. ✅ Phase 64
3. Add pipelined batch indexing (overlap read/embed/store stages). ✅ Phase 69 (AsyncQueue-based pipeline)
4. Add speed/quality/balanced search profile presets. ✅ Phase 63
5. Add top-K early-cut scoring mode for large candidate sets. ✅ Phase 64
6. Add semantic PR report generation for CI and code review. ✅ Phase 61 (gitsema pr-report)
7. Add incident triage bundles (bisect + change-points + first-seen). ✅ Phase 65 (gitsema triage)
8. Add concept ownership heatmap and ownership-shift tracking. ✅ Phase 67 (gitsema ownership)
9. Add policy-style CI gates for drift/debt/security thresholds. ✅ Phase 66 (gitsema policy check)
10. Add AI-oriented provenance explain mode for prompt grounding. ✅ Phase 64 (--explain-llm)
11. Add saved workflow templates (pr-review, incident, release-audit). ✅ Phase 68 (gitsema workflow run)
12. Add retrieval quality evaluation harness for AI workflows. ✅ Phase 64 (gitsema eval)

All 12 original productization proposals from review4 are now shipped. See docs/review5.md for the next set of priorities.

This section is intentionally brief. The canonical roadmap is in docs/PLAN.md.