Configuration

Gestura uses a YAML configuration file located at ~/.gestura/config.yaml. Every setting can also be overridden via environment variables prefixed with GESTURA_.

API keys are never stored in the YAML file, they are persisted in your operating system's secure keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). The api_key fields shown below are used only for initial import and are removed from the file after migration.

Full Schema Example

# ── Core ──────────────────────────────────────────────────
hotkey_listen: "Ctrl+Space"
grace_period_secs: 30
nats_url: "nats://127.0.0.1:4223"

# ── LLM Providers ────────────────────────────────────────
llm:
  primary: "anthropic"        # openai | anthropic | gemini | grok | ollama
  fallback: "ollama"
  openai:
    api_key: ""               # stored in keychain
    base_url: null             # custom endpoint (optional)
    model: "gpt-4o"
  anthropic:
    api_key: ""
    base_url: null
    model: "claude-sonnet-4-20250514"
    thinking_budget_tokens: null  # enable extended thinking (optional)
  gemini:
    api_key: ""
    base_url: null
    model: "gemini-2.0-flash"
  grok:
    api_key: ""
    base_url: null
    model: "grok-3"
  ollama:
    base_url: "http://localhost:11434"
    model: "llama3.2"

# ── Voice & Speech ───────────────────────────────────────
voice:
  provider: "local"            # local | openai | none
  audio_device: null           # null = system default
  local_model_path: null       # path to whisper.cpp .bin model
  input_path: null             # test transcription file (dev)
  openai_api_key: null
  openai_base_url: null
  openai_model: "gpt-4o-transcribe"

# ── UI ───────────────────────────────────────────────────
ui:
  theme_mode: "system"         # system | light | dark
  accent: null                 # optional CSS color

# ── Pipeline & Context ───────────────────────────────────
pipeline:
  max_history_messages: 10
  auto_compact_threshold_percent: 80
  compaction_strategy: "Summarize"  # Summarize | Truncate | Clear | Prompt | MemoryBank
  max_context_tokens: 0             # 0 = use provider default
  log_token_usage: true
  project_guardrails:
    enabled: true
    max_chars: 12000

# ── Permissions ──────────────────────────────────────────
permissions:
  default_level: "Restricted"  # Sandbox | Restricted | Full
  default_enabled_tools:
    file: true
    shell: true
    git: true
    code: true
    web: true
    web_search: true
    task: true
    screenshot: false          # privacy-sensitive
    screen_record: false
    screen: false
    a2a: false                 # advanced
    permissions: false
    mcp: false

# ── Notifications ────────────────────────────────────────
notifications:
  sound_enabled: true
  haptic_enabled: true
  sound_volume: 70             # 0-100
  haptic_intensity: 70         # 0-100
  notification_sound: "default"
  command_confirm_sound: "default"
  mcp_feedback_enabled: true
  auto_listen_on_feedback: true

# ── Web Search ───────────────────────────────────────────
web_search:
  provider: "local"            # local | serpapi | duckduckgo | brave
  serpapi_key: null
  brave_key: null
  max_results: 5
  timeout_secs: 30
  extract_content: true
  max_content_length: 10000
  fallback_providers:
    - "duckduckgo"

# ── MCP Servers ──────────────────────────────────────────
mcp_servers:
  - name: "postgres"
    type: "stdio"              # stdio | http | sse
    enabled: true
    command: "npx"
    args: ["-y", "@anthropic-ai/mcp-server-postgres"]
    env: {}
    scope: "user"              # user | project | local
    timeout_secs: 30
    auto_reconnect: true

# ── Developer ────────────────────────────────────────────
developer:
  developer_mode: false
  enable_simulators: true
  auto_discover_simulators: true
  verbose_ble_logging: false
  simulator:
    device_name_pattern: "Gestura Simulator*"
    auto_connect: true
    health_check_interval: 30
    enable_metrics: true
    discovery_port_range: [9000, 9100]

# ── Prompt Enhancement ───────────────────────────────────
prompt_enhancement:
  auto_enhance: false
  style: "concise"             # concise | detailed | technical
  max_length_multiplier_x10: 30   # ÷10 → actual multiplier (3.0×)

