aia 0.9.24 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9592d9ea1bbbbdc04f92dc822cfbdae91c1e04084530583e50f6cdb8a90460d
-  data.tar.gz: 897e53ec02de0fcc46a0e5ddcf15ca13a462b7cc20e4f355950f5872e5b04f00
+  metadata.gz: 07ebe0842c8ba2a8d1a24a072066564fe83954157b272b3c02ba07f86ce6e8c9
+  data.tar.gz: 8e0e9f0b7963bed6db571e0670cedc38e4c540efca48c2b0d8ffe69545c4ba48
 SHA512:
-  metadata.gz: 5e8b63a8ca892346e4dd1090ef487e4fc6dc6b9395238ecc6208128d8908a5dca87d730a9193a15b05dbb005b8d9eb84e2bb7f63100982130eeec69e0bb9483d
-  data.tar.gz: 660c1c40117300223a7bd88c67ec826225a44ada72d459ee6c8fd3e3c015e81a7874a9618220c4dc7caf3de930ee140d29ef1c7c8dfc205ecfeedef8e629b36a
+  metadata.gz: e248f19290dc0f2b0cb132c952e1d6a3e50cc3bf8435a2cfad5a8f7e342790a0bb23a958eee2c50bb993a0943f273b30df1e72be03ca29b929789f3885c27e17
+  data.tar.gz: 18985b3f3348e6ed359bd5920ef44b675976ca09c40aa6e9abb17950b9260f682df0fb16a15f673e958b0cc6f2300669e92ba90b925ec73fc0620a7577863baa

data/.version

@@ -1 +1 @@
-0.9.24
+0.10.2

data/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
-## [Unreleased]
+## [0.10.2] - 2025-12-25
+
+**Merry Christmas!**
+
+### Breaking Changes
+- **Renamed `--metrics` to `--tokens`**: The CLI flag for displaying token usage has been renamed
+  - `--metrics` → `--tokens`
+  - Environment variable: `AIA_FLAGS__TOKENS`
+  - The `--cost` flag now automatically enables `--tokens`
+
+### New Features
+- **Parallel MCP Connections**: Replaced serial MCP server connections with fiber-based parallel execution using SimpleFlow
+  - MCP servers now connect concurrently instead of sequentially
+  - Total connection time reduced from sum(timeouts) to max(timeouts)
+  - Added `simple_flow` gem dependency for lightweight pipeline-based concurrency
+
+### Improvements
+- **MCP Failure Feedback**: Added per-server error messages when MCP connections fail
+  - Users now see which specific server failed and why (e.g., "⚠️  MCP: 'iMCP' failed - Connection timed out")
+  - Previously only showed generic timeout message without identifying the failing server
+
+### Bug Fixes
+- **Ruby 4.0 Compatibility**: Fixed `NameError` in `lib/extensions/ruby_llm/modalities.rb`
+  - Added `require 'ruby_llm'` before extending `RubyLLM::Model::Modalities`
+  - Resolves "uninitialized constant RubyLLM" error on Ruby 4.0.0-preview2
+
+### Technical Changes
+- Added `simple_flow` gem dependency to gemspec
+- Refactored MCP connection code in `lib/aia/ruby_llm_adapter.rb`:
+  - Added `support_mcp_with_simple_flow` method using SimpleFlow::Pipeline
+  - Added `build_mcp_connection_step`, `register_single_mcp_client`, `extract_mcp_results`, `report_mcp_connection_results` helper methods
+  - Removed old serial methods: `support_mcp_lazy`, `register_mcp_clients`, `start_mcp_clients`, `reconcile_mcp_server_status`, `check_mcp_client_status`
+  - Net reduction of ~60 lines of code with cleaner architecture
+
+### Documentation
+- **Multi-Model Concurrent Comparison**: Added prominent documentation highlighting the ability to query multiple LLMs simultaneously
+  - Added "Concurrent Multi-Model Comparison" spotlight section to README.md
+  - Added "Token Usage and Cost Tracking" subsection to Multi-Model Support in README.md
+  - Added comprehensive "Token Usage and Cost Tracking" section to `docs/guides/models.md`
+- **Token and Cost Flags**: Added documentation for `--tokens` and `--cost` flags
+  - Updated `docs/cli-reference.md` with full flag descriptions
+  - Updated `docs/configuration.md` with environment variable examples
+  - Added "Token Usage and Cost Tracking" section to `docs/guides/chat.md`
+  - Updated README.md Key Command-Line Options and Configuration tables
+
+## [0.10.0] - 2025-12-23
+
+### Breaking Changes
+- **Environment Variable Naming Convention**: Updated to use nested naming with double underscore (`__`)
+  - `AIA_PROMPTS_DIR` → `AIA_PROMPTS__DIR`
+  - `AIA_OUT_FILE` → `AIA_OUTPUT__FILE`
+  - `AIA_VERBOSE` → `AIA_FLAGS__VERBOSE`
+  - `AIA_DEBUG` → `AIA_FLAGS__DEBUG`
+  - `AIA_CHAT` → `AIA_FLAGS__CHAT`
+  - `AIA_TEMPERATURE` → `AIA_LLM__TEMPERATURE`
+  - `AIA_MARKDOWN` → `AIA_OUTPUT__MARKDOWN`
+  - Note: `AIA_MODEL` remains unchanged (top-level, not nested)
+
+### Bug Fixes
+- **MCP Tool Timeout Handling**: Fixed issue where MCP tool timeouts corrupted conversation history
+  - Added `repair_incomplete_tool_calls` method to add synthetic tool results when timeouts occur
+  - Prevents "assistant message with 'tool_calls' must be followed by tool messages" API errors
+  - Conversation can now continue gracefully after tool timeouts
+
+- **Tool Crash Handling**: Fixed crash when tools throw non-StandardError exceptions (e.g., LoadError)
+  - Changed `rescue StandardError` to `rescue Exception` to catch all error types
+  - Added `handle_tool_crash` method that logs errors with 5-line traceback
+  - Tool crashes no longer crash AIA - conversation continues gracefully
 
 ## [0.9.24] 2025-12-17
 ### Fixes
