Struct Config 

pub struct Config {

    pub ultra_compact: bool,
    pub tee_mode: TeeMode,
    pub output_density: OutputDensity,
    pub checkpoint_interval: u32,
    pub excluded_commands: Vec<String>,
    pub passthrough_urls: Vec<String>,
    pub custom_aliases: Vec<AliasEntry>,
    pub preserve_compact_formats: Vec<String>,
    pub slow_command_threshold_ms: u64,
    pub theme: String,
    pub cloud: CloudConfig,
    pub gain: GainConfig,
    pub autonomy: AutonomyConfig,
    pub providers: ProvidersConfig,
    pub proxy: ProxyConfig,
    pub proxy_enabled: Option<bool>,
    pub proxy_port: Option<u16>,
    pub proxy_timeout_ms: Option<u64>,
    pub buddy_enabled: bool,
    pub enable_wakeup_ctx: bool,
    pub redirect_exclude: Vec<String>,
    pub disabled_tools: Vec<String>,
    pub default_tool_categories: Vec<String>,
    pub no_degrade: bool,
    pub profile: Option<String>,
    pub tool_profile: Option<String>,
    pub tools_enabled: Vec<String>,
    pub loop_detection: LoopDetectionConfig,
    pub rules_scope: Option<String>,
    pub extra_ignore_patterns: Vec<String>,
    pub terse_agent: TerseAgent,
    pub compression_level: CompressionLevel,
    pub archive: ArchiveConfig,
    pub memory: MemoryPolicy,
    pub allow_paths: Vec<String>,
    pub extra_roots: Vec<String>,
    pub content_defined_chunking: bool,
    pub minimal_overhead: bool,
    pub symbol_map_auto: bool,
    pub team_url: Option<String>,
    pub journal_enabled: bool,
    pub auto_capture: bool,
    pub search: HybridConfig,
    pub llm: LlmConfig,
    pub embedding: EmbeddingConfig,
    pub shell_hook_disabled: bool,
    pub shadow_mode: bool,
    pub shell_activation: ShellActivation,
    pub update_check_disabled: bool,
    pub updates: UpdatesConfig,
    pub bm25_max_cache_mb: u64,
    pub graph_index_max_files: u64,
    pub memory_profile: MemoryProfile,
    pub memory_cleanup: MemoryCleanup,
    pub max_ram_percent: u8,
    pub max_disk_mb: u64,
    pub max_staleness_days: u32,
    pub savings_footer: SavingsFooter,
    pub project_root: Option<String>,
    pub lsp: HashMap<String, String>,
    pub ide_paths: HashMap<String, Vec<String>>,
    pub model_context_windows: HashMap<String, usize>,
    pub response_verbosity: ResponseVerbosity,
    pub bypass_hints: Option<String>,
    pub cache_policy: Option<String>,
    pub boundary_policy: BoundaryPolicy,
    pub secret_detection: SecretDetectionConfig,
    pub allow_auto_reroot: bool,
    pub path_jail: Option<bool>,
    pub sandbox_level: u8,
    pub reference_results: bool,
    pub agent_token_budget: usize,
    pub shell_allowlist: Vec<String>,
    pub shell_allowlist_extra: Vec<String>,
    pub shell_strict_mode: bool,
    pub setup: SetupConfig,
}

Global lean-ctx configuration loaded from config.toml, merged with project-local overrides.

Fields

ultra_compact: bool

tee_mode: TeeMode

output_density: OutputDensity

checkpoint_interval: u32

excluded_commands: Vec<String>

passthrough_urls: Vec<String>

custom_aliases: Vec<AliasEntry>

preserve_compact_formats: Vec<String>

