Gestura.app user documentation
Learn the intent-first architecture, workflows, GUI, CLI, and feature controls.
This documentation is written for people using Gestura.app day to day. Start here to understand how voice, chat, CLI, and gesture inputs converge on one shared core loop, then move into the guides that match how you actually work.
I am brand new
Understand the product, install it, grant permissions, and complete your first workflow.
I want to use the desktop app well
Learn the GUI surfaces, voice controls, settings, and notifications that shape everyday use.
I prefer the CLI
Start from the terminal and add tools, workflows, and diagnostics when you need them.
Browse by topic
The user docs are organized from first-run guidance through deeper reference and recovery material. Use the sidebar on article pages for the full navigation tree.
Start Here
- Docs Home
Choose the right learning path for your first install, daily use, or troubleshooting.
- What is Gestura.app?
Understand what the app does, who it is for, and how the desktop app, CLI, and hardware fit together.
- How Gestura Works
Learn the user-level architecture: inputs, sessions, tools, permissions, and outputs.
- Installation
Install Gestura.app on Windows, macOS, or Linux, or build it from source.
- First Launch & Permissions
Prepare microphone access, voice settings, trust controls, and your first successful run.
- First Workflow Quickstart
Complete one end-to-end task with voice, chat, and an MCP tool connection.
Core Concepts
- Sessions & Conversations
Understand how Gestura keeps context, history, and task state together.
- Knowledge, Memory & Retrieval
Learn how built-in expertise, user-managed knowledge, session memory, and durable memory work together.
- Workflows & Approvals
See how requests become actions, where approvals happen, and how progress is communicated.
- Reflection & Learning (ERL)
Understand ERL-inspired reflection, quality recovery, and how useful corrections can be reused later.
- Projects & Context
Learn how project instructions, scoped tools, and working directories shape behavior.
- Models & Providers
Understand local defaults, cloud providers, fallbacks, and when provider settings affect the experience.
- Tools & Permissions
Review built-in capabilities, permission levels, and MCP extensions.
Use the App
- GUI Tour
Get oriented in the desktop experience and learn where everyday controls live.
- Voice & Natural Interaction
Use wake word, hotkey, chat, and gestures as one continuous interaction model.
- Settings & Preferences
Decide what belongs in the GUI, config file, keychain, and environment variables.
- Notifications & Haptics
Tune sounds, haptic feedback, and automatic re-listening behavior.
- Haptic Harmony Ring
Understand gesture control, feedback, simulator support, and ring-specific settings.
CLI Guides
- CLI Overview
Learn when to use the CLI and how it complements the desktop app.
- CLI Quickstart
Initialize Gestura, start listening, open chat, and check configuration from the terminal.
- CLI Workflows
Run repeatable session and workflow patterns from your shell.
- CLI Knowledge & Context
Inspect built-in knowledge, search relevant expertise, and understand context analysis commands.
- CLI MCP & Tools
Add, inspect, and validate tool connections from the command line.
- CLI Diagnostics
Use health checks, config validation, and recovery commands to debug issues.
- CLI Privacy & Maintenance
Review secure storage, environment overrides, upgrades, and safe maintenance habits.
Reference
- Configuration Reference
Browse the full configuration model, defaults, and environment-variable overrides.
- Controls & Shortcuts
Quick lookup for wake word, listen hotkey, and control surfaces.
- Glossary
Decode common Gestura terms such as sessions, permissions, MCP, and haptic feedback.
Troubleshooting & Support
- Common Problems
Start here for install, microphone, permissions, and tool-connection issues.
- Diagnostics & Logs
Find the fastest way to gather useful information before asking for help.
- Workflow Recovery
Recover from interrupted runs, misfires, approval blockers, and context drift.
- Permissions & Privacy Troubleshooting
Fix microphone access, approval friction, provider trust, and secret-storage problems.
- Ring Troubleshooting
Work through pairing, connectivity, haptic, and gesture-recognition issues.
- Support & Escalation
Know when to use the docs, FAQ, community, or GitHub issue tracker.