@@ -12,6 +79,20 @@
   - Shows "No tools match the filter: [filter]" when no matches found
   - Header indicates when filtering is active: "Available Tools (filtered by 'filter')"
 
+### Documentation
+- Updated all shell completion scripts (`aia_completion.bash`, `aia_completion.zsh`, `aia_completion.fish`) to use new nested naming convention
+- Updated `docs/configuration.md` with comprehensive environment variable documentation
+- Updated `docs/cli-reference.md` environment variables section
+- Updated `docs/prompt_management.md` with correct envar names
+- Updated `docs/faq.md` with correct envar names
+- Updated `docs/guides/basic-usage.md` shell setup examples
+
+### Technical Changes
+- Enhanced `lib/aia/ruby_llm_adapter.rb`:
+  - Added `repair_incomplete_tool_calls` method for conversation integrity
+  - Added `handle_tool_crash` method for graceful error handling
+  - Removed debug statements
+
 ## [0.9.23] 2025-12-06
 
 ### New Features
@@ -178,7 +259,7 @@ Now with the fix:
 ### Usage Examples
 ```bash
 # Multi-model chat now properly isolates each model's context
-bin/aia --chat --model lms/openai/gpt-oss-20b,ollama/gpt-oss:20b --metrics
+bin/aia --chat --model lms/openai/gpt-oss-20b,ollama/gpt-oss:20b --tokens
 
 > pick a random language and say hello
 # LMS: "Habari!" (Swahili)
@@ -313,7 +394,7 @@ aia --model ollama/llama3.2 --chat
 
 ## [0.9.13] 2025-09-02
 ### New Features
-- **NEW FEATURE**: Added `--metrics` flag to show token counts for each model
+- **NEW FEATURE**: Added `--tokens` flag to show token counts for each model
 - **NEW FEATURE**: Added `--cost` flag to enable cost estimation for each model
 
 ### Improvements

data/README.md

@@ -5,6 +5,20 @@
   <p>Check out the new <a href="http://madbomber.github.io/aia/guides/models/?h=inline+role+syntax#inline-role-syntax">Inline Role Syntax</a> when working with multiple concurrent models.</p>
 </div>
 
+---
+
+> ## ⚠️ BREAKING CHANGES IN v0.10.0 ⚠️
+>
+> **Version 0.10.0 will introduce breaking changes affecting:**
+>
+> - **Environment Variables** — Naming conventions for system environment variables will change
+> - **Configuration Files** — Both the content format and structure of configuration files will be updated
+> - **File Locations** — Expected locations for configuration files will change
+>
+> **Please review the migration guide (coming soon) before upgrading to v0.10.0.**
+
+---
+
 AIA is a command-line utility that facilitates interaction with AI models through dynamic prompt management. It automates the management of pre-compositional prompts and executes generative AI commands with enhanced features including embedded directives, shell integration, embedded Ruby, history management, interactive chat, and prompt workflows.
 
 AIA leverages the following Ruby gems:
@@ -65,6 +79,47 @@ For more information on AIA visit these locations:
 
 ```
 
