Skip to content
Back to search

kodit

👩‍💻 MCP server to index external repositories

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/helixml/kodit with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/helixml/kodit'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/helixml--kodit/badge.svg)](/listings/helixml--kodit)

HTML

<a href="/listings/helixml--kodit"><img src="/api/listings/helixml--kodit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Docker (recommended)

docker run -p 8080:8080 registry.helix.ml/helix/kodit:latest

This starts Kodit with SQLite storage and a built-in embedding model. No API keys needed.

Pre-built binaries

Download a binary from the [releases page](https://github.com/helixml/kodit/releases), then:

chmod +x kodit
./kodit serve

Verify it works

Open the interactive API docs at [http://localhost:8080/docs](http://localhost:8080/docs).

Or index a small repository and run a search:

# Index a repository
curl http://localhost:8080/api/v1/repositories \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "repository",
      "attributes": {
        "remote_uri": "https://gist.github.com/philwinder/7aa38185e20433c04c533f2b28f4e217.git"
      }
    }
  }'

# Check indexing progress
curl http://localhost:8080/api/v1/repositories/1/status

# Search (once indexing is complete)
curl http://localhost:8080/api/v1/search \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "search",
      "attributes": {
        "keywords": ["orders"],
        "text": "code to get all orders"
      }
    }
  }'

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 645 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://helix.ml"><img src="https://docs.helix.ml/images/helix-kodit-logo.png" alt="Kodit" width="300"></a>
  3. </p>
  4. <h1 align="center">Kodit</h1>
  5. <p align="center">
  6. A code and document intelligence server that indexes Git repositories and provides search through MCP and REST APIs.
  7. </p>
  8. <div align="center">
  9. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](./LICENSE)
  10. [![Discussions](https://img.shields.io/badge/Discussions-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/helixml/kodit/discussions)
  11. </div>
  12. AI coding assistants work better when they have access to real examples from your codebase. Kodit indexes your repositories, splits source files into searchable snippets, and serves them to any MCP-compatible assistant. When your assistant needs to write new code, it queries Kodit first and gets back relevant, up-to-date examples drawn from your own projects.
  13. Kodit also handles documents. PDFs, Word files, PowerPoint decks, and spreadsheets are rasterized and indexed so you can search across both code and documentation in one place.
  14. **What you get:**
  15. - **Multiple search strategies** including BM25 keyword search, semantic vector search, regex grep, and visual document search, each exposed as a separate MCP tool so your assistant picks the right approach for each query
  16. - **MCP server** that works with Claude Code, Cursor, Cline, Kilo Code, and any other MCP-compatible assistant
  17. - **REST API** for programmatic access to search, repositories, enrichments, and indexing status
  18. - **AI enrichments** (optional) including architecture docs, API docs, database schema detection, cookbook examples, and commit summaries, all generated by an LLM
  19. - **Document intelligence** with visual search across PDF pages, Office documents, and images using multimodal embeddings
  20. - **No external dependencies required** for basic operation, with a built-in embedding model and SQLite storage
  21. ## Quickstart
  22. ### Docker (recommended)
  23. ```sh
  24. docker run -p 8080:8080 registry.helix.ml/helix/kodit:latest
  25. ```
  26. This starts Kodit with SQLite storage and a built-in embedding model. No API keys needed.
  27. ### Pre-built binaries
  28. Download a binary from the [releases page](https://github.com/helixml/kodit/releases), then:
  29. ```sh
  30. chmod +x kodit
  31. ./kodit serve
  32. ```
  33. ### Verify it works
  34. Open the interactive API docs at [http://localhost:8080/docs](http://localhost:8080/docs).
  35. Or index a small repository and run a search:
  36. ```sh
  37. # Index a repository
  38. curl http://localhost:8080/api/v1/repositories \
  39. -X POST -H "Content-Type: application/json" \
  40. -d '{
  41. "data": {
  42. "type": "repository",
  43. "attributes": {
  44. "remote_uri": "https://gist.github.com/philwinder/7aa38185e20433c04c533f2b28f4e217.git"
  45. }
  46. }
  47. }'
  48. # Check indexing progress
  49. curl http://localhost:8080/api/v1/repositories/1/status
  50. # Search (once indexing is complete)
  51. curl http://localhost:8080/api/v1/search \
  52. -X POST -H "Content-Type: application/json" \
  53. -d '{
  54. "data": {
  55. "type": "search",
  56. "attributes": {
  57. "keywords": ["orders"],
  58. "text": "code to get all orders"
  59. }
  60. }
  61. }'
  62. ```
  63. ## Connecting to AI Assistants
  64. Kodit exposes an MCP endpoint at `/mcp`. Connect your assistant to start using Kodit as a code search tool.
  65. ### Claude Code
  66. ```sh
  67. claude mcp add --transport http kodit http://localhost:8080/mcp
  68. ```
  69. ### Cursor
  70. Add to `~/.cursor/mcp.json`:
  71. ```json
  72. {
  73. "mcpServers": {
  74. "kodit": {
  75. "url": "http://localhost:8080/mcp"
  76. }
  77. }
  78. }
  79. ```
  80. ### Cline
  81. Add to the MCP Servers configuration (Remote Servers tab):
  82. ```json
  83. {
  84. "mcpServers": {
  85. "kodit": {
  86. "autoApprove": [],
  87. "disabled": false,
  88. "timeout": 60,
  89. "type": "streamableHttp",
  90. "url": "http://localhost:8080/mcp"
  91. }
  92. }
  93. }
  94. ```
  95. ### Kilo Code
  96. Add to the MCP configuration (Edit Project/Global MCP):
  97. ```json
  98. {
  99. "mcpServers": {
  100. "kodit": {
  101. "type": "streamable-http",
  102. "url": "http://localhost:8080/mcp",
  103. "alwaysAllow": [],
  104. "disabled": false
  105. }
  106. }
  107. }
  108. ```
  109. Replace `http://localhost:8080` with your server URL if running remotely.
  110. ### Encouraging assistants to use Kodit
  111. Some assistants may not call Kodit tools automatically. Add this to your project rules or system prompt to enforce usage:
  112. ```
  113. For every request that involves writing or modifying code, the assistant's first
  114. action must be to call the kodit search MCP tools. Only produce or edit code after
  115. the tool call returns results.
  116. ```
  117. In Cursor, save this as `.cursor/rules/kodit.mdc` with `alwaysApply: true` frontmatter.
  118. ## MCP Tools
  119. Kodit exposes these tools to connected AI assistants:
  120. | Tool | Description |
  121. |------|-------------|
  122. | `kodit_repositories` | List all indexed repositories |
  123. | `kodit_semantic_search` | Semantic similarity search across code |
  124. | `kodit_keyword_search` | BM25 keyword search |
  125. | `kodit_visual_search` | Search document page images |
  126. | `kodit_grep` | Regex pattern matching |
  127. | `kodit_ls` | List files by glob pattern |
  128. | `kodit_read_resource` | Read file content by URI |
  129. | `kodit_architecture_docs` | Architecture documentation for a repo |
  130. | `kodit_api_docs` | Public API documentation |
  131. | `kodit_database_schema` | Database schema documentation |
  132. | `kodit_cookbook` | Usage examples and patterns |
  133. | `kodit_commit_description` | Commit description |
  134. | `kodit_wiki` | Wiki table of contents |
  135. | `kodit_wiki_page` | Read a specific wiki page |
  136. | `kodit_version` | Server version |
  137. The enrichment tools (`architecture_docs`, `api_docs`, `database_schema`, `cookbook`, `wiki`, `commit_description`) require an LLM provider to be configured. See Enrichment Providers under Configuration Reference.
  138. ## Go Library
  139. Kodit can be embedded directly as a Go library. This is how [Helix](https://helix.ml) integrates Kodit into its platform.
  140. ```go
  141. import "github.com/helixml/kodit"
  142. client, err := kodit.New(
  143. kodit.WithSQLite(".kodit/data.db"),
  144. )
  145. if err != nil {
  146. log.Fatal(err)
  147. }
  148. defer client.Close()
  149. // Index a repository
  150. _, _, err = client.Repositories.Add(ctx, &service.RepositoryAddParams{
  151. URL: "https://github.com/kubernetes/kubernetes",
  152. })
  153. // Search
  154. results, err := client.Search.Query(ctx, "create a deployment",
  155. service.WithLimit(10),
  156. )
  157. for _, result := range results.Enrichments() {
  158. fmt.Println(result.Subtype(), result.Content())
  159. }
  160. ```
  161. ### Library options
  162. | Option | Description |
  163. |--------|-------------|
  164. | `WithSQLite(path)` | Use SQLite for storage |
  165. | `WithPostgresVectorchord(dsn)` | Use PostgreSQL with VectorChord |
  166. | `WithOpenAI(apiKey)` | OpenAI for embeddings and text |
  167. | `WithAnthropic(apiKey)` | Anthropic Claude for text (needs separate embedding provider) |
  168. | `WithTextProvider(p)` | Custom text generation provider |
  169. | `WithEmbeddingProvider(p)` | Custom embedding provider |
  170. | `WithRAGPipeline()` | Skip LLM enrichments, index and search only |
  171. | `WithFullPipeline()` | Require all enrichments (errors without a text provider) |
  172. | `WithDataDir(dir)` | Data directory (default: `~/.kodit`) |
  173. | `WithCloneDir(dir)` | Repository clone directory |
  174. | `WithAPIKeys(keys...)` | API keys for HTTP authentication |
  175. | `WithWorkerCount(n)` | Number of background workers (default: 1) |
  176. | `WithPeriodicSyncConfig(cfg)` | Automatic repository sync settings |
  177. ### Search options
  178. | Option | Description |
  179. |--------|-------------|
  180. | `WithSemanticWeight(w)` | Weight for semantic vs keyword search (0.0 to 1.0) |
  181. | `WithLimit(n)` | Maximum number of results |
  182. | `WithOffset(n)` | Offset for pagination |
  183. | `WithLanguages(langs...)` | Filter by programming languages |
  184. | `WithRepositories(ids...)` | Filter by repository IDs |
  185. | `WithMinScore(score)` | Minimum score threshold |
  186. | `WithEnrichmentTypes(types...)` | Filter results to specific enrichment types |
  187. | `WithSnippets(include)` | Include code snippets in results |
  188. | `WithDocuments(include)` | Include enrichment documents in results |
  189. ### Go HTTP client
  190. A generated HTTP client is available for calling a remote Kodit server from Go:
  191. ```sh
  192. go get github.com/helixml/kodit/clients/go
  193. ```
  194. ```go
  195. import koditclient "github.com/helixml/kodit/clients/go"
  196. client, err := koditclient.NewClient("https://kodit.example.com")
  197. // List repositories
  198. resp, err := client.GetRepositories(ctx, nil)
  199. // Search
  200. text := "create a deployment"
  201. resp, err := client.PostSearch(ctx, koditclient.PostSearchJSONRequestBody{
  202. Data: &koditclient.DtoSearchData{
  203. Attributes: &koditclient.DtoSearchAttributes{
  204. Text: &text,
  205. },
  206. },
  207. })
  208. ```
  209. Types are auto-generated from the OpenAPI spec. See the interactive API docs at `/docs` for the full endpoint list.
  210. ## Production Deployment
  211. For production use, deploy with PostgreSQL (VectorChord) for scalable vector search and a dedicated LLM provider for enrichments.
  212. ### Docker Compose
  213. Save this as `docker-compose.yaml`:
  214. ```yaml
  215. services:
  216. kodit:
  217. image: registry.helix.ml/helix/kodit:latest
  218. ports:
  219. - "8080:8080"
  220. command: ["serve"]
  221. restart: unless-stopped
  222. depends_on:
  223. - vectorchord
  224. environment:
  225. DATA_DIR: /data
  226. DB_URL: postgresql://postgres:mysecretpassword@vectorchord:5432/kodit
  227. # Enrichment LLM (optional, enables AI-generated docs)
  228. ENRICHMENT_ENDPOINT_BASE_URL: http://ollama:11434
  229. ENRICHMENT_ENDPOINT_MODEL: ollama/qwen3:1.7b
  230. # External embedding provider (optional, replaces built-in model)
  231. # EMBEDDING_ENDPOINT_API_KEY: sk-proj-xxxx
  232. # EMBEDDING_ENDPOINT_MODEL: openai/text-embedding-3-small
  233. LOG_LEVEL: INFO
  234. API_KEYS: ${KODIT_API_KEYS:-}
  235. volumes:
  236. - kodit-data:/data
  237. vectorchord:
  238. image: tensorchord/vchord-suite:pg17-20250601
  239. environment:
  240. POSTGRES_DB: kodit
  241. POSTGRES_PASSWORD: mysecretpassword
  242. volumes:
  243. - vectorchord-data:/var/lib/postgresql/data
  244. restart: unless-stopped
  245. volumes:
  246. kodit-data:
  247. vectorchord-data:
  248. ```
  249. ### Kubernetes
  250. ```yaml
  251. apiVersion: apps/v1
  252. kind: Deployment
  253. metadata:
  254. name: vectorchord
  255. spec:
  256. replicas: 1
  257. selector:
  258. matchLabels:
  259. app: vectorchord
  260. template:
  261. metadata:
  262. labels:
  263. app: vectorchord
  264. spec:
  265. containers:
  266. - name: vectorchord
  267. image: tensorchord/vchord-suite:pg17-20250601
  268. env:
  269. - name: POSTGRES_DB
  270. value: kodit
  271. - name: POSTGRES_PASSWORD
  272. value: mysecretpassword
  273. ports:
  274. - containerPort: 5432
  275. ---
  276. apiVersion: v1
  277. kind: Service
  278. metadata:
  279. name: vectorchord
  280. spec:
  281. selector:
  282. app: vectorchord
  283. ports:
  284. - port: 5432
  285. ---
  286. apiVersion: apps/v1
  287. kind: Deployment
  288. metadata:
  289. name: kodit
  290. spec:
  291. replicas: 1
  292. selector:
  293. matchLabels:
  294. app: kodit
  295. template:
  296. metadata:
  297. labels:
  298. app: kodit
  299. spec:
  300. containers:
  301. - name: kodit
  302. image: registry.helix.ml/helix/kodit:latest # pin to a specific version
  303. args: ["serve"]
  304. env: [] # see Configuration Reference for environment variables
  305. ports:
  306. - containerPort: 8080
  307. readinessProbe:
  308. httpGet:
  309. path: /
  310. port: 8080
  311. initialDelaySeconds: 10
  312. periodSeconds: 5
  313. ---
  314. apiVersion: v1
  315. kind: Service
  316. metadata:
  317. name: kodit
  318. spec:
  319. type: LoadBalancer
  320. selector:
  321. app: kodit
  322. ports:
  323. - port: 8080
  324. ```
  325. ### Authentication
  326. Set the `API_KEYS` environment variable to a comma-separated list of keys. Write endpoints (creating repositories, triggering syncs) require a valid key in the `Authorization: Bearer <key>` header. Search endpoints are open by default.
  327. ## Configuration Reference
  328. Configuration is done through environment variables. You can also use a `.env` file:
  329. ```sh
  330. kodit serve --env-file .env
  331. ```
  332. ### Server
  333. | Variable | Default | Description |
  334. |----------|---------|-------------|
  335. | `HOST` | `0.0.0.0` | Listen address |
  336. | `PORT` | `8080` | Listen port |
  337. | `DATA_DIR` | `~/.kodit` | Data directory for models, clones, and database |
  338. | `DB_URL` | (empty) | PostgreSQL connection string (uses SQLite if empty) |
  339. | `LOG_LEVEL` | `INFO` | Logging verbosity: `DEBUG`, `INFO`, `WARN`, `ERROR` |
  340. | `LOG_FORMAT` | `pretty` | Log format: `pretty` or `json` |
  341. | `API_KEYS` | (empty) | Comma-separated API keys for write endpoints |
  342. | `WORKER_COUNT` | `1` | Number of background workers |
  343. | `SEARCH_LIMIT` | `10` | Default search result limit |
  344. | `DISABLE_TELEMETRY` | `false` | Disable anonymous usage telemetry |
  345. | `ALLOW_LOCAL_GIT_REPOSITORIES` | `false` | Read `file://` repositories that have a `.git` directory with git. Otherwise every `file://` repository is indexed as a plain directory. Enable only when every `file://` path is trusted: kodit's own git commands override hooks, the filesystem monitor and diff drivers, but some read-only commands run by the bundled Gitea git library use the repository's configuration as it is |
  346. | `HTTP_CACHE_DIR` | (empty) | Directory for caching HTTP POST responses to disk; avoids repeated API calls during development |
  347. | `REPORTING_LOG_TIME_INTERVAL` | `5` | Progress reporting interval in seconds |
  348. ### Embedding Provider
  349. These configure an external embedding model. If unset, Kodit uses its built-in model.
  350. | Variable | Default | Description |
  351. |----------|---------|-------------|
  352. | `EMBEDDING_ENDPOINT_BASE_URL` | (empty) | Base URL of embedding service |
  353. | `EMBEDDING_ENDPOINT_MODEL` | (empty) | Model identifier |
  354. | `EMBEDDING_ENDPOINT_API_KEY` | (empty) | API key |
  355. | `EMBEDDING_ENDPOINT_MAX_TOKENS` | `0` | Max tokens per request (0 = provider default) |
  356. | `EMBEDDING_ENDPOINT_MAX_BATCH_CHARS` | `16000` | Max total characters per embedding batch |
  357. | `EMBEDDING_ENDPOINT_MAX_BATCH_SIZE` | `1` | Max items per batch |
  358. | `EMBEDDING_ENDPOINT_TIMEOUT` | `60` | Request timeout in seconds |
  359. | `EMBEDDING_ENDPOINT_NUM_PARALLEL_TASKS` | `1` | Concurrent embedding requests |
  360. | `EMBEDDING_ENDPOINT_EXTRA_PARAMS` | (empty) | JSON-encoded extra parameters for the embedding provider |
  361. | `EMBEDDING_ENDPOINT_QUERY_INSTRUCTION` | (empty) | Instruction prepended to queries for asymmetric retrieval |
  362. | `EMBEDDING_ENDPOINT_DOCUMENT_INSTRUCTION` | (empty) | Instruction prepended to documents for asymmetric retrieval |
  363. | `EMBEDDING_ENDPOINT_SOCKET_PATH` | (empty) | Unix socket path for local provider (alternative to BASE_URL) |
  364. | `EMBEDDING_ENDPOINT_MAX_RETRIES` | `5` | Maximum retry attempts on request failure |
  365. | `EMBEDDING_ENDPOINT_INITIAL_DELAY` | `2.0` | Initial retry delay in seconds |
  366. | `EMBEDDING_ENDPOINT_BACKOFF_FACTOR` | `2.0` | Retry backoff multiplier |
  367. ### Vision Embedding Provider
  368. These configure a remote service for image and text vision embeddings. If unset, Kodit uses its built-in SigLIP2 model.
  369. | Variable | Default | Description |
  370. |----------|---------|-------------|
  371. | `VISION_EMBEDDING_ENDPOINT_BASE_URL` | (empty) | Base URL of vision embedding service |
  372. | `VISION_EMBEDDING_ENDPOINT_MODEL` | (empty) | Model identifier |
  373. | `VISION_EMBEDDING_ENDPOINT_API_KEY` | (empty) | API key |
  374. | `VISION_EMBEDDING_ENDPOINT_MAX_TOKENS` | `0` | Max tokens per request (0 = provider default) |
  375. | `VISION_EMBEDDING_ENDPOINT_MAX_BATCH_CHARS` | `16000` | Max total characters per embedding batch |
  376. | `VISION_EMBEDDING_ENDPOINT_MAX_BATCH_SIZE` | `1` | Max items per batch |
  377. | `VISION_EMBEDDING_ENDPOINT_TIMEOUT` | `60` | Request timeout in seconds |
  378. | `VISION_EMBEDDING_ENDPOINT_NUM_PARALLEL_TASKS` | `1` | Concurrent vision embedding requests |
  379. | `VISION_EMBEDDING_ENDPOINT_EXTRA_PARAMS` | (empty) | JSON-encoded extra parameters for the vision embedding provider |
  380. | `VISION_EMBEDDING_ENDPOINT_QUERY_INSTRUCTION` | (empty) | Instruction prepended to queries for asymmetric retrieval |
  381. | `VISION_EMBEDDING_ENDPOINT_DOCUMENT_INSTRUCTION` | (empty) | Instruction prepended to documents for asymmetric retrieval |
  382. | `VISION_EMBEDDING_ENDPOINT_SOCKET_PATH` | (empty) | Unix socket path for local provider (alternative to BASE_URL) |
  383. | `VISION_EMBEDDING_ENDPOINT_MAX_RETRIES` | `5` | Maximum retry attempts on request failure |
  384. | `VISION_EMBEDDING_ENDPOINT_INITIAL_DELAY` | `2.0` | Initial retry delay in seconds |
  385. | `VISION_EMBEDDING_ENDPOINT_BACKOFF_FACTOR` | `2.0` | Retry backoff multiplier |
  386. ### Enrichment Providers
  387. These configure an LLM for generating architecture docs, API docs, database schemas, cookbooks, commit summaries, and wiki pages. Without this, Kodit indexes and searches code but does not generate any AI documentation.
  388. | Variable | Default | Description |
  389. |----------|---------|-------------|
  390. | `ENRICHMENT_ENDPOINT_BASE_URL` | (empty) | Base URL of LLM service |
  391. | `ENRICHMENT_ENDPOINT_MODEL` | (empty) | Model identifier |
  392. | `ENRICHMENT_ENDPOINT_API_KEY` | (empty) | API key |
  393. | `ENRICHMENT_ENDPOINT_NUM_PARALLEL_TASKS` | `1` | Concurrent enrichment requests |
  394. | `ENRICHMENT_ENDPOINT_TIMEOUT` | `60` | Request timeout in seconds |
  395. | `ENRICHMENT_ENDPOINT_EXTRA_PARAMS` | (empty) | JSON-encoded extra parameters for the LLM |
  396. | `ENRICHMENT_ENDPOINT_MAX_TOKENS` | `0` | Max tokens per response (0 = provider default) |
  397. | `ENRICHMENT_ENDPOINT_SOCKET_PATH` | (empty) | Unix socket path for local provider (alternative to BASE_URL) |
  398. | `ENRICHMENT_ENDPOINT_MAX_RETRIES` | `5` | Maximum retry attempts on request failure |
  399. | `ENRICHMENT_ENDPOINT_INITIAL_DELAY` | `2.0` | Initial retry delay in seconds |
  400. | `ENRICHMENT_ENDPOINT_BACKOFF_FACTOR` | `2.0` | Retry backoff multiplier |
  401. | `ENRICHMENT_ENDPOINT_MAX_BATCH_CHARS` | `16000` | Max total characters per batch |
  402. | `ENRICHMENT_ENDPOINT_MAX_BATCH_SIZE` | `1` | Max items per batch |
  403. | `ENRICHMENT_ENDPOINT_QUERY_INSTRUCTION` | (empty) | Instruction prepended to queries for asymmetric retrieval |
  404. | `ENRICHMENT_ENDPOINT_DOCUMENT_INSTRUCTION` | (empty) | Instruction prepended to documents for asymmetric retrieval |
  405. Enrichment is typically the slowest part of indexing because each enrichment requires a round-trip to the LLM provider. Increase `NUM_PARALLEL_TASKS` to speed things up, but respect your provider's rate limits. Start low and increase over time.
  406. Provider examples:
  407. ```sh
  408. # OpenAI
  409. ENRICHMENT_ENDPOINT_BASE_URL=https://api.openai.com/v1
  410. ENRICHMENT_ENDPOINT_MODEL=gpt-4o-mini
  411. ENRICHMENT_ENDPOINT_API_KEY=sk-proj-xxxx
  412. # Ollama (local)
  413. ENRICHMENT_ENDPOINT_BASE_URL=http://localhost:11434
  414. ENRICHMENT_ENDPOINT_MODEL=ollama/qwen3:1.7b
  415. # Helix (private cloud)
  416. ENRICHMENT_ENDPOINT_BASE_URL=https://app.helix.ml/v1
  417. ENRICHMENT_ENDPOINT_MODEL=Qwen/Qwen3-8B
  418. ENRICHMENT_ENDPOINT_API_KEY=your-helix-key
  419. ```
  420. ### Periodic Sync
  421. | Variable | Default | Description |
  422. |----------|---------|-------------|
  423. | `PERIODIC_SYNC_ENABLED` | `true` | Auto-sync repositories on an interval |
  424. | `PERIODIC_SYNC_INTERVAL_SECONDS` | `1800` | Sync interval (default: 30 minutes) |
  425. | `PERIODIC_SYNC_RETRY_ATTEMPTS` | `3` | Retry count on sync failure |
  426. ### Chunking
  427. | Variable | Default | Description |
  428. |----------|---------|-------------|
  429. | `CHUNK_SIZE` | `1500` | Characters per chunk |
  430. | `CHUNK_OVERLAP` | `200` | Overlap between adjacent chunks |
  431. | `CHUNK_MIN_SIZE` | `50` | Minimum chunk size |
  432. ## REST API
  433. The full API is documented interactively at `/docs` on a running Kodit instance. The OpenAPI 3.0 specification is available at `/docs/openapi.json`.
  434. Key endpoints:
  435. | Method | Path | Description |
  436. |--------|------|-------------|
  437. | `POST` | `/api/v1/repositories` | Add a repository for indexing |
  438. | `GET` | `/api/v1/repositories` | List indexed repositories |
  439. | `GET` | `/api/v1/repositories/{id}/status` | Indexing progress |
  440. | `POST` | `/api/v1/repositories/{id}/sync` | Trigger a sync |
  441. | `DELETE` | `/api/v1/repositories/{id}` | Remove a repository |
  442. | `POST` | `/api/v1/search` | Combined search (keyword + semantic) |
  443. | `GET` | `/api/v1/search/semantic` | Semantic search only |
  444. | `GET` | `/api/v1/search/keyword` | Keyword search only |
  445. | `GET` | `/api/v1/search/visual` | Visual search on document pages |
  446. | `GET` | `/api/v1/search/grep` | Regex pattern search |
  447. | `GET` | `/api/v1/search/ls` | List files by glob |
  448. All write endpoints require an `Authorization: Bearer <key>` header when `API_KEYS` is set.
  449. ## How Indexing Works
  450. When you add a repository, Kodit runs a pipeline:
  451. 1. **Clone** the Git repository to local storage
  452. 2. **Scan** commits, branches, and tags to extract metadata
  453. 3. **Extract snippets** by splitting source files into overlapping text chunks
  454. 4. **Build search indexes** with BM25 (keyword) and vector embeddings (semantic)
  455. 5. **Generate enrichments** (if an LLM provider is configured): architecture docs, API docs, database schemas, cookbook examples, commit summaries, and wiki pages
  456. Kodit tracks which files have changed between syncs and only reprocesses modified content. Repositories sync automatically on a configurable interval (default: every 30 minutes).
  457. ### Supported sources
  458. Kodit indexes any Git repository accessible via HTTPS, SSH, or the Git protocol. This includes GitHub, GitLab, Bitbucket, Azure DevOps, and self-hosted servers.
  459. ### Private repositories
  460. Private repositories are supported through personal access tokens or SSH keys:
  461. ```sh
  462. # HTTPS with token
  463. https://username:token@github.com/username/repo.git
  464. # SSH (ensure your SSH key is configured)
  465. git@github.com:username/repo.git
  466. ```
  467. ### Privacy
  468. Kodit respects `.gitignore` and `.noindex` files. Files matching these patterns are excluded from indexing.
  469. ## Storage Backends
  470. ### SQLite (default)
  471. No configuration needed. Kodit creates a SQLite database in the data directory with FTS5 for keyword search and in-process vector storage. Good for single-user and small-team deployments.
  472. ### PostgreSQL with VectorChord
  473. For larger deployments, use PostgreSQL with the [VectorChord](https://github.com/tensorchord/VectorChord) extension. This provides scalable vector search and concurrent access. Set the `DB_URL` environment variable to your connection string.
  474. The recommended Docker image is `tensorchord/vchord-suite:pg17-20250601`, which bundles PostgreSQL 17 with VectorChord, vchord_bm25, and pg_tokenizer.
  475. ## Building from Source
  476. ```sh
  477. git clone https://github.com/helixml/kodit.git
  478. cd kodit
  479. make tools # Install development tools
  480. make download-model # Download the built-in embedding model
  481. make build # Build the binary
  482. ./bin/kodit version
  483. ./bin/kodit serve
  484. ```
  485. Run the tests:
  486. ```sh
  487. make test # All tests
  488. make test PKG=./internal/foo/... # Specific package
  489. make check # Format, vet, lint, and test
  490. ```
  491. ## Troubleshooting
  492. **MCP connection error after restart:** If you see `No valid session ID provided` after restarting the Kodit server, reload the MCP client in your assistant. MCP sessions do not survive server restarts.
  493. **No search results:** Check that indexing has completed by calling `GET /api/v1/repositories/{id}/status`. If status shows errors, check the server logs with `LOG_LEVEL=DEBUG`.
  494. **Enrichments not generating:** Enrichments require an LLM provider. Check that `ENRICHMENT_ENDPOINT_BASE_URL` and `ENRICHMENT_ENDPOINT_MODEL` are set. Without these, Kodit indexes and searches code but does not generate AI documentation.
  495. ## Telemetry
  496. Kodit collects limited anonymous telemetry (usage metadata only, no user data) to guide development. Disable it with:
  497. ```sh
  498. DISABLE_TELEMETRY=true
  499. ```
  500. ## Commercial Support
  501. [Helix](https://helix.ml) provides a managed platform built on Kodit with additional features including a management UI, repository browsing, team collaboration, and hosted infrastructure. For commercial support or enterprise integration, contact [founders@helix.ml](mailto:founders@helix.ml).
  502. ## Contributing
  503. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
  504. ## License
  505. [Apache 2.0](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.