# ── Hooks ────────────────────────────────────────────────
hooks:
  enabled: false
  allowed_programs: []
  timeout_ms: 5000
  max_output_bytes: 65536
  hooks:
    - name: "notify-slack"
      event: "post_pipeline"   # pre_pipeline | post_pipeline | pre_tool | post_tool
      command:
        program: "curl"
        args: ["-X", "POST", "https://hooks.slack.com/..."]

# ── MDH Pointers ────────────────────────────────────────
mdh_pointers: {}

Sections

Core Settings

Top-level settings that control the global behavior of the Gestura application.

LLM Providers (llm)

Define your primary and fallback inference providers. Gestura supports OpenAI, Anthropic, Gemini, Grok, and local Ollama models. If the primary provider fails, requests automatically fall back to the configured fallback.

Provider Configuration

Each provider section accepts the following fields:

Default models per provider:

• OpenAI: gpt-4o
• Anthropic: claude-sonnet-4-20250514, which also supports thinking_budget_tokens for extended reasoning
• Gemini: gemini-2.0-flash
• Grok: grok-3
• Ollama: llama3.2 (base URL: http://localhost:11434)

Voice & Speech (voice)

Controls speech-to-text input. By default Gestura uses a local whisper.cpp model for privacy and speed. You can switch to OpenAI's Whisper API for higher accuracy, or disable voice entirely with "none".

UI Preferences (ui)

Controls the Gestura desktop client appearance.

Pipeline & Context (pipeline)

Controls how the agent pipeline manages conversation context, token limits, and auto-compaction behavior.

Reflection & Learning (pipeline.reflection)

Reflection is Gestura's ERL-inspired quality-recovery system. When enabled, weak turns can trigger a structured correction phase, optionally leading to a same-turn text-only retry and promotion of strong reflections into durable memory.

Project Guardrails (pipeline.project_guardrails)

Automatically discovers and injects project-level instructions (e.g. from an AGENTS.md file) into the agent's system prompt.

Permissions (permissions)

Controls what the agent can do without explicit user confirmation. These are default settings. Individual sessions can override them.

Permission Levels

• Sandbox: Read-only access. No file writes or shell commands.
• Restricted (default): Can read files, but asks for confirmation before writes or shell commands.
• Full: No confirmations. Use with caution.

Default Tool States

Notifications (notifications)

Controls how Gestura confirms completed actions. Supports audio sound effects and Haptic Harmony ring vibrations.

Web Search (web_search)

Configures the built-in web search tool. The default local provider uses DuckDuckGo HTML scraping and requires no API key.

MCP Servers (mcp_servers)

An array of MCP (Model Context Protocol) server entries. Compatible with the .mcp.json schema used by Claude Desktop / Claude Code. You can also import servers from Claude Desktop via the CLI.

Developer Settings (developer)

Settings for Haptic Harmony ring simulator integration and development debugging.

Simulator (developer.simulator)

Prompt Enhancement (prompt_enhancement)

LLM-powered prompt improvement that rewrites user input before sending it to the primary model.

Hooks (hooks)

Execute custom commands on pipeline lifecycle events. Hooks are disabled by default and require an explicit allow-list of programs for security.

Hook Definition (hooks.hooks[])

MDH Pointers (mdh_pointers)

A free-form map of string keys to string values used for Machine Data Hub pointer mappings. Empty by default.

Environment Variables

All environment variables use the GESTURA_ prefix and snake_case naming. They take the highest precedence, overriding both config file values and defaults.

Examples:

export GESTURA_LLM_PRIMARY="openai"
export GESTURA_OPENAI_API_KEY="sk-..."
export GESTURA_VOICE_PROVIDER="none"
export GESTURA_UI_THEME_MODE="dark"

Validation & Health Check

Gestura validates your configuration on startup and reports errors and warnings. You can also run a manual health check via the CLI with gestura config check.

Key Validation Rules

• ui.theme_mode must be "system", "light", or "dark".
• notifications.sound_volume and haptic_intensity must be 0–100.
• OpenAI keys must start with sk- (≥ 20 chars).
• Anthropic keys must start with sk-ant- (≥ 20 chars).
• Grok keys must start with xai- (≥ 20 chars).
• Ollama requires a non-empty base_url (defaults to http://localhost:11434).

Configuration Precedence

Settings are resolved in the following order (highest wins):

1. Environment variables (GESTURA_*)
2. Config file (~/.gestura/config.yaml)
3. Built-in defaults