+---
+
+## Concurrent Multi-Model Comparison
+
+One of AIA's most powerful features is the ability to send a single prompt to multiple AI models simultaneously and compare their responses side-by-side—complete with token usage and cost tracking.
+
+```bash
+# Compare responses from 3 models with token counts and cost estimates
+aia --chat -m gpt-4o,claude-3-5-sonnet,gemini-1.5-pro --tokens --cost
+```
+
+**Example output:**
+```
+You: What's the best approach for handling database migrations in a microservices architecture?
+
+from: gpt-4o
+Use a versioned migration strategy with backward compatibility...
+
+from: claude-3-5-sonnet
+Consider the Expand-Contract pattern for zero-downtime migrations...
+
+from: gemini-1.5-pro
+Implement a schema registry with event-driven synchronization...
+
+┌─────────────────────────────────────────────────────────────────┐
+│ Model               │ Input Tokens │ Output Tokens │ Cost      │
+├─────────────────────────────────────────────────────────────────┤
+│ gpt-4o              │ 156          │ 342           │ $0.0089   │
+│ claude-3-5-sonnet   │ 156          │ 418           │ $0.0063   │
+│ gemini-1.5-pro      │ 156          │ 387           │ $0.0041   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Why this matters:**
+- **Compare reasoning approaches** - See how different models tackle the same problem
+- **Identify blind spots** - One model might catch something others miss
+- **Cost optimization** - Find the best price/performance ratio for your use case
+- **Consensus building** - Use `--consensus` to synthesize the best answer from all models
+
+---
+
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
 ## Table of Contents
@@ -190,7 +245,7 @@ aia --chat [--role ROLE] [--model MODEL]
 aia --model gpt-4 my_prompt
 
 # Specify output file
-aia --out_file result.md my_prompt
+aia --output result.md my_prompt
 
 # Use a role/system prompt
 aia --role expert my_prompt
@@ -209,8 +264,10 @@ aia --fuzzy
 | `--no-consensus` | Force individual responses | `aia --no-consensus` |
 | `--role ROLE` | Use a role/system prompt (default for all models) | `aia --role expert` |
 | `--list-roles` | List available role files | `aia --list-roles` |
-| `--out_file FILE` | Specify output file | `aia --out_file results.md` |
+| `--output FILE` | Specify output file | `aia --output results.md` |
 | `--fuzzy` | Use fuzzy search for prompts | `aia --fuzzy` |
+| `--tokens` | Display token usage in chat mode | `aia --chat --tokens` |
+| `--cost` | Include cost calculations with token usage | `aia --chat --cost` |
 | `--help` | Show complete help | `aia --help` |
 
 ### Directory Structure
@@ -235,7 +292,7 @@ The most commonly used configuration options:
 |--------|---------|-------------|
 | `model` | `gpt-4o-mini` | AI model to use |
 | `prompts_dir` | `~/.prompts` | Directory containing prompts |
-| `out_file` | `temp.md` | Default output file |
+| `output` | `temp.md` | Default output file |
 | `temperature` | `0.7` | Model creativity (0.0-1.0) |
 | `chat` | `false` | Start in chat mode |
 
@@ -254,8 +311,8 @@ AIA determines configuration settings using this order (highest to lowest priori
 **Environment Variables:**
 ```bash
 export AIA_MODEL=gpt-4
