Configuration

GitKB stores its configuration in .kb/config.toml, created when you run git kb init. This file lives alongside the KB database inside the .kb/ directory.

Minimal config

A freshly initialized KB starts with an empty config. GitKB works with sensible defaults — you only need to add settings you want to customize.

[identity]
# Uses your git config name/email by default

Full annotated reference

[identity]

Override the author identity used for KB commits. If omitted, GitKB reads from your git config (user.name and user.email).

[identity]
name = "Alice"
email = "alice@example.com"

[sync.remotes.<name>]

Define named remotes for pushing and pulling KB state. Each remote needs a url pointing to a GitKB sync endpoint.

[sync.remotes.origin]
url = "https://gitkb.com/my-org/my-kb"

[sync.remotes.staging]
url = "gitkb://gitkb.com/my-org/my-kb"

Use git kb remote add <name> <url> to add remotes via the CLI instead of editing this file directly.

[repos]

Configure repository discovery strategy. This controls how GitKB finds and manages repositories in your project.

[repos]
strategy = "meta"   # Use meta-repo discovery (for multi-repo workspaces)
# strategy = "auto"  # Default — auto-detect single repo

Value	Description
"auto"	Default. Single repository, discovered by searching upward for .git/.
"meta"	Multi-repo workspace managed by meta. GitKB discovers repos via .meta configuration.

[code]

Configure the code intelligence indexer.

[code]
index_threads = 0   # 0 = auto-detect (uses all available cores)

Key	Type	Default	Description
index_threads	integer	0	Number of threads for code indexing. 0 uses all available CPU cores.

[embeddings]

Configure the embedding engine for semantic search. Embeddings are disabled by default — enable them to use git kb ai semantic and the kb_semantic MCP tool.

[embeddings]
enabled = true
backend = "candle"
batch_size = 16
queue_size = 64
batch_delay_ms = 50

Key	Type	Default	Description
enabled	boolean	false	Enable embedding generation and semantic search.
backend	string	"candle"	Embedding backend. Currently only "candle" (local, on-device) is supported.
batch_size	integer	16	Number of documents to embed per batch.
queue_size	integer	64	Maximum number of pending embedding requests.
batch_delay_ms	integer	50	Delay in milliseconds before processing a partial batch.

[embeddings.index]

Configure where the vector index is stored on disk.

[embeddings.index]
path = ".kb/cache/index"

Key	Type	Default	Description
path	string	".kb/cache/index"	Directory for the vector similarity index. Relative to the KB root.

[auth]

Configure authentication for the sync server (used when running git kb serve).

[auth]
mode = "optional"   # or "required"

[auth.api_keys]
# key_name = "key_value"

Key	Type	Default	Description
mode	string	"optional"	"optional" allows unauthenticated access. "required" enforces API key authentication.
api_keys	table	{}	Named API keys for authenticating sync requests.

[pager]

Configure external pagers for rendering output.

[pager]
markdown = "glow -p -w 0"

Key	Type	Default	Description
markdown	string	none	Command to pipe Markdown output through. glow works well. If unset, Markdown renders as plain text.

Example: full config

[identity]
name = "Alice"
email = "alice@example.com"

[sync.remotes.origin]
url = "https://gitkb.com/acme/main-kb"

[repos]
strategy = "auto"

[code]
index_threads = 0

[embeddings]
enabled = true
backend = "candle"
batch_size = 16
queue_size = 64
batch_delay_ms = 50

[embeddings.index]
path = ".kb/cache/index"

[auth]
mode = "optional"

[auth.api_keys]

[pager]
markdown = "glow -p -w 0"

Next steps

• CLI Reference — Commands that read and modify configuration
• Daemon — Background service configured via these settings
• Team Collaboration — Using remotes for team workflows