Gaia

Gaia is a command-line interface (CLI) tool that provides a convenient way to interact with language models through a local or remote API. It features a beautiful terminal UI, configuration management, automatic role detection, response caching, and support for different interaction modes.

Features

• 🚀 Simple and intuitive command-line interface
• 🎨 Beautiful terminal UI with progress bars
• 📺 Interactive TUI prompts (Bubble Tea): when using tool actions (gaia tool git commit) or operator mode (gaia investigate), context and confirmation prompts use a rich terminal UI in a real terminal — styled boxes, keyboard shortcuts, text wrapping to window width
• ⚙️ Comprehensive configuration management with YAML support
• 🔄 Support for different interaction modes (default, describe, code, shell, commit, branch)
• 🤖 Automatic role detection based on message content
• 📦 Automatic model management (pull if not present)
• 💾 Response caching for faster repeated queries
• 🧹 Optional sanitization of prompts before LLM (reduce noise and tokens; configurable levels)
• 🔌 Support for local (Ollama) and remote (OpenAI, Mistral) APIs
• 🛠️ Tool integration for executing external commands
• 📥 Stdin support for piping content
• 🔍 Investigate (operator mode): autonomous investigation with tool execution (e.g. "Why is my disk full?") — plan, run commands, reason, and summarize with safety controls (denylist, confirmation, dry-run)

Installation

Prerequisites

• Go 1.26 or later
• A running instance of a compatible language model API (e.g., Ollama) or an API key for OpenAI or Mistral

Building from Source

git clone https://github.com/vonglasow/gaia.git
cd gaia
go build

Using Homebrew (recommended 🍺)

brew tap vonglasow/tap
brew install gaia

Update

brew upgrade gaia

Configuration

Gaia stores its configuration in ~/.config/gaia/config.yaml. The configuration file is automatically created on first run with sensible defaults.

Project-Local Overrides (.gaia.yaml)

When you run Gaia inside a project, Gaia looks for a local .gaia.yaml (from your current directory up to the git repository root).

• Local config is useful for project-specific roles.* prompts and tools.* actions.
• On first detection, Gaia asks whether you trust that repository.
• If trusted, local settings override your user config for that repository.
• Trust decisions are stored in ~/.config/gaia/trusted-repos.yaml and reused on next runs.
• In non-interactive mode (CI, piped execution), untrusted local config is ignored and Gaia uses user/global config only.

Configuration precedence is:

CLI flags > env vars > local .gaia.yaml > ~/.config/gaia/config.yaml > built-in defaults

Basic Configuration

• model: The language model to use (default: "mistral" for Ollama, "gpt-4o-mini" for OpenAI, "mistral-medium-latest" for Mistral)
• host: API host (default: "localhost" for Ollama, "api.openai.com" for OpenAI, "api.mistral.ai" for Mistral)
• port: API port (default: 11434 for Ollama, 443 for OpenAI and Mistral)

Cache Configuration

• cache.enabled: Enable/disable response caching (default: true)
• cache.dir: Cache directory path (default: ~/.config/gaia/cache)

Sanitize before LLM

Optional preprocessing to reduce noise and token usage before sending messages to the model:

• sanitize_before_llm: Enable/disable sanitization (default: false)
• sanitize.level: Filter intensity — none, light, or aggressive (default: light)
  • light: Removes debug/metadata lines, timestamps, obvious duplicates, collapses extra newlines
  • aggressive: In addition, removes long unstructured runs and redundant sections
• sanitize.max_tokens_after: Cap total tokens after sanitization (default: 0 = no cap)
• sanitize.log_stats: Log token counts and filtering stats to stderr when sanitization runs (default: true)

The last user message is always preserved. When enabled, a one-line summary is printed to stderr, e.g. [sanitize] tokens before=1200 after=800 removed≈400 ms=2.

Auto-Role Detection

• auto_role.enabled: Enable automatic role detection (default: true)
• auto_role.mode: Detection mode - off, heuristic, or hybrid (default: hybrid)
  • off: Disable auto-detection, always use default role
  • heuristic: Use fast local keyword matching only
  • hybrid: Use heuristic first, fallback to LLM for ambiguous cases