-export AIA_PROMPTS_DIR=~/my-prompts
-export AIA_TEMPERATURE=0.8
+export AIA_PROMPTS__DIR=~/my-prompts
+export AIA_LLM__TEMPERATURE=0.8
 ```
 
 **Configuration File** (`~/.aia/config.yml`):
@@ -283,48 +340,50 @@ Your prompt content here...
 |------------------|-------------|---------------|---------------------|
 | adapter | --adapter | ruby_llm | AIA_ADAPTER |
 | aia_dir | | ~/.aia | AIA_DIR |
-| append | -a, --append | false | AIA_APPEND |
-| chat | --chat | false | AIA_CHAT |
-| clear | --clear | false | AIA_CLEAR |
-| config_file | -c, --config_file | ~/.aia/config.yml | AIA_CONFIG_FILE |
-| debug | -d, --debug | false | AIA_DEBUG |
-| embedding_model | --em, --embedding_model | text-embedding-ada-002 | AIA_EMBEDDING_MODEL |
-| erb | | true | AIA_ERB |
-| frequency_penalty | --frequency_penalty | 0.0 | AIA_FREQUENCY_PENALTY |
-| fuzzy | -f, --fuzzy | false | AIA_FUZZY |
-| image_quality | --iq, --image_quality | standard | AIA_IMAGE_QUALITY |
-| image_size | --is, --image_size | 1024x1024 | AIA_IMAGE_SIZE |
-| image_style | --style, --image_style | vivid | AIA_IMAGE_STYLE |
-| log_file | -l, --log_file | ~/.prompts/_prompts.log | AIA_LOG_FILE |
-| markdown | --md, --markdown | true | AIA_MARKDOWN |
-| max_tokens | --max_tokens | 2048 | AIA_MAX_TOKENS |
+| append | -a, --append | false | AIA_FLAGS__APPEND |
+| chat | --chat | false | AIA_FLAGS__CHAT |
+| clear | --clear | false | AIA_FLAGS__CLEAR |
+| config_file | -c, --config-file | ~/.aia/config.yml | AIA_CONFIG_FILE |
+| debug | -d, --debug | false | AIA_FLAGS__DEBUG |
+| embedding_model | --em, --embedding_model | text-embedding-ada-002 | AIA_LLM__EMBEDDING_MODEL |
+| erb | | true | AIA_FLAGS__ERB |
+| frequency_penalty | --frequency-penalty | 0.0 | AIA_LLM__FREQUENCY_PENALTY |
+| fuzzy | -f, --fuzzy | false | AIA_FLAGS__FUZZY |
+| image_quality | --iq, --image-quality | standard | AIA_IMAGE__QUALITY |
+| image_size | --is, --image-size | 1024x1024 | AIA_IMAGE__SIZE |
+| image_style | --style, --image-style | vivid | AIA_IMAGE__STYLE |
+| history_file | --history-file | ~/.prompts/_prompts.log | AIA_OUTPUT__HISTORY_FILE |
+| markdown | --md, --markdown | true | AIA_OUTPUT__MARKDOWN |
+| max_tokens | --max-tokens | 2048 | AIA_LLM__MAX_TOKENS |
 | model | -m, --model | gpt-4o-mini | AIA_MODEL |
 | next | -n, --next | nil | AIA_NEXT |
-| out_file | -o, --out_file | temp.md | AIA_OUT_FILE |
-| parameter_regex | --regex | '(?-mix:(\[[A-Z _\|]+\]))' | AIA_PARAMETER_REGEX |
+| output | -o, --output | temp.md | AIA_OUTPUT__FILE |
+| parameter_regex | --regex | '(?-mix:(\[[A-Z _\|]+\]))' | AIA_PROMPTS__PARAMETER_REGEX |
 | pipeline | --pipeline | [] | AIA_PIPELINE |
-| presence_penalty | --presence_penalty | 0.0 | AIA_PRESENCE_PENALTY |
-| prompt_extname | | .txt | AIA_PROMPT_EXTNAME |
-| prompts_dir | -p, --prompts_dir | ~/.prompts | AIA_PROMPTS_DIR |
-| refresh | --refresh | 7 (days) | AIA_REFRESH |
+| presence_penalty | --presence-penalty | 0.0 | AIA_LLM__PRESENCE_PENALTY |
+| prompt_extname | | .txt | AIA_PROMPTS__EXTNAME |
+| prompts_dir | --prompts-dir | ~/.prompts | AIA_PROMPTS__DIR |
+| refresh | --refresh | 7 (days) | AIA_REGISTRY__REFRESH |
 | require_libs | --rq --require | [] | AIA_REQUIRE_LIBS |
 | role | -r, --role | | AIA_ROLE |
-| roles_dir | | ~/.prompts/roles | AIA_ROLES_DIR |
-| roles_prefix | --roles_prefix | roles | AIA_ROLES_PREFIX |
-| shell | | true | AIA_SHELL |
-| speak | --speak | false | AIA_SPEAK |
-| speak_command | | afplay | AIA_SPEAK_COMMAND |
-| speech_model | --sm, --speech_model | tts-1 | AIA_SPEECH_MODEL |
-| system_prompt | --system_prompt | | AIA_SYSTEM_PROMPT |
-| temperature | -t, --temperature | 0.7 | AIA_TEMPERATURE |
-| terse | --terse | false | AIA_TERSE |
-| tool_paths | --tools | [] | AIA_TOOL_PATHS |
-| allowed_tools | --at --allowed_tools | nil | AIA_ALLOWED_TOOLS |
-| rejected_tools | --rt --rejected_tools | nil | AIA_REJECTED_TOOLS |
-| top_p | --top_p | 1.0 | AIA_TOP_P |
-| transcription_model | --tm, --transcription_model | whisper-1 | AIA_TRANSCRIPTION_MODEL |
-| verbose | -v, --verbose | false | AIA_VERBOSE |
-| voice | --voice | alloy | AIA_VOICE |
+| roles_dir | | ~/.prompts/roles | AIA_ROLES__DIR |
+| roles_prefix | --roles-prefix | roles | AIA_ROLES__PREFIX |
+| shell | | true | AIA_FLAGS__SHELL |
+| speak | --speak | false | AIA_FLAGS__SPEAK |
+| speak_command | | afplay | AIA_SPEECH__COMMAND |
+| speech_model | --sm, --speech-model | tts-1 | AIA_SPEECH__MODEL |
+| system_prompt | --system-prompt | | AIA_SYSTEM_PROMPT |
+| temperature | -t, --temperature | 0.7 | AIA_LLM__TEMPERATURE |
+| terse | --terse | false | AIA_FLAGS__TERSE |
+| tokens | --tokens | false | AIA_FLAGS__TOKENS |
+| cost | --cost | false | AIA_FLAGS__COST |
+| tool_paths | --tools | [] | AIA_TOOLS__PATHS |
+| allowed_tools | --at, --allowed-tools | nil | AIA_TOOLS__ALLOWED |
+| rejected_tools | --rt, --rejected-tools | nil | AIA_TOOLS__REJECTED |
+| top_p | --top-p | 1.0 | AIA_LLM__TOP_P |
+| transcription_model | --tm, --transcription-model | whisper-1 | AIA_TRANSCRIPTION__MODEL |
+| verbose | -v, --verbose | false | AIA_FLAGS__VERBOSE |
+| voice | --voice | alloy | AIA_SPEECH__VOICE |
 
 </details>
 
@@ -566,6 +625,39 @@ Model Details:
 - **Error Handling**: Invalid models are reported but don't prevent valid models from working
 - **Batch Mode Support**: Multi-model responses are properly formatted in output files
 
+#### Token Usage and Cost Tracking
+
+Monitor token consumption and estimate costs across all models with `--tokens` and `--cost`:
+
+```bash
+# Display token usage for each model
+aia my_prompt -m gpt-4o,claude-3-sonnet --tokens
+
+# Include cost estimates (automatically enables --tokens)
+aia my_prompt -m gpt-4o,claude-3-sonnet --cost
+
+# In chat mode with full tracking
+aia --chat -m gpt-4o,claude-3-sonnet,gemini-pro --cost
+```
+
+**Token Usage Output:**
+```
+from: gpt-4o
+Here's my analysis of the code...
+
+from: claude-3-sonnet
+Looking at this code, I notice...
+
+Tokens: gpt-4o: input=245, output=312 | claude-3-sonnet: input=245, output=287
+Cost: gpt-4o: $0.0078 | claude-3-sonnet: $0.0045 | Total: $0.0123
+```
+
+**Use Cases for Token/Cost Tracking:**
+- **Budget management** - Monitor API costs in real-time during development
+- **Model comparison** - Identify which models are most cost-effective for your tasks
+- **Optimization** - Find the right balance between response quality and cost
+- **Billing insights** - Track usage patterns across different model providers
+
 ### Local Model Support
 
 AIA supports running local AI models through Ollama and LM Studio, providing privacy, offline capability, and cost savings.
@@ -721,7 +813,7 @@ Provide comprehensive background information.
 
 **analyze.txt:**
 ```