Output formats that are already compact/token-oriented and must be preserved verbatim instead of being recompressed (#342). Matched against the output shape (not the command name), so any tool emitting the format is covered without enumerating commands in excluded_commands. Default: ["toon"]. Set to [] to disable and always recompress.

slow_command_threshold_ms: u64

Commands taking longer than this threshold (ms) are recorded in the slow log. Set to 0 to disable slow logging.

theme: String

cloud: CloudConfig

gain: GainConfig

autonomy: AutonomyConfig

providers: ProvidersConfig

proxy: ProxyConfig

proxy_enabled: Option<bool>

Whether the API proxy is enabled. Tri-state:

• None: undecided (fresh install, will prompt on interactive setup)
• Some(true): user opted in, proxy managed by lean-ctx
• Some(false): user opted out, never touch proxy or endpoints

proxy_port: Option<u16>

proxy_timeout_ms: Option<u64>

Proxy reachability timeout in milliseconds. Default: 200. Override via LEAN_CTX_PROXY_TIMEOUT_MS env var.

buddy_enabled: bool

enable_wakeup_ctx: bool

redirect_exclude: Vec<String>

disabled_tools: Vec<String>

Tools to exclude from the MCP tool list returned by list_tools. Accepts exact tool names (e.g. ["ctx_graph", "ctx_agent"]). Empty by default — all tools listed, no behaviour change.

default_tool_categories: Vec<String>

Tool categories to activate by default for dynamic-tool-capable clients. Values: “core” (always on), “arch”, “debug”, “memory”, “metrics”, “session”. Example: default_tool_categories = ["core", "arch", "memory"] Override via LCTX_DEFAULT_CATEGORIES env var (comma-separated). Empty = lean-ctx default (core + session).

no_degrade: bool

Disable all automatic read-mode degradation (auto_degrade + context_gate pressure). When true, lean-ctx never downgrades requested read modes regardless of pressure. Override via LCTX_NO_DEGRADE=1 env var.

profile: Option<String>

Persistent profile name. Checked after LEAN_CTX_PROFILE env var. Set via lean-ctx config set profile passthrough or editing config.toml.

tool_profile: Option<String>

Tool visibility profile: “minimal” (5), “standard” (20), or “power” (all). Override via LEAN_CTX_TOOL_PROFILE env var. Existing installs default to “power” (backward compat).

tools_enabled: Vec<String>

Explicit list of enabled tool names (overrides tool_profile when non-empty). Example: tools_enabled = ["ctx_read", "ctx_shell", "ctx_search"]

loop_detection: LoopDetectionConfig

rules_scope: Option<String>

Controls where lean-ctx installs agent rule files. Values: “both” (default), “global” (home-dir only), “project” (repo-local only). Override via LEAN_CTX_RULES_SCOPE env var.

extra_ignore_patterns: Vec<String>

Extra glob patterns to ignore in graph/overview/preload (repo-local). Example: ["externals/**", "target/**", "temp/**"]

terse_agent: TerseAgent

Controls agent output verbosity via instructions injection. Values: “off” (default), “lite”, “full”, “ultra”. Override via LEAN_CTX_TERSE_AGENT env var.

compression_level: CompressionLevel

Unified compression level (replaces separate terse_agent + output_density). Values: “off” (default), “lite”, “standard”, “max”. Override via LEAN_CTX_COMPRESSION env var.

archive: ArchiveConfig

Archive configuration for zero-loss compression.

memory: MemoryPolicy

Memory policy (knowledge/episodic/procedural/lifecycle budgets & thresholds).

allow_paths: Vec<String>

Additional paths allowed by PathJail (absolute). Useful for multi-project workspaces where the jail root is a parent directory. Override via LEAN_CTX_ALLOW_PATH env var (path-list separator).

extra_roots: Vec<String>

Extra project roots for multi-root workspaces. Tools like ctx_tree and ctx_search can scan across all roots in a single call. These paths are automatically added to PathJail’s allow-list. Override via LEAN_CTX_EXTRA_ROOTS env var (path-list separator).

content_defined_chunking: bool

Enable content-defined chunking (Rabin-Karp) for cache-optimal output ordering. Stable chunks are emitted first to maximize prompt cache hits.

minimal_overhead: bool

Skip session/knowledge/gotcha blocks in MCP instructions to minimize token overhead. Override via LEAN_CTX_MINIMAL env var.

symbol_map_auto: bool

Auto-enable SymbolMap for projects with >50 source files.

team_url: Option<String>

Team server URL for opt-in savings roll-up. Set via lean-ctx config set team_url https://... or [team] url in config.toml. Override via LEAN_CTX_TEAM_URL env var.

journal_enabled: bool

Enable human-readable activity journal (~/.lean-ctx/journal.md).

auto_capture: bool

Opt-in: auto-persist interesting findings as knowledge facts.

search: HybridConfig

Hybrid search weights (BM25/dense/candidates).

llm: LlmConfig

Optional LLM enhancement (query expansion, contradiction explanation).

embedding: EmbeddingConfig

Semantic-embedding engine settings (which local ONNX model to use).

shell_hook_disabled: bool

Disable shell hook injection (the _lc() function that wraps CLI commands). Override via LEAN_CTX_NO_HOOK env var.

shadow_mode: bool

Shadow mode: transparently intercepts native tool calls (Read/Grep/Shell) via hooks, strengthens MCP instructions to MUST-level, and activates immediate bypass hints on first native tool use. Enables “transparent replacement” so agents use ctx_* without explicit opt-in.

shell_activation: ShellActivation

Controls when the shell hook auto-activates aliases.

• always: (Default) Aliases active in every interactive shell.
• agents-only: Aliases only active when an AI agent env var is detected.
• off: Aliases never auto-activate (user must call lean-ctx-on manually).

Override via LEAN_CTX_SHELL_ACTIVATION env var.

update_check_disabled: bool

Disable the daily version check against leanctx.com/version.txt. Override via LEAN_CTX_NO_UPDATE_CHECK env var.

updates: UpdatesConfig

bm25_max_cache_mb: u64

Maximum BM25 cache file size in MB. Indexes exceeding this are quarantined on load and refused on save. Override via LEAN_CTX_BM25_MAX_CACHE_MB env var.

graph_index_max_files: u64

Maximum number of files scanned by the lightweight JSON graph index. 0 = unlimited (default). Set >0 to cap for constrained systems.

memory_profile: MemoryProfile

Controls RAM vs feature trade-off. Values: “low”, “balanced” (default), “performance”. Override via LEAN_CTX_MEMORY_PROFILE env var.

memory_cleanup: MemoryCleanup

Controls how aggressively memory is freed when idle. Values: “aggressive” (default, 5 min TTL), “shared” (30 min TTL for multi-IDE use). Override via LEAN_CTX_MEMORY_CLEANUP env var.

max_ram_percent: u8

Maximum percentage of system RAM that lean-ctx may use (default: 5). Override via LEAN_CTX_MAX_RAM_PERCENT env var.

max_disk_mb: u64

Simplified disk budget (MB). When set and detail values are at defaults, distributes proportionally: archive=25%, bm25=10%, remainder for stores. 0 = disabled (use individual settings). Override via LEAN_CTX_MAX_DISK_MB.

max_staleness_days: u32

Auto-purge data older than this many days. 0 = disabled. Flows into archive.max_age_hours and lifecycle idle TTL.

savings_footer: SavingsFooter

Controls visibility of token savings footers in tool output. Values: “always” (default, show on every response), “never”, “auto” (legacy compatibility). Override via LEAN_CTX_SAVINGS_FOOTER or LEAN_CTX_SHOW_SAVINGS=1|0 env var.

project_root: Option<String>

Explicit project root override. When set, lean-ctx uses this instead of auto-detection. This prevents accidental home-directory scans when running from $HOME. Override via LEAN_CTX_PROJECT_ROOT env var.

lsp: HashMap<String, String>

LSP server overrides. Map language name to custom binary path. Example: [lsp]\nrust = "/opt/rust-analyzer"\npython = "~/.venvs/main/bin/pylsp"

ide_paths: HashMap<String, Vec<String>>

Per-IDE allowed paths. Restricts which directories lean-ctx will scan/index for each IDE. Example: [ide_paths]\ncursor = ["/home/user/projects/app1"]\ncodex = ["/home/user/codex"] When set, only these paths are indexed for the matching agent. Global allow_paths still applies.

model_context_windows: HashMap<String, usize>

Custom model context window overrides. Example: [model_context_windows]\n"my-custom-model" = 500000

response_verbosity: ResponseVerbosity

Controls how much detail tool responses include.

• full (default): complete compressed output
• headers_only: metadata line only (path, mode, token count)

Override via LEAN_CTX_RESPONSE_VERBOSITY env var.

bypass_hints: Option<String>

Bypass hint mode. When agents use native Read/Grep instead of lean-ctx tools, a hint is appended to the next tool response. Values: “on” (default), “off”, “aggressive” (hint on every call, no cooldown). Override via LEAN_CTX_BYPASS_HINTS env var.

cache_policy: Option<String>

Cache policy for ctx_read. Controls behavior on cache hits. Values: “aggressive” (default, 13-tok stubs + compaction-aware reset), “safe” (delivers map instead of stub), “off” (no caching, always disk read). Override via LEAN_CTX_CACHE_POLICY env var.

boundary_policy: BoundaryPolicy

Cross-project boundary policy. Controls whether cross-project search/import is allowed and whether access is audited.

secret_detection: SecretDetectionConfig

allow_auto_reroot: bool

Allow automatic project-root re-rooting when absolute paths outside the jail are seen. When false (default), absolute paths outside the jail are rejected without re-rooting. Override via LEAN_CTX_ALLOW_REROOT env var.

path_jail: Option<bool>

Disable PathJail entirely. Set to false to allow all paths. Useful in container/Docker environments. Override via LEAN_CTX_NO_JAIL=1.

sandbox_level: u8

Sandbox level for code execution (ctx_exec). 0 = subprocess only (current), 1 = OS-level restriction (Seatbelt/Landlock). Override via LEAN_CTX_SANDBOX_LEVEL env var.

reference_results: bool

When true, large tool outputs (>4000 chars) are stored as references and a short URI is returned instead of the full content. Override via LEAN_CTX_REFERENCE_RESULTS env var.

agent_token_budget: usize

Default per-agent token budget. 0 means unlimited. Override per-agent via ctx_session or programmatically.

shell_allowlist: Vec<String>

Optional shell command allowlist. When non-empty, only commands whose base binary is in this list are permitted by ctx_shell. Empty = disable allowlist (allow all). Default includes common dev tools. Set to [] to disable. Override via LEAN_CTX_SHELL_ALLOWLIST env var (comma-separated).

shell_allowlist_extra: Vec<String>

Extra commands MERGED on top of the effective shell_allowlist without replacing the defaults. Setting shell_allowlist replaces the whole built-in list (a common footgun); entries here are purely additive, which is what lean-ctx allow <cmd> writes. Only applied in restricted mode (when the base allowlist is non-empty).

shell_strict_mode: bool

When true, block command substitution ($(), backticks) and process substitution (<(), >()) in shell arguments. When false (default), only warn via tracing. Default false preserves backward compatibility — set true for maximum security.

setup: SetupConfig

Setup behavior: controls what gets injected during setup and updates.

Implementations

impl Config

pub fn rules_scope_effective(&self) -> RulesScope

Returns the effective rules scope, preferring env var over config file.

pub fn disabled_tools_effective(&self) -> Vec<String>

Returns the effective disabled tools list, preferring env var over config file.

pub fn minimal_overhead_effective(&self) -> bool

Returns true if minimal overhead is enabled via env var or config.

pub fn minimal_overhead_effective_for_client(&self, client_name: &str) -> bool

Returns true if minimal overhead should be enabled for this MCP client.

This is a superset of minimal_overhead_effective():

• LEAN_CTX_OVERHEAD_MODE=minimal forces minimal overhead
• LEAN_CTX_OVERHEAD_MODE=full disables client/model heuristics (still honors LEAN_CTX_MINIMAL / config)
• In auto mode (default), certain low-context clients/models are treated as minimal to prevent large metadata blocks from destabilizing smaller context windows (e.g. Hermes + MiniMax).

pub fn shell_hook_disabled_effective(&self) -> bool

Returns true if shell hook injection is disabled via env var or config.

pub fn shell_activation_effective(&self) -> ShellActivation

Returns the effective shell activation mode (env var > config > default).

pub fn update_check_disabled_effective(&self) -> bool

Returns true if the daily update check is disabled via env var or config.

pub fn memory_policy_effective(&self) -> Result<MemoryPolicy, String>

pub fn default_tool_categories_effective(&self) -> Vec<String>

Returns the effective set of default tool categories. Priority: LCTX_DEFAULT_CATEGORIES env var > config.toml > hardcoded default.

pub fn tool_profile_effective(&self) -> ToolProfile

Returns the effective tool profile. Priority: LEAN_CTX_TOOL_PROFILE env > config tool_profile > config tools_enabled > power.

pub fn no_degrade_effective(&self) -> bool

Returns true if all automatic read-mode degradation is disabled. Checks LCTX_NO_DEGRADE env var first, then config.toml field.

pub fn max_disk_mb_effective(&self) -> u64

Effective max_disk_mb from env or config.

pub fn max_staleness_days_effective(&self) -> u32

Effective max_staleness_days from env or config.

pub fn archive_max_disk_mb_effective(&self) -> u64

Archive max_disk_mb derived from simplified max_disk_mb if the detail value is still at its default. Explicit overrides take priority.

pub fn archive_max_age_hours_effective(&self) -> u64

Archive max_age_hours derived from max_staleness_days if the detail value is still at its default. Explicit overrides take priority.

pub fn bm25_max_cache_mb_effective(&self) -> u64

Effective on-disk ceiling (MB) for the persisted BM25 index. Single source of truth for save/load, cache prune, and the doctor health check.

Priority: explicit bm25_max_cache_mb › max_disk_mb budget (10%) › generous default (DEFAULT_BM25_PERSIST_MB). The default is decoupled from the RAM profile so large repos persist instead of rebuilding forever (issue #249).

impl Config

pub fn path() -> Option<PathBuf>

Returns the path to the global config file (~/.lean-ctx/config.toml).

pub fn local_path(project_root: &str) -> PathBuf

Returns the path to the project-local config override file.

pub fn load() -> Self

Loads config from disk with caching, merging global + project-local overrides.

pub fn save(&self) -> Result<(), LeanCtxError>

Persists the current config to the global config file.

Preserves user comments, formatting, and unknown keys, keeps the file minimal (defaults that were never set on disk stay implicit), and writes atomically with a .bak backup so customizations are always recoverable.

pub fn show(&self) -> String

Formats the current config as a human-readable string with file paths.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Config

where Config: Default,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Config

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.