• auto_role.keywords.<role_name>: Custom keywords for role detection (see below)

Roles

Roles define different interaction modes with their respective prompts. The available roles depend on what is configured in your configuration file. By default, the following roles are pre-configured:

Default Roles (Pre-configured):

• roles.default: General programming and system administration assistance
• roles.describe: Command description and documentation
• roles.shell: Shell command generation
• roles.code: Code generation without descriptions
• roles.commit: Generate conventional commit messages
• roles.branch: Generate branch names

Custom Roles: You can add custom roles by adding roles.<role_name> keys to your configuration file. Any role defined in the configuration will be available for use.

YAML role directory and inheritance: When roles.directory is set to a directory path, Gaia loads roles from YAML files in that directory (one role per file). Roles can inherit from others with extends: ["base", "other-role"]. Parent prompts are concatenated first (separator ---), then the child’s; signals, threshold, priority, weight, mode and exclusive are merged (child overrides when defined). Circular or missing parents cause a clear error. Resolution runs once at load time. Optional: roles.debug (or CLI --roles-debug) prints resolution and scoring to stderr with prefix [ROLES DEBUG].

Note: The list of available roles is dynamic and depends on your configuration. Use gaia config list to see all configured roles in your setup.

Role Keywords (Auto-Detection)

Keywords are used by the heuristic detection to identify the appropriate role. Default keywords are pre-configured for the default roles:

Pre-configured Keywords:

• auto_role.keywords.shell: Command-related keywords
• auto_role.keywords.code: Programming-related keywords
• auto_role.keywords.describe: Question/explanation keywords
• auto_role.keywords.commit: Commit message keywords
• auto_role.keywords.branch: Branch creation keywords

Custom Keywords: You can customize these keywords or add keywords for custom roles by adding auto_role.keywords.<role_name> keys to your configuration file. This allows auto-detection to work with your custom roles as well.

Tool Configuration

Tools allow you to execute external commands with AI-generated content. Example configuration:

tools:
  git:
    commit:
      context_command: "git diff --staged"
      role: "commit"
      execute_command: "git commit -F {file}"
    branch:
      context_command: "git diff"
      role: "branch"
      execute_command: "git checkout -b {response}"

Tool configuration fields:

• context_command: Command to run to gather context (optional)
• role: Role to use for AI generation
• execute_command: Command to execute with AI response (use {file} for multi-line, {response} for single-line)

Operator (Investigate) Configuration

The operator mode (gaia investigate) uses the following options (all under operator.):

• operator.max_steps: Maximum number of steps per run (default: 10)
• operator.confirm_medium_risk: Ask for confirmation before running medium-risk commands (default: true)
• operator.dry_run: If true, never execute commands; only show what would be run (default: false)
• operator.denylist: List of forbidden command patterns (e.g. ["rm -rf", "sudo", "mkfs"]). Commands containing these are blocked.
• operator.allowlist: Optional. If set, only commands that start with or contain one of these patterns are allowed (prefix or substring, case-insensitive; not regex). Example: ["df", "du", "find"].
• operator.output_max_bytes: Maximum length of command output per step (default: 4096); longer output is truncated.
• operator.command_timeout_seconds: Timeout in seconds for each shell command (default: 30).
• operator.treat_exit_code_1_as_success: When true (default), commands that exit with code 1 are treated as success and their output is returned (e.g. git diff with no changes). When false, exit code 1 is reported as an error. Useful if you want strict failure detection for all commands.

Example in config.yaml:

operator:
  max_steps: 10
  confirm_medium_risk: true
  denylist:
    - "rm -rf"
    - "sudo"
    - "mkfs"
  allowlist: []   # leave empty to allow any command not on denylist
  command_timeout_seconds: 30
  treat_exit_code_1_as_success: true   # default: git diff with no changes (exit 1) is not an error

Use an Alternative Configuration File

gaia --config /path/to/custom/config.yaml ask "Hello!"
# or
GAIA_CONFIG=/path/to/custom/config.yaml gaia ask "Hello!"

Usage

Basic Commands

# Ask a question
gaia ask "What is the meaning of life?"

# Ask with piped input