Configuration

ctx init writes a default .ctx/config.toml at your project root. Editing it changes how the index is built and how ctx context behaves. If the file is missing, ctx uses the same defaults shown here.

The default config

This is exactly what ctx init writes:

# ctx configuration
[index]
exclude = [
    "node_modules",
    "target",
    ".git",
    ".ctx",
    "dist",
    "build",
    ".cache",
    "vendor",
    "coverage",
    "__pycache__",
    ".next",
    ".nuxt",
    ".venv",
    "venv",
    ".venvs",
    "env",
    ".env",
    "Pods",
    ".output",
]

[context]
max_tokens = 12000
max_files = 25
include_bodies = false

[watch]
enabled = true
debounce_ms = 200

[index] — what gets scanned

exclude is a list of directory names that are skipped during scanning. Add any generated or vendored directory here so it is not parsed. Directories are matched by name at any depth.

Two other limits are baked in and not currently configurable via TOML: a file larger than 2 MB is skipped (oversized files are not upserted), and symlinks are not followed.

[context] — the context budget

These control ctx context:

• max_tokens = 12000 — the token budget for the suggested context package. Overridable per run with ctx context --max-tokens N.
• max_files = 25 — the maximum number of files included.
• include_bodies = false — whether files are emitted as full source or as skeletons. Overridable per run with --include-bodies.

[watch] — filesystem watching

ctx watch listens for file events and re-indexes changed files. enabled = true turns the watcher on, and debounce_ms = 200 is how long a burst of edits is coalesced before re-indexing.