Quick Start

Get up and running with Gestura.app in under 5 minutes. This guide walks you through creating your first voice-enabled agent connected to an MCP server.

Prerequisites

Gestura.app installed (see Installation Guide)
Working microphone
Basic familiarity with configuration files
Optional: An MCP server running locally

Step 1: Initial Setup

First, let's create your configuration directory and initial setup:

# Create configuration directory
gestura-app init

# This creates:
# Windows: %APPDATA%\Gestura\gestura.toml
# macOS: ~/Library/Application Support/Gestura/gestura.toml
# Linux: ~/.config/gestura/gestura.toml

Step 2: Basic Configuration

Create a simple configuration to get started. Open your gestura.toml file and add:

# Basic Gestura.app configuration
[app]
name = "My First Agent"
version = "1.0.0"
log_level = "info"

# Voice recognition settings
[voice]
language = "en-US"
wake_word = "hey gestura"
confidence_threshold = 0.7

# Simple commands without MCP
[commands]
"hello world" = { action = "echo", message = "Hello from Gestura!" }
"what time is it" = { action = "system", command = "date" }
"open calculator" = { action = "system", command = "calc" }  # Windows

Step 3: Test Basic Functionality

Let's test your setup without MCP first:

# Test configuration syntax
gestura-app validate

# Test microphone
gestura-app test-audio

# Start listening (Ctrl+C to stop)
gestura-app listen

# In another terminal, check status
gestura-app status

Step 4: Add MCP Integration

If you have an MCP server running, enhance your configuration:

# Add MCP configuration to your gestura.toml
[mcp]
server_url = "http://localhost:8080"
timeout = 30
retry_attempts = 3

# MCP-powered commands
[commands]
"create file {filename}" = {
  action = "mcp",
  command = "create_file",
  params = { "filename" = "{filename}" }
}
"list files" = {
  action = "mcp",
  command = "list_files"
}
"run {command}" = {
  action = "mcp",
  command = "execute",
  params = { "command" = "{command}" }
}

Step 5: Test Everything

Now test your complete setup:

# Start Gestura with full logging
RUST_LOG=debug gestura-app listen

# Try these voice commands:
# "Hey Gestura, hello world"
# "Hey Gestura, what time is it"
# "Hey Gestura, create a new file called test.txt"
# "Hey Gestura, list files"

Troubleshooting

Voice Recognition Issues

Commands not recognized: Speak clearly, reduce background noise
False triggers: Increase confidence_threshold in config
Wake word not working: Try different wake words or adjust sensitivity

MCP Connection Issues

Connection refused: Ensure MCP server is running on correct port
Timeout errors: Increase timeout value in configuration
Authentication failed: Check MCP server credentials

Next Steps

Now that you have a basic setup working:

Read the Configuration Guide for advanced options
Learn about Voice Commands for better patterns
Explore Session Management for complex workflows
Check out Event Handling for reactive systems

FAQ

Can I use Gestura without MCP? Yes! You can use system commands and built-in actions without any MCP server.

How accurate is voice recognition? Accuracy depends on microphone quality, background noise, and speaking clarity. Typically 90%+ in good conditions.

Can I use custom wake words? Yes, configure any wake word in the [voice] section of your config.

Does it work offline? Basic functionality works offline. Some advanced features may require internet connectivity.

← Installation

Configuration →