-//config out_file = analysis.md
+//config output = analysis.md
 //next summarize
 
 Analyze the research data and identify key insights.
@@ -729,7 +821,7 @@ Analyze the research data and identify key insights.
 
 **summarize.txt:**
 ```
-//config out_file = summary.md
+//config output = summary.md
 
 Create a concise summary of the analysis with actionable recommendations.
 ```
@@ -897,8 +989,8 @@ aia --tools ~/my-tools/ --chat
 aia --tools weather.rb,calculator.rb --chat
 
 # Filter tools
-aia --tools ~/tools/ --allowed_tools weather,calc
-aia --tools ~/tools/ --rejected_tools deprecated
+aia --tools ~/tools/ --allowed-tools weather,calc
+aia --tools ~/tools/ --rejected-tools deprecated
 ```
 
 **Tool Examples** (see `examples/tools/` directory):
@@ -1180,13 +1272,13 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo --consensus
 
 The `--exec` flag is used to create executable prompts.  If it is not present on the shebang line then the prompt file will be treated like any other context file.  That means that the file will be included as context in the prompt but no dynamic content integration or directives will be processed. All other AIA options are, well, optional.  All you need is an initial prompt ID and the --exec flag.
 
-In the example below the option `--no-out_file` is used to direct the output from the LLM processing of the prompt to STDOUT.  This way the executable prompts can be good citizens on the *nix command line receiving piped in input via STDIN and send its output to STDOUT.
+In the example below the option `--no-output` is used to direct the output from the LLM processing of the prompt to STDOUT.  This way the executable prompts can be good citizens on the *nix command line receiving piped in input via STDIN and send its output to STDOUT.
 
 Create executable prompts:
 
 **weather_report** (make executable with `chmod +x`):
 ```bash
