aia 0.9.24 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9592d9ea1bbbbdc04f92dc822cfbdae91c1e04084530583e50f6cdb8a90460d
-  data.tar.gz: 897e53ec02de0fcc46a0e5ddcf15ca13a462b7cc20e4f355950f5872e5b04f00
+  metadata.gz: b583dae0c86c40fc70dc5d71e39cc6781283e93af38a5773bfcfe92fbbdb9c65
+  data.tar.gz: ed7b710bee9a484c1f25bf450a2bcfb7ed1db701a5962a9829bc7f9404c0b370
 SHA512:
-  metadata.gz: 5e8b63a8ca892346e4dd1090ef487e4fc6dc6b9395238ecc6208128d8908a5dca87d730a9193a15b05dbb005b8d9eb84e2bb7f63100982130eeec69e0bb9483d
-  data.tar.gz: 660c1c40117300223a7bd88c67ec826225a44ada72d459ee6c8fd3e3c015e81a7874a9618220c4dc7caf3de930ee140d29ef1c7c8dfc205ecfeedef8e629b36a
+  metadata.gz: c00641d58b7feda9cb3930561857fd203fa7f623137e4758e87193e3528106a173a0faf1e12a57fe2dd326d6506ba4e26d4d7c33c1eda90e58ee6bd3fca4d947
+  data.tar.gz: b9707f94782fc48566da722b1144a7e60d90f6a8b1507e4ccb5148cd84cccbe088b066e176893500caf052cf295cfe3c20a1c80415eb2623d42180b270ae7e52

data/.envrc

@@ -2,3 +2,10 @@ source_up
 
 export RR=`pwd`
 # PATH_add $RR/bin
+
+# see aia --help for --model option
+#   The format of a "model" is [provider/]model_name[=roll_id]
+#   where provider and roll_id are optional
+#   Use a comma to seperate the models in a multi-model setup
+#
+# export AIA_MODEL=claude-haiku-4-5,gpt-4o-mini

data/.version

@@ -1 +1 @@
-0.9.24
+0.11.0

data/CHANGELOG.md

@@ -1,5 +1,121 @@
 # Changelog
-## [Unreleased]
+## [0.11.0] - 2026-02-02
+
+### New Features
+- **`--list-tools` CLI Option**: List all available tools and exit
+  - Shows tools loaded via `--require` and `--tools` options
+  - Dual-mode output: plain text (word-wrapped, 3-sentence summaries) for terminal, full markdown with nested headings when STDOUT is redirected to a file or pipe
+  - Combine with `--mcp-list` to also initialize and list tools from MCP servers, grouped by source
+  - Example: `aia --require shared_tools --list-tools > tools.md`
+
+- **`--mcp-list` Filtering**: `--mcp-list` now respects `--mcp-use` and `--mcp-skip` filters
+  - When filters are active, header changes from "Configured MCP Servers" to "Active MCP Servers"
+  - Shows only the servers that would actually be connected during a session
+
+- **`--mcp-use` and `--mcp-skip` Server Selection**: Select or exclude specific MCP servers by name
+  - `--mcp-use server1,server2` - whitelist specific servers (takes precedence)
+  - `--mcp-skip server3` - blacklist specific servers
+
+- **Multi-Model Environment Variable Support**: `AIA_MODEL` now supports inline role syntax
+  - Example: `export AIA_MODEL="gpt-4o=architect,claude=security"`
+
+### Breaking Changes
+- **Removed `--adapter` CLI Option**: The LLM adapter configuration has been removed
+  - AIA now exclusively uses `ruby_llm` as its AI interface layer
+  - The `ai_client` adapter option is no longer available
+
+### Improvements
+- **CLI Refactoring**: Streamlined CLI option names and improved help text
+  - Cleaner option grouping and descriptions in `--help` output
+
+### Documentation
+- **`--list-tools` and `--mcp-list`**: Added comprehensive documentation to `docs/cli-reference.md` with examples, output format tables, and usage patterns
+- **README.md**: Added `--mcp-list` and `--list-tools` to Key Command-Line Options table
+- **MCP Integration Guide**: Updated `docs/mcp-integration.md` with current CLI syntax and examples
+- **Shared Tools Guide**: Created dedicated `docs/guides/shared-tools.md` with all 17 tools organized by category (Data & Analysis, Database, File & System Operations, Web & Network, Code Execution, Documents, Scheduling & Time, Workflow & Weather, Development & Reference)
+- **MkDocs Navigation**: Added Shared Tools guide to site navigation
+
+### Technical Changes
+- Added `list_tools` attribute to `AIA::Config` for runtime flag storage
+- Added `--list-tools` option to CLI parser in `setup_tool_options`
+- Added `handle_list_tools` to `ConfigValidator` with dual-mode output (terminal vs redirected)
+- Added `load_local_tools` with gem activation and Zeitwerk lazy-loading support for `--require` libraries
+- Added `load_mcp_tools_grouped` returning tools organized by server name
+- Added `quiet_mcp_logger` to suppress MCP connection noise during tool listing
+- Added `filter_mcp_servers` and `mcp_filter_active?` to `ConfigValidator` for `--mcp-use`/`--mcp-skip` support
+- Added `nest_markdown_headings` to properly nest markdown headings in tool descriptions under parent heading level
+- Added `first_sentences` helper for terminal-mode description truncation
+- Uses `word_wrapper` gem for terminal word wrapping
+- Removed adapter selection logic and `--adapter` CLI option
+
+## [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 +128,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 +308,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 +443,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,22 @@
   <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.* ⚠️
+>
+> **Version 0.10.0 introduces breaking changes affecting:**
+>
+> - **Environment Variables** — Naming conventions now use double underscore (`__`) for nested config sections (e.g., `AIA_LLM__TEMPERATURE`, `AIA_FLAGS__DEBUG`). See [Environment Variables](https://madbomber.github.io/aia/configuration/#environment-variables) for the complete list.
+>
+> - **Configuration Files** — Configuration now uses a nested YAML structure with sections like `llm:`, `prompts:`, `output:`, `flags:`, etc. The [defaults.yml](lib/aia/config/defaults.yml) file is the single source of truth for all configuration options. See [Configuration Guide](https://madbomber.github.io/aia/configuration/) for details.
+>
+> - **File Locations** — Configuration files now follow the XDG Base Directory Specification. The default config file location is `~/.config/aia/aia.yml`. See [Installation Guide](https://madbomber.github.io/aia/installation/) for setup instructions.
+>
+> **Review the [Configuration Guide](https://madbomber.github.io/aia/configuration/) 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 +81,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 +247,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 +266,12 @@ 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` |
+| `--mcp-list` | List configured MCP servers and exit | `aia --mcp-list` |
+| `--list-tools` | List available tools and exit | `aia --require shared_tools --list-tools` |
 | `--help` | Show complete help | `aia --help` |
 
 ### Directory Structure
@@ -235,7 +296,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 +315,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 +344,52 @@ 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 |
+| mcp_use | --mu, --mcp-use | ~ | AIA_MCP_USE |
+| mcp_skip | --ms, --mcp-skip | ~ | AIA_MCP_SKIP |
+| 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 +631,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 +819,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 +827,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 +995,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 +1278,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 +1320,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 +1385,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 +1397,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 +1425,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