Module config 

Configuration management for Gestura.

Core config types (struct definitions, pure helpers) are defined in the gestura-core-config domain crate and re-exported here. This module extends them with security-dependent methods via the AppConfigSecurityExt extension trait, JSON→YAML migration, and keychain integration.

Backward compatibility

Older versions stored configuration as JSON in ~/.gestura/config.json. On load, if config.yaml does not exist but config.json does, we automatically migrate the JSON file to YAML.

File location and layering

Gestura’s user configuration is centered on ~/.gestura/config.yaml. Pure types and validation live in gestura-core-config, while this facade adds the runtime wiring needed to make configuration work in the full app.

This includes:

• file-system loading and saving helpers
• JSON-to-YAML migration glue for older installs
• security-aware secret hydration from keychain/secure storage
• canonical-key and legacy-key fallback logic for stored secrets
• user-friendly recovery behavior for fresh installs and reinstalls

Configuration Precedence

Configuration values are loaded with the following precedence (highest first):

1. Environment variables (GESTURA_* prefix)
2. Config file (~/.gestura/config.yaml)
3. Default values

See crate::config_env for environment variable documentation.

Secret handling

Secrets should preferentially live in secure storage rather than plaintext config files. This module provides the security-aware bridge that can:

• read from keychain-backed secure storage when available
• fall back to legacy key names during migration
• self-heal secrets into canonical storage keys when possible
• populate the public AppConfig model with hydrated runtime values

Keeping this logic here rather than in gestura-core-config preserves a clean separation between pure config modeling and OS-integrated secret management.

Modules

config_env

Environment Variable Configuration Support

hooks_types

Hook configuration types used in crate::types::AppConfig.

types

Configuration types and pure AppConfig methods.

validation

Configuration validation and health checking

watcher

Configuration file watcher for runtime configuration reloading

Structs

AgentTelemetrySettings

Settings for request-level agent-loop telemetry.

AgentTelemetryTraceExportSettings

OTLP trace export settings for request-level agent telemetry.

AnthropicConfig

AppConfig

Application configuration persisted to a YAML file.

ConfigError

Configuration error

ConfigHealthCheck

Configuration health check result

ConfigValidationResult

Configuration validation result

ConfigWarning

Configuration warning

ConfigWatcher

Configuration file watcher

DeveloperSettings

Developer and simulator settings

GeminiConfig

GlobalPermissionSettings

Global permission settings for tool execution.

GrokConfig

HookCommandTemplate

A command template for a hook.

HookDefinition

A single hook definition.

HooksSettings

Global hooks settings.

HotReloadableSettings

Settings that can be hot-reloaded without restart

LlmSettings

LLM settings grouping provider-specific configs

McpJsonFile

Represents an .mcp.json configuration file.

McpServerEntry

Full MCP server entry compatible with .mcp.json.

McpTool

MCP tool entry (basic) — DEPRECATED: use McpServerEntry instead.

NotificationSettings

Notification settings for response completion and MCP feedback

NotificationSettingsPatch

Partial update payload for notification settings.

OllamaConfig

OpenAiConfig

PipelineSettings

Pipeline and context management settings.

PrivacySettings

Privacy and data-handling preferences for the local app experience.

ProjectGuardrailsSettings

Settings for project-level guardrails discovery and prompt injection.

PromptEnhancementSettings

Prompt enhancement settings for LLM-powered prompt improvement

PromptEnhancementSettingsPatch

Partial update payload for prompt-enhancement settings.

ReflectionSettings

Settings for ERL-inspired experiential reflection.

SimulatorSettings

Simulator-specific configuration

UiSettings

UI preferences including theme mode and accent color.

VoiceSettings

Voice settings; default uses local Whisper

WebSearchConfig

Web search configuration.

WhisperModelInfo

Information about available Whisper models

Enums

AgentTelemetryTraceExportProtocol

OTLP trace export settings for request-level agent telemetry.

ApiKeyValidation

API key validation result

AppError

Top-level application error for Gestura.

ConfigChangeEvent

Events emitted when configuration changes

GlobalPermissionLevel

Global permission level for new sessions.

HookEvent

A hook event.

McpScope

Configuration scope for MCP servers.

McpTransportType

Transport type for MCP server connections.

WebSearchProvider

Web search provider selection.

Constants

ENV_MAPPINGS

Environment variable mappings for AppConfig fields

ENV_PREFIX

Environment variable prefix for all Gestura configuration

Traits

AppConfigSecurityExt

Extension trait adding security-dependent methods to AppConfig.

Functions

get_env

Get an environment variable with the GESTURA_ prefix

get_env_bool

Get an environment variable as a boolean

get_env_u32

Get an environment variable as a u32

get_env_u64

Get an environment variable as a u64

get_env_usize

Get an environment variable as a usize

get_set_env_vars

Get all environment variables that are set

import_claude_desktop_servers

Import MCP servers from Claude Desktop config.

infer_transport_from_endpoint

Infer the MCP transport type from an endpoint URL.

is_secret_key

Check if a key is a secret (should be redacted in logs)

print_env_docs

Print documentation for all environment variables

redact_secret

Redact a secret value for logging

validate_anthropic_key

Validate an Anthropic API key

validate_api_key

Validate any API key by provider name

validate_config

Validate an AppConfig

validate_grok_key

Validate a Grok API key

validate_openai_key

Validate an OpenAI API key

Type Aliases

Result

Result type alias for operations that may fail with AppError.