-#!/usr/bin/env aia run --no-out_file --exec
+#!/usr/bin/env aia run --no-output --exec
 # Get current storm activity for the east and south coast of the US
 
 Summarize the tropical storm outlook fpr the Atlantic, Caribbean Sea and Gulf of America.
@@ -1222,13 +1314,13 @@ Usage: `aia ad_hoc` - perfect for any quick one-shot question without cluttering
 #### Recommended Shell Setup
 ```bash
 # ~/.bashrc_aia
-export AIA_PROMPTS_DIR=~/.prompts
-export AIA_OUT_FILE=./temp.md
+export AIA_PROMPTS__DIR=~/.prompts
+export AIA_OUTPUT__FILE=./temp.md
 export AIA_MODEL=gpt-4o-mini
-export AIA_VERBOSE=true  # Shows spinner while waiting for LLM response
+export AIA_FLAGS__VERBOSE=true  # Shows spinner while waiting for LLM response
 
 alias chat='aia --chat --terse'
-ask() { echo "$1" | aia run --no-out_file; }
+ask() { echo "$1" | aia run --no-output; }
 ```
 
 The `chat` alias and the `ask` function (shown above in HASH) are two powerful tools for interacting with the AI assistant. The `chat` alias allows you to engage in an interactive conversation with the AI assistant, while the `ask` function allows you to ask a question and receive a response. Later in this document the `run` prompt ID is discussed.  Besides using the run prompt ID here its also used in making executable prompt files.
@@ -1287,7 +1379,7 @@ chmod 600 ~/.prompts/*.txt
 **Prompt not found:**
 ```bash
 # Check prompts directory
-ls $AIA_PROMPTS_DIR
+ls $AIA_PROMPTS__DIR
 
 # Verify prompt file exists
 ls ~/.prompts/my_prompt.txt
@@ -1299,7 +1391,7 @@ aia --fuzzy
 **Model errors:**
 ```bash
 # List available models
-aia --available_models
+aia --available-models
 
 # Check model name spelling
 aia --model gpt-4o  # Correct
@@ -1327,27 +1419,55 @@ aia --debug --config
 | Error | Cause | Solution |
 |-------|-------|----------|
 | "Prompt not found" | Missing prompt file | Check file exists and spelling |
-| "Model not available" | Invalid model name | Use `--available_models` to list valid models |
+| "Model not available" | Invalid model name | Use `--available-models` to list valid models |
 | "Shell command failed" | Invalid shell syntax | Test shell commands separately first |
 | "Configuration error" | Invalid config syntax | Check config file YAML syntax |
 
-### Debug Mode
+### Debug Mode and Log Level Options
+
+AIA provides multiple log level options to control the verbosity of logging output. These options set the log level for all three loggers:
+- **aia**: Used within the AIA codebase for application-level logging
+- **llm**: Passed to the RubyLLM gem's configuration (`RubyLLM.logger`)
+- **mcp**: Passed to the RubyLLM::MCP process (`RubyLLM::MCP.logger`)
 
-Enable debug output for troubleshooting:
+| Option | Description |
+|--------|-------------|
+| `-d, --debug` | Enable debug output (most verbose) and set all loggers to DEBUG level |
+| `--no-debug` | Disable debug output |
+| `--info` | Set all loggers to INFO level |
+| `--warn` | Set all loggers to WARN level (default) |
+| `--error` | Set all loggers to ERROR level |
+| `--fatal` | Set all loggers to FATAL level (least verbose) |
 
 ```bash
-# Enable debug mode
+# Enable debug mode (most verbose - shows all log messages)
 aia --debug my_prompt
 
 # Combine with verbose for maximum output
 aia --debug --verbose my_prompt
+
+# Use info level for moderate logging
+aia --info my_prompt
+
+# Use error level to only see errors and fatal messages
+aia --error my_prompt
+
+# Use fatal level for minimal logging (only critical errors)
+aia --fatal --chat
 ```
 
+**Log Level Hierarchy** (from most to least verbose):
+1. **debug** - All messages including detailed debugging information
+2. **info** - Informational messages and above
+3. **warn** - Warnings, errors, and fatal messages (default)
+4. **error** - Only errors and fatal messages
+5. **fatal** - Only critical/fatal messages
+
 ### Performance Issues
 
 **Slow model responses:**
 - Try smaller/faster models: `--model gpt-4o-mini`
-- Reduce max_tokens: `--max_tokens 1000`
+- Reduce max_tokens: `--max-tokens 1000`
 - Use lower temperature for faster responses: `--temperature 0.1`
 
 **Large prompt processing:**

data/bin/aia

@@ -3,4 +3,10 @@
 
 require_relative '../lib/aia'
 
+# Handle Ctrl-C gracefully
+Signal.trap('INT') do
+  warn "\nInterrupted. Exiting..."
+  exit 130
+end
+
 AIA.run