aia 2.0.0.0.pre.alpha → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (236) hide show
  1. checksums.yaml +4 -4
  2. data/.version +1 -1
  3. data/CHANGELOG.md +151 -228
  4. data/README.md +42 -19
  5. data/bin/aia +8 -3
  6. data/lib/aia/aia_completion.bash +2 -3
  7. data/lib/aia/aia_completion.fish +6 -5
  8. data/lib/aia/aia_completion.zsh +2 -3
  9. data/lib/aia/chat_loop.rb +24 -66
  10. data/lib/aia/config/cli_parser.rb +164 -123
  11. data/lib/aia/config/defaults.yml +12 -39
  12. data/lib/aia/config/mcp_parser.rb +42 -40
  13. data/lib/aia/config/model_spec.rb +8 -14
  14. data/lib/aia/config/validator.rb +144 -156
  15. data/lib/aia/config/value_caster.rb +76 -0
  16. data/lib/aia/config.rb +72 -54
  17. data/lib/aia/content_extractor.rb +2 -0
  18. data/lib/aia/cost_calculator.rb +1 -0
  19. data/lib/aia/crew.rb +29 -19
  20. data/lib/aia/debate_handler.rb +45 -20
  21. data/lib/aia/delegate_handler.rb +7 -3
  22. data/lib/aia/directive.rb +10 -8
  23. data/lib/aia/directives/configuration_directives.rb +164 -109
  24. data/lib/aia/directives/context_directives.rb +55 -40
  25. data/lib/aia/directives/execution_directives.rb +25 -25
  26. data/lib/aia/directives/model_directives.rb +112 -195
  27. data/lib/aia/directives/trakflow_directives.rb +27 -9
  28. data/lib/aia/directives/utility_directives.rb +86 -87
  29. data/lib/aia/directives/web_and_file_directives.rb +83 -63
  30. data/lib/aia/fact_asserter.rb +3 -3
  31. data/lib/aia/history_transfer.rb +64 -24
  32. data/lib/aia/layered_orchestrator.rb +66 -43
  33. data/lib/aia/logger.rb +27 -62
  34. data/lib/aia/mcp_config_normalizer.rb +27 -14
  35. data/lib/aia/mcp_connection_manager.rb +193 -186
  36. data/lib/aia/mcp_discovery.rb +43 -15
  37. data/lib/aia/mcp_grouper.rb +2 -1
  38. data/lib/aia/mcp_server_config.rb +48 -0
  39. data/lib/aia/mcp_utility.rb +28 -20
  40. data/lib/aia/mention_router.rb +22 -52
  41. data/lib/aia/modality_query.rb +36 -0
  42. data/lib/aia/model_alias_registry.rb +11 -11
  43. data/lib/aia/model_registry.rb +75 -0
  44. data/lib/aia/network_builder.rb +17 -11
  45. data/lib/aia/network_memory_manager.rb +6 -6
  46. data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
  47. data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
  48. data/lib/aia/pipeline_orchestrator.rb +88 -45
  49. data/lib/aia/plugin_monitor.rb +9 -6
  50. data/lib/aia/prompt_decomposer.rb +6 -4
  51. data/lib/aia/prompt_handler.rb +90 -69
  52. data/lib/aia/provider_registry.rb +105 -0
  53. data/lib/aia/robot_builder.rb +1 -1
  54. data/lib/aia/robot_factory.rb +77 -69
  55. data/lib/aia/robot_namer.rb +2 -8
  56. data/lib/aia/robot_sync.rb +79 -0
  57. data/lib/aia/role_catalog.rb +89 -0
  58. data/lib/aia/session.rb +32 -14
  59. data/lib/aia/session_tracker.rb +39 -41
  60. data/lib/aia/similarity_scorer.rb +5 -3
  61. data/lib/aia/skill_utils.rb +60 -19
  62. data/lib/aia/spawn_handler.rb +16 -4
  63. data/lib/aia/spawn_spec_parser.rb +6 -7
  64. data/lib/aia/special_mode_handler.rb +80 -57
  65. data/lib/aia/speech.rb +103 -0
  66. data/lib/aia/startup_coordinator.rb +17 -91
  67. data/lib/aia/streaming_runner.rb +16 -5
  68. data/lib/aia/system_prompt_assembler.rb +20 -15
  69. data/lib/aia/task_board.rb +60 -0
  70. data/lib/aia/task_coordinator.rb +10 -5
  71. data/lib/aia/timing.rb +15 -0
  72. data/lib/aia/tool_approver.rb +205 -0
  73. data/lib/aia/tool_filter.rb +1 -9
  74. data/lib/aia/tool_filter_strategy.rb +39 -25
  75. data/lib/aia/tool_introspection.rb +25 -0
  76. data/lib/aia/tool_loader.rb +71 -31
  77. data/lib/aia/tool_utility.rb +6 -5
  78. data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
  79. data/lib/aia/tools/recruit_robot_tool.rb +12 -12
  80. data/lib/aia/tools/reskill_robot_tool.rb +7 -7
  81. data/lib/aia/tools/task_board_tool.rb +17 -16
  82. data/lib/aia/trakflow_bridge.rb +19 -11
  83. data/lib/aia/turn_state.rb +32 -8
  84. data/lib/aia/ui_presenter.rb +83 -59
  85. data/lib/aia/utility.rb +8 -24
  86. data/lib/aia/variable_input_collector.rb +1 -3
  87. data/lib/aia/verification_network.rb +10 -12
  88. data/lib/aia.rb +49 -8
  89. metadata +27 -162
  90. data/.better-commits.json +0 -150
  91. data/.config/tocer/configuration.yml +0 -6
  92. data/.envrc +0 -15
  93. data/.loki +0 -231
  94. data/.quality/flay_baseline.txt +0 -1
  95. data/.quality/flog_baseline.txt +0 -29
  96. data/.quality/reek_baseline.txt +0 -80
  97. data/.rubocop.yml +0 -116
  98. data/COMMITS.md +0 -196
  99. data/IMPLEMENTATION_PLAN.md +0 -506
  100. data/Rakefile +0 -160
  101. data/architecture_review.md +0 -314
  102. data/docs/AGENTS.md +0 -40
  103. data/docs/advanced-prompting.md +0 -814
  104. data/docs/assets/images/aia.png +0 -0
  105. data/docs/cli-reference.md +0 -1241
  106. data/docs/configuration.md +0 -747
  107. data/docs/contributing.md +0 -386
  108. data/docs/directives-reference.md +0 -1145
  109. data/docs/examples/index.md +0 -277
  110. data/docs/examples/mcp/index.md +0 -475
  111. data/docs/examples/prompts/analysis/index.md +0 -78
  112. data/docs/examples/prompts/automation/index.md +0 -109
  113. data/docs/examples/prompts/development/index.md +0 -125
  114. data/docs/examples/prompts/index.md +0 -333
  115. data/docs/examples/prompts/learning/index.md +0 -127
  116. data/docs/examples/prompts/writing/index.md +0 -62
  117. data/docs/examples/tools/index.md +0 -282
  118. data/docs/faq.md +0 -578
  119. data/docs/guides/available-models.md +0 -366
  120. data/docs/guides/basic-usage.md +0 -478
  121. data/docs/guides/chat.md +0 -680
  122. data/docs/guides/crew.md +0 -239
  123. data/docs/guides/executable-prompts.md +0 -331
  124. data/docs/guides/first-prompt.md +0 -454
  125. data/docs/guides/getting-started.md +0 -455
  126. data/docs/guides/image-generation.md +0 -507
  127. data/docs/guides/index.md +0 -48
  128. data/docs/guides/local-models.md +0 -306
  129. data/docs/guides/migrate-prompts.md +0 -335
  130. data/docs/guides/models.md +0 -1017
  131. data/docs/guides/shared-tools.md +0 -254
  132. data/docs/guides/tools.md +0 -831
  133. data/docs/index.md +0 -259
  134. data/docs/installation.md +0 -274
  135. data/docs/mcp-integration.md +0 -603
  136. data/docs/prompt_management.md +0 -665
  137. data/docs/security.md +0 -674
  138. data/docs/special_projects_guide.md +0 -386
  139. data/docs/tools-and-mcp-examples.md +0 -1211
  140. data/docs/workflows-and-pipelines.md +0 -636
  141. data/examples/.gitignore +0 -2
  142. data/examples/00_setup_aia.sh +0 -111
  143. data/examples/01_basic_usage.sh +0 -23
  144. data/examples/02_frontmatter.sh +0 -33
  145. data/examples/03_shell_integration.sh +0 -55
  146. data/examples/04_erb_templating.sh +0 -56
  147. data/examples/05_shell_then_erb.sh +0 -38
  148. data/examples/06_prompt_chaining.sh +0 -59
  149. data/examples/07_pipeline.sh +0 -46
  150. data/examples/08_context_files.sh +0 -43
  151. data/examples/09_roles.sh +0 -67
  152. data/examples/10_stdin_piping.sh +0 -49
  153. data/examples/11_multi_model.sh +0 -65
  154. data/examples/12_token_usage.sh +0 -52
  155. data/examples/13_cost_tracking.sh +0 -68
  156. data/examples/14_output_file.sh +0 -91
  157. data/examples/15_parameters.sh +0 -68
  158. data/examples/16_directives.sh +0 -113
  159. data/examples/17_require_and_conditionals.sh +0 -68
  160. data/examples/18_tools.sh +0 -61
  161. data/examples/19_local_tools.sh +0 -34
  162. data/examples/20_mcp_servers.sh +0 -102
  163. data/examples/21_executable_prompts.sh +0 -78
  164. data/examples/22_chat_mode.sh +0 -217
  165. data/examples/23_verify.sh +0 -139
  166. data/examples/24_decompose.sh +0 -139
  167. data/examples/25_spawn.sh +0 -139
  168. data/examples/26_debate.sh +0 -97
  169. data/examples/27_mention_routing.sh +0 -157
  170. data/examples/28_model_switching.sh +0 -106
  171. data/examples/29_agent_harness.sh +0 -177
  172. data/examples/README.md +0 -321
  173. data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
  174. data/examples/aia_config.yml +0 -22
  175. data/examples/aia_config_orchestrator.yml +0 -45
  176. data/examples/aia_config_with_mcp.yml +0 -21
  177. data/examples/common.sh +0 -39
  178. data/examples/context/project_goals.md +0 -6
  179. data/examples/context/tech_stack.md +0 -7
  180. data/examples/directives/timestamp_directive.rb +0 -22
  181. data/examples/mcp/filesystem.json +0 -9
  182. data/examples/prompts_dir/analyze.md +0 -2
  183. data/examples/prompts_dir/brainstorm.md +0 -2
  184. data/examples/prompts_dir/conditional.md +0 -17
  185. data/examples/prompts_dir/creative.md +0 -4
  186. data/examples/prompts_dir/erbinfo.md +0 -5
  187. data/examples/prompts_dir/erbinfo_raw.md +0 -8
  188. data/examples/prompts_dir/evaluate.md +0 -2
  189. data/examples/prompts_dir/explain_joke.md +0 -1
  190. data/examples/prompts_dir/explain_recursion.md +0 -1
  191. data/examples/prompts_dir/fun_fact +0 -3
  192. data/examples/prompts_dir/greeting.md +0 -8
  193. data/examples/prompts_dir/greeting_required.md +0 -7
  194. data/examples/prompts_dir/hello.md +0 -1
  195. data/examples/prompts_dir/includes/ruby_facts.md +0 -4
  196. data/examples/prompts_dir/limerick.md +0 -1
  197. data/examples/prompts_dir/list_with_mcp.md +0 -3
  198. data/examples/prompts_dir/pick_best.md +0 -2
  199. data/examples/prompts_dir/project_summary +0 -12
  200. data/examples/prompts_dir/quiz_with_include.md +0 -6
  201. data/examples/prompts_dir/require_demo.md +0 -5
  202. data/examples/prompts_dir/roles/formal.md +0 -3
  203. data/examples/prompts_dir/roles/orchestrator.md +0 -21
  204. data/examples/prompts_dir/roles/pirate.md +0 -3
  205. data/examples/prompts_dir/shell_then_erb.md +0 -6
  206. data/examples/prompts_dir/sort_compare.md +0 -2
  207. data/examples/prompts_dir/summarize_context.md +0 -2
  208. data/examples/prompts_dir/sysinfo.md +0 -5
  209. data/examples/prompts_dir/sysinfo_raw.md +0 -8
  210. data/examples/prompts_dir/tagline.md +0 -1
  211. data/examples/prompts_dir/tell_joke.md +0 -1
  212. data/examples/prompts_dir/tell_joke_with_next.md +0 -4
  213. data/examples/prompts_dir/use_local_tool.md +0 -8
  214. data/examples/prompts_dir/use_tools.md +0 -8
  215. data/examples/prompts_dir/weather.md +0 -2
  216. data/examples/prompts_dir/whats_new.md +0 -2
  217. data/examples/prompts_dir/with_timestamp.md +0 -5
  218. data/examples/requirements/sinatra_taskflow_app.md +0 -139
  219. data/examples/rules/01_classify_ruby.rb +0 -16
  220. data/examples/rules/02_prefer_claude_for_code.rb +0 -19
  221. data/examples/rules/03_gate_prompt_length.rb +0 -19
  222. data/examples/rules/04_tool_selection.rb +0 -41
  223. data/examples/rules/README.md +0 -30
  224. data/examples/run_all.sh +0 -294
  225. data/examples/tools/word_count_tool.rb +0 -30
  226. data/lib/AGENTS.md +0 -57
  227. data/lib/aia/model_switch_handler.rb +0 -100
  228. data/mcp_servers/README.md +0 -110
  229. data/mcp_servers/apple-mcp.json +0 -8
  230. data/mcp_servers/filesystem.json +0 -9
  231. data/mcp_servers/mcp_server_chart.json +0 -11
  232. data/mcp_servers/playwright_one.json +0 -8
  233. data/mcp_servers/playwright_server_definition.json +0 -9
  234. data/mcp_servers/playwright_two.json +0 -8
  235. data/mcp_servers/tavily_mcp_server.json +0 -8
  236. data/mkdocs.yml +0 -169
@@ -1,1241 +0,0 @@
1
- <!-- Tocer[start]: Auto-generated, don't remove. -->
2
-
3
- ## Table of Contents
4
-
5
- - [CLI Reference](#cli-reference)
6
- - [Usage Patterns](#usage-patterns)
7
- - [Mode Options](#mode-options)
8
- - [`--chat`](#--chat)
9
- - [`-f, --fuzzy`](#-f---fuzzy)
10
- - [`--terse`](#--terse)
11
- - [`--tokens`](#--tokens)
12
- - [`--cost`](#--cost)
13
- - [`--mcp FILE`](#--mcp-file)
14
- - [`--no-mcp`](#--no-mcp)
15
- - [`--mcp-list`](#--mcp-list)
16
- - [`--mu`, `--mcp-use NAMES`](#--mu---mcp-use-names)
17
- - [`--ms`, `--mcp-skip NAMES`](#--ms---mcp-skip-names)
18
- - [Adapter Options](#adapter-options)
19
- - [`--available-models [QUERY]`](#--available-models-query)
20
- - [Model Options](#model-options)
21
- - [`-m MODEL, --model MODEL`](#-m-model---model-model)
22
- - [`--[no-]consensus`](#--no-consensus)
23
- - [`-s, --skill SKILL_IDS`](#-s---skill-skill_ids)
24
- - [`--list-skills`](#--list-skills)
25
- - [`--skills-dir DIR`](#--skills-dir-dir)
26
- - [`--skills-prefix PREFIX`](#--skills-prefix-prefix)
27
- - [`--sm, --speech-model MODEL`](#--sm---speech-model-model)
28
- - [`--tm, --transcription-model MODEL`](#--tm---transcription-model-model)
29
- - [File Options](#file-options)
30
- - [`-c, --config-file FILE`](#-c---config-file-file)
31
- - [`-o, --[no-]output [FILE]`](#-o---no-output-file)
32
- - [`-a, --[no-]append`](#-a---no-append)
33
- - [`--[no-]history-file [FILE]`](#--no-history-file-file)
34
- - [`--md, --[no-]markdown`](#--md---no-markdown)
35
- - [Prompt Options](#prompt-options)
36
- - [`--prompts-dir DIR`](#--prompts-dir-dir)
37
- - [`--roles-prefix PREFIX`](#--roles-prefix-prefix)
38
- - [`-r, --role ROLE_ID`](#-r---role-role_id)
39
- - [`--list-roles`](#--list-roles)
40
- - [`--skills-prefix PREFIX`](#--skills-prefix-prefix-1)
41
- - [`-s, --skill SKILL_IDS`](#-s---skill-skill_ids-1)
42
- - [`--list-skills`](#--list-skills-1)
43
- - [`-n, --next PROMPT_ID`](#-n---next-prompt_id)
44
- - [`-p PROMPTS, --pipeline PROMPTS`](#-p-prompts---pipeline-prompts)
45
- - [`--system-prompt PROMPT_ID`](#--system-prompt-prompt_id)
46
- - [`--regex PATTERN`](#--regex-pattern)
47
- - [AI Parameters](#ai-parameters)
48
- - [`-t, --temperature TEMP`](#-t---temperature-temp)
49
- - [`--max-tokens TOKENS`](#--max-tokens-tokens)
50
- - [`--top-p VALUE`](#--top-p-value)
51
- - [`--frequency-penalty VALUE`](#--frequency-penalty-value)
52
- - [`--presence-penalty VALUE`](#--presence-penalty-value)
53
- - [Audio/Image Options](#audioimage-options)
54
- - [`--speak`](#--speak)
55
- - [`--voice VOICE`](#--voice-voice)
56
- - [`--is, --image-size SIZE`](#--is---image-size-size)
57
- - [`--iq, --image-quality QUALITY`](#--iq---image-quality-quality)
58
- - [`--style, --image-style STYLE`](#--style---image-style-style)
59
- - [Tool Options](#tool-options)
60
- - [`--rq LIBS, --require LIBS`](#--rq-libs---require-libs)
61
- - [`--tools PATH_LIST`](#--tools-path_list)
62
- - [`--at, --allowed-tools TOOLS_LIST`](#--at---allowed-tools-tools_list)
63
- - [`--rt, --rejected-tools TOOLS_LIST`](#--rt---rejected-tools-tools_list)
64
- - [`--list-tools`](#--list-tools)
65
- - [Utility Options](#utility-options)
66
- - [Log Level Options](#log-level-options)
67
- - [`-d, --debug`](#-d---debug)
68
- - [`--no-debug`](#--no-debug)
69
- - [`--log-level LEVEL`](#--log-level-level)
70
- - [`--log-to FILE`](#--log-to-file)
71
- - [`-v, --[no-]verbose`](#-v---no-verbose)
72
- - [`--[no-]thinking`](#--no-thinking)
73
- - [`--refresh DAYS`](#--refresh-days)
74
- - [`--dump FILE`](#--dump-file)
75
- - [`--completion SHELL`](#--completion-shell)
76
- - [`--version`](#--version)
77
- - [`-h, --help`](#-h---help)
78
- - [Usage Examples](#usage-examples)
79
- - [Basic Examples](#basic-examples)
80
- - [Advanced Examples](#advanced-examples)
81
- - [Configuration Examples](#configuration-examples)
82
- - [Environment Variables](#environment-variables)
83
- - [Configuration Precedence](#configuration-precedence)
84
- - [Related Documentation](#related-documentation)
85
-
86
- <!-- Tocer[finish]: Auto-generated, don't remove. -->
87
-
88
- # CLI Reference
89
-
90
- Complete reference for all AIA command-line arguments, options, and flags.
91
-
92
- ## Usage Patterns
93
-
94
- ```bash
95
- # Basic usage
96
- aia [options] [PROMPT_ID] [CONTEXT_FILE]*
97
-
98
- # Chat mode
99
- aia --chat [PROMPT_ID] [CONTEXT_FILE]*
100
- aia --chat [CONTEXT_FILE]*
101
-
102
- # Show help
103
- aia --help
104
-
105
- # Show version
106
- aia --version
107
- ```
108
-
109
- ## Mode Options
110
-
111
- ### `--chat`
112
- Begin a chat session with the LLM after processing all prompts in the pipeline.
113
-
114
- ```bash
115
- aia --chat
116
- aia --chat system_prompt
117
- aia --chat my_prompt context.txt
118
- ```
119
-
120
- ### `-f, --fuzzy`
121
- Use fuzzy matching for prompt search (requires `fzf` to be installed).
122
-
123
- ```bash
124
- aia --fuzzy
125
- aia -f
126
- ```
127
-
128
- **Note**: If `fzf` is not installed, AIA will exit with an error.
129
-
130
- ### `--terse`
131
- **Deprecated.** Accepted for backward compatibility but has no effect.
132
-
133
- Formerly added a special instruction to the prompt asking the AI to keep responses short and to the point.
134
-
135
- ```bash
136
- aia --terse my_prompt
137
- aia --terse --chat
138
- ```
139
-
140
- ### `--tokens`
141
- Display token usage information after each response in chat mode. Shows input tokens, output tokens, and model ID.
142
-
143
- ```bash
144
- aia --chat --tokens
145
- aia --chat --tokens --model gpt-4
146
- ```
147
-
148
- ### `--cost`
149
- Include cost calculations with token usage. Automatically enables `--tokens`. Shows estimated cost based on the model's pricing.
150
-
151
- ```bash
152
- aia --chat --cost
153
- aia --chat --cost --model gpt-4,claude-3-sonnet
154
- ```
155
-
156
- **Note**: `--cost` implies `--tokens`, so you don't need to specify both.
157
-
158
- ### `--mcp FILE`
159
- Load an MCP (Model Context Protocol) server from a JSON configuration file. MCP servers provide additional tools and context to AI models. Multiple `--mcp` options can be used to load multiple servers.
160
-
161
- ```bash
162
- # Load a single MCP server
163
- aia --mcp ~/.config/aia/mcp/github.json my_prompt
164
-
165
- # Load multiple MCP servers
166
- aia --mcp github.json --mcp filesystem.json my_prompt
167
-
168
- # Combine with chat mode
169
- aia --chat --mcp ~/mcp-servers/memory.json
170
- ```
171
-
172
- **JSON file format**:
173
- ```json
174
- {
175
- "name": "github",
176
- "command": "github-mcp-server",
177
- "args": ["stdio"],
178
- "env": {
179
- "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
180
- },
181
- "timeout": 8000
182
- }
183
- ```
184
-
185
- ### `--no-mcp`
186
- Disable all MCP server processing, including servers defined in the configuration file.
187
-
188
- ```bash
189
- # Disable MCP server processing
190
- aia --no-mcp my_prompt
191
- ```
192
-
193
- **Use cases**:
194
- - Use `--no-mcp` when you want faster responses without MCP tool overhead
195
- - Use `--no-mcp` to temporarily bypass MCP servers configured in your config file
196
-
197
- ### `--mcp-list`
198
- List configured MCP servers and exit. Shows the server name and command for each server. Useful for verifying which servers are loaded from config files and `--mcp` options.
199
-
200
- When combined with `--mcp-use` or `--mcp-skip`, only the servers that pass the filter are shown. The header changes from "Configured" to "Active" to reflect this.
201
-
202
- When combined with `--list-tools`, MCP servers are started and their tools are included in the tool listing (see `--list-tools`).
203
-
204
- ```bash
205
- # List all servers from config file
206
- aia --mcp-list
207
-
208
- # List servers loaded from specific MCP JSON files
209
- aia --mcp github.json --mcp filesystem.json --mcp-list
210
-
211
- # List only the servers that would be active after filtering
212
- aia --mcp-list --mcp-use github,filesystem
213
-
214
- # List all configured servers except those skipped
215
- aia --mcp-list --mcp-skip playwright
216
-
217
- # Combine with --list-tools to show MCP tools grouped by server
218
- aia --mcp-list --list-tools
219
- aia --mcp-list --list-tools --mcp-use redis
220
- ```
221
-
222
- ### `--mu`, `--mcp-use NAMES`
223
- Only connect to the named MCP servers (whitelist). Server names are comma-separated and must match the `name` field in the server configuration.
224
-
225
- ```bash
226
- # Only use the github server
227
- aia --mcp-use github --chat
228
-
229
- # Only use github and filesystem servers
230
- aia --mcp-use github,filesystem --chat
231
-
232
- # Can be specified multiple times
233
- aia --mu github --mu filesystem --chat
234
- ```
235
-
236
- **Precedence**: `--no-mcp` overrides `--mcp-use`. If both `--mcp-use` and `--mcp-skip` are specified, `--mcp-use` takes precedence.
237
-
238
- ### `--ms`, `--mcp-skip NAMES`
239
- Skip the named MCP servers (blacklist). All other configured servers will still be connected.
240
-
241
- ```bash
242
- # Skip the playwright server
243
- aia --mcp-skip playwright --chat
244
-
245
- # Skip multiple servers
246
- aia --mcp-skip playwright,filesystem --chat
247
-
248
- # Can be specified multiple times
249
- aia --ms playwright --ms filesystem --chat
250
- ```
251
-
252
- **Precedence**: `--no-mcp` overrides `--mcp-skip`. If `--mcp-use` is also specified, `--mcp-skip` is ignored.
253
-
254
- ## Adapter Options
255
-
256
- ### `--available-models [QUERY]`
257
- List (then exit) available models that match the optional query. Query is a comma-separated list of AND components.
258
-
259
- ```bash
260
- # List all models
261
- aia --available-models
262
-
263
- # Filter by provider
264
- aia --available-models openai
265
-
266
- # Filter by capability and provider
267
- aia --available-models openai,mini
268
-
269
- # Filter by modality
270
- aia --available-models text_to_text
271
-
272
- # Complex filter
273
- aia --available-models openai,gpt,text_to_image
274
- ```
275
-
276
- ## Model Options
277
-
278
- ### `-m MODEL, --model MODEL`
279
- Name of the LLM model(s) to use. For multiple models, use comma-separated values.
280
-
281
- Supports inline role assignment using `MODEL=ROLE` syntax to assign specific roles to individual models.
282
-
283
- ```bash
284
- # Single model
285
- aia --model gpt-4 my_prompt
286
-
287
- # Multiple models (parallel processing)
288
- aia --model "gpt-4,claude-3-sonnet,gemini-pro" my_prompt
289
-
290
- # Short form
291
- aia -m gpt-3.5-turbo my_prompt
292
-
293
- # Single model with role (inline syntax)
294
- aia --model gpt-4o=architect design_review.md
295
-
296
- # Multiple models with different roles
297
- aia --model "gpt-4o=architect,claude=security,gemini=performance" my_prompt
298
-
299
- # Same model with multiple roles for diverse perspectives
300
- aia --model "gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist" project_plan.md
301
-
302
- # Mixed: some models with roles, some without
303
- aia --model "gpt-4o=expert,claude,gemini" my_prompt
304
- ```
305
-
306
- **See also**: `--role` for applying a role to all models, `--list-roles` for discovering available roles.
307
-
308
- ### `--[no-]consensus`
309
- Enable/disable consensus mode for multi-model responses. When enabled, AIA attempts to create a consensus response from multiple models.
310
-
311
- ```bash
312
- # Enable consensus mode (requires multiple models)
313
- aia --model "gpt-4,claude-3-sonnet" --consensus my_prompt
314
-
315
- # Disable consensus mode (default: show individual responses)
316
- aia --model "gpt-4,claude-3-sonnet" --no-consensus my_prompt
317
- ```
318
-
319
- ### `-s, --skill SKILL_IDS`
320
- Inject one or more skills into the prompt before it is sent to the AI. Skills are loaded from the skills directory (default: `~/.prompts/skills/`). Multiple skills can be specified as a comma-separated list, and the flag may be repeated.
321
-
322
- **Injection mode depends on `--chat`:**
323
-
324
- - **Chat mode** (`--chat`): skill content is appended to the system prompt once, so it persists across all turns without repetition.
325
- - **Pipeline mode** (default): skill content is appended to each individual prompt text, immediately after the role content.
326
-
327
- In both modes the assembled order is:
328
- ```
329
- Role content (who the LLM is)
330
- Skill content (how to approach the task)
331
- User prompt (what to do)
332
- ```
333
-
334
- Only the body of each `SKILL.md` is injected — the YAML front matter is stripped.
335
-
336
- ```bash
337
- # Single skill (ID-based — resolved from skills directory)
338
- aia --skill code-review my_prompt
339
- aia -s summarizer my_prompt
340
-
341
- # Path-based skill (relative, home-relative, or absolute path to a skill directory)
342
- aia --skill ./local-skills/code-review my_prompt
343
- aia --skill /shared/team-skills/security-audit my_prompt
344
- aia --skill ~/my-skills/custom-skill my_prompt
345
-
346
- # Combine with a role: role sets persona, skill sets method
347
- aia --role ruby_expert --skill code-review review_prompt my_code.rb
348
-
349
- # Multiple skills applied in order (comma-separated)
350
- aia --skill "code-review,security-audit" my_prompt
351
-
352
- # Repeatable form
353
- aia -s code-review -s security-audit my_prompt
354
- ```
355
-
356
- **Path resolution**: If a skill ID starts with `/`, `~/`, `./`, or `../`, it is treated as a filesystem path to a skill directory (which must contain `SKILL.md`). Otherwise it is looked up by ID in the skills directory.
357
-
358
- **See also**: `--list-skills` to discover available skills, `/skill` chat directive, `--role` for personality
359
-
360
- ### `--list-skills`
361
- List all available skills and exit. Skills are subdirectories under the skills directory, each containing a `SKILL.md` file with YAML front matter.
362
-
363
- ```bash
364
- aia --list-skills
365
-
366
- # With a custom skills directory
367
- aia --skills-dir ~/work/skills --list-skills
368
- ```
369
-
370
- **Example output**:
371
- ```markdown
372
- ## code-quality
373
-
374
- | Key | Value |
375
- |-----|-------|
376
- | name | code-quality |
377
- | description | Improve code quality through analysis and refactoring. |
378
- | user-invocable | true |
379
-
380
- ## summarizer
381
-
382
- | Key | Value |
383
- |-----|-------|
384
- | name | summarizer |
385
- | description | Summarize documents and conversations concisely. |
386
- ```
387
-
388
- Each skill is shown as a `## skill-name` heading followed by a table of all front matter fields from its `SKILL.md`.
389
-
390
- ### `--skills-dir DIR`
391
- Directory containing skill subdirectories (default: `~/.prompts/skills`). Each subdirectory must contain a `SKILL.md` file to be recognized as a skill.
392
-
393
- ```bash
394
- aia --skills-dir ~/work/skills --list-skills
395
- aia --skills-dir /shared/team-skills -s code-review my_prompt
396
- ```
397
-
398
- **Environment variable**: `AIA_SKILLS__DIR`
399
-
400
- ### `--skills-prefix PREFIX`
401
- Subdirectory name appended to the skills base to build the full skills path (default: none — unset). Affects `AIA.config.prompts.skills_prefix`.
402
-
403
- Path resolution when prefix is set:
404
- - If `--skills-dir` is also given: `skills-dir/prefix`
405
- - Otherwise: `prompts-dir/prefix` (using `--prompts-dir` or `AIA_PROMPTS__DIR`)
406
-
407
- ```bash
408
- aia --skills-prefix team-skills --list-skills
409
- # Looks for skills under ~/.prompts/team-skills/
410
-
411
- aia --skills-dir /shared --skills-prefix team-skills --list-skills
412
- # Looks for skills under /shared/team-skills/
413
- ```
414
-
415
- **Environment variable**: `AIA_PROMPTS__SKILLS_PREFIX`
416
-
417
- ### `--sm, --speech-model MODEL`
418
- Set the `SPEECH_MODEL` environment variable that AIA passes to the
419
- `speak_command`. AIA does not call any TTS API — this value is only meaningful
420
- if your `speak_command` script reads `$SPEECH_MODEL`.
421
-
422
- ```bash
423
- aia --speech-model tts-1 --speak my_prompt
424
- aia --sm tts-1-hd --speak my_prompt
425
- ```
426
-
427
- ### `--tm, --transcription-model MODEL`
428
- Transcription model to use for speech-to-text functionality.
429
-
430
- ```bash
431
- aia --transcription-model whisper-1 audio_file.wav
432
- aia --tm whisper-1 my_audio.mp3
433
- ```
434
-
435
- ## File Options
436
-
437
- ### `-c, --config-file FILE`
438
- Load configuration from a specific file.
439
-
440
- ```bash
441
- aia --config-file /path/to/config.yml my_prompt
442
- aia -c ~/.config/aia/custom_config.yml my_prompt
443
- ```
444
-
445
- ### `-o, --[no-]output [FILE]`
446
- Output file for saving AI responses.
447
-
448
- ```bash
449
- # Save to default file (temp.md)
450
- aia --output my_prompt
451
-
452
- # Save to specific file
453
- aia --output output.txt my_prompt
454
-
455
- # Use absolute path
456
- aia --output /tmp/ai_response.md my_prompt
457
-
458
- # Disable file output
459
- aia --no-output my_prompt
460
- ```
461
-
462
- ### `-a, --[no-]append`
463
- Append to output file instead of overwriting.
464
-
465
- ```bash
466
- # Append mode
467
- aia --output log.md --append my_prompt
468
-
469
- # Overwrite mode (default)
470
- aia --output log.md --no-append my_prompt
471
- ```
472
-
473
- ### `--[no-]history-file [FILE]`
474
- Path to the Reline readline history file used in `--chat` mode. Each chat session saves the raw follow-up inputs you typed so they can be recalled with the up-arrow key in future sessions. Up to 50 entries are kept; oldest entries are dropped first when the limit is reached. Has no effect in pipeline mode.
475
-
476
- **File content**: plain text, one user input per line — no timestamps, no AI responses, no prompt IDs.
477
-
478
- **Path resolution** (first match wins):
479
- 1. `FILE` supplied to this flag (or `AIA_OUTPUT__HISTORY_FILE` env var)
480
- 2. `<aia_dir>/chat_history` when `paths.aia_dir` is configured
481
- 3. `~/.config/aia/chat_history` (built-in default)
482
-
483
- **Large-file rotation**: when the history file exceeds an internal size threshold, the session renames it to `<file>.1` and starts a fresh file.
484
-
485
- ```bash
486
- # Use the default history file location
487
- aia --chat my_prompt
488
-
489
- # Use a custom history file
490
- aia --history-file ~/.aia_chat_history --chat my_prompt
491
-
492
- # Disable history entirely for this session
493
- aia --no-history-file --chat my_prompt
494
- ```
495
-
496
- **Environment variable**: `AIA_OUTPUT__HISTORY_FILE`
497
-
498
- ### `--md, --[no-]markdown`
499
- Format output with Markdown.
500
-
501
- ```bash
502
- # Enable Markdown formatting
503
- aia --markdown my_prompt
504
-
505
- # Disable Markdown formatting
506
- aia --no-markdown my_prompt
507
- ```
508
-
509
- ## Prompt Options
510
-
511
- ### `--prompts-dir DIR`
512
- Directory containing prompt files.
513
-
514
- ```bash
515
- aia --prompts-dir /custom/prompts my_prompt
516
- aia --prompts-dir ~/work/prompts my_prompt
517
- ```
518
-
519
- ### `--roles-prefix PREFIX`
520
- Subdirectory name for role files (default: `roles`).
521
-
522
- ```bash
523
- # Use custom roles directory
524
- aia --roles-prefix personas --role expert
525
-
526
- # Results in looking for roles in ~/.prompts/personas/expert.md
527
- ```
528
-
529
- ### `-r, --role ROLE_ID`
530
- Role ID to prepend to the prompt. This applies the same role to all models.
531
-
532
- For per-model role assignment, use the inline `MODEL=ROLE` syntax with `--model` instead.
533
-
534
- ```bash
535
- # Apply role by ID (resolved from roles directory)
536
- aia --role expert my_prompt
537
- aia -r teacher explain_concept
538
-
539
- # Path-based role (relative or absolute path to a .md file)
540
- aia --role ./local-roles/domain-expert my_prompt
541
- aia --role /shared/roles/security-auditor review.md
542
- aia --role ~/my-roles/custom-persona my_prompt
543
-
544
- # With multiple models (same role for all)
545
- aia --model "gpt-4,claude" --role architect design.md
546
-
547
- # Per-model roles (inline syntax - see --model)
548
- aia --model "gpt-4=architect,claude=security" design.md
549
- ```
550
-
551
- **Path resolution**: If `ROLE_ID` starts with `/`, `~/`, `./`, or `../`, it is treated as a filesystem path to a role `.md` file. The `.md` extension is added automatically when the path has no file extension. Otherwise the ID is resolved relative to the roles directory.
552
-
553
- **See also**: `--model` for inline role syntax, `--list-roles` for discovering available roles.
554
-
555
- ### `--list-roles`
556
- List all available roles and exit. Shows role IDs and their descriptions from the roles directory.
557
-
558
- ```bash
559
- # List all available roles
560
- aia --list-roles
561
-
562
- # Example output:
563
- # Available roles in /Users/you/.prompts/roles:
564
- # architect - Software architecture expert
565
- # security - Security analysis specialist
566
- # performance - Performance optimization expert
567
- # debugger - Expert debugging assistant
568
- # optimist - Positive perspective analyzer
569
- # pessimist - Critical risk analyzer
570
- # realist - Balanced pragmatic analyzer
571
- ```
572
-
573
- Roles are discovered from:
574
- - **Default location**: `~/.prompts/roles/`
575
- - **Custom location**: Set via `--prompts-dir` and `--roles-prefix`
576
- - **Nested directories**: Supports subdirectories like `roles/software/architect.md`
577
-
578
- **Use case**: Discover available roles before using them with `--role` or inline `MODEL=ROLE` syntax.
579
-
580
- **See also**: `--role`, `--model`, `--prompts-dir`, `--roles-prefix`
581
-
582
- ### `--skills-prefix PREFIX`
583
- Subdirectory name appended to the base path to form the skills directory (default: none — unset).
584
-
585
- When unset and no `--skills-dir` is given, skills are resolved from `~/.prompts/skills/`.
586
-
587
- ```bash
588
- # Use custom prefix under prompts-dir
589
- aia --skills-prefix capabilities --skill expert
590
- # Looks for ~/.prompts/capabilities/expert/SKILL.md
591
-
592
- # Use prefix under an explicit skills-dir
593
- aia --skills-dir /shared --skills-prefix team --skill expert
594
- # Looks for /shared/team/expert/SKILL.md
595
- ```
596
-
597
- ### `-s, --skill SKILL_IDS`
598
- One or more skill IDs to layer into the prompt after the role. Skills define *what the LLM does* in order to respond — they sit between the role (identity) and the user prompt in the assembled system prompt.
599
-
600
- Each skill ID is the name of a subdirectory under `skills.dir` that contains a `SKILL.md` file (e.g., skill `testing` → `~/.prompts/skills/testing/SKILL.md`).
601
-
602
- Accepts comma-separated values, multiple flags, or a combination of both:
603
-
604
- ```bash
605
- # Single skill
606
- aia --skill testing my_prompt
607
- aia -s testing my_prompt
608
-
609
- # Comma-separated
610
- aia --skill testing,debugging my_prompt
611
-
612
- # Repeatable flag
613
- aia --skill testing --skill debugging my_prompt
614
-
615
- # Combined
616
- aia --skill testing,debugging --skill refactoring my_prompt
617
-
618
- # With a role (system → role → skills → user)
619
- aia --role ruby_expert --skill testing --skill minitest my_prompt
620
- ```
621
-
622
- **Prompt assembly order** (first turn only):
623
- 1. System prompt (guardrails)
624
- 2. Role prompt (identity/personality)
625
- 3. Skill prompt(s) (capabilities, in declaration order)
626
- 4. User prompt
627
-
628
- Follow-up turns in chat mode include only the system prompt and the user message; role and skills are carried implicitly via conversation history.
629
-
630
- **See also**: `--role`, `--list-skills`, `--skills-prefix`
631
-
632
- ### `--list-skills`
633
- List all available skills and exit. A skill is a subdirectory of the skills directory that contains a `SKILL.md` file. Output is a formatted markdown document.
634
-
635
- ```bash
636
- # List all available skills
637
- aia --list-skills
638
-
639
- # Example output:
640
- #
641
- # ## debugging
642
- #
643
- # | Key | Value |
644
- # |-----|-------|
645
- # | name | debugging |
646
- # | description | Debug Ruby applications. |
647
- #
648
- # ## minitest
649
- #
650
- # | Key | Value |
651
- # |-----|-------|
652
- # | name | minitest |
653
- # | description | Write tests using Minitest. |
654
- ```
655
-
656
- Skills are discovered from:
657
- - **Default location**: `~/.prompts/skills/`
658
- - **Custom location**: Set via `--prompts-dir` and `--skills-prefix`
659
- - **Convention**: Each skill is a subdirectory containing a `SKILL.md` file; plain `.md` files and subdirectories without `SKILL.md` are ignored
660
- - **Output**: H2 heading per skill ID, followed by a two-column table of YAML front matter key/value pairs
661
-
662
- **See also**: `--skill`, `--skills-prefix`
663
-
664
- ### `-n, --next PROMPT_ID`
665
- Next prompt to process (can be used multiple times to build a pipeline).
666
-
667
- ```bash
668
- aia my_prompt --next second_prompt --next third_prompt
669
- aia -n analysis -n summary my_prompt
670
- ```
671
-
672
- ### `-p PROMPTS, --pipeline PROMPTS`
673
- Pipeline of comma-separated prompt IDs to process.
674
-
675
- ```bash
676
- aia --pipeline "analysis,summary,report" my_data
677
- aia -p "review,optimize,test" my_code.py
678
- ```
679
-
680
-
681
- ### `--system-prompt PROMPT_ID`
682
- System prompt ID to use for chat sessions.
683
-
684
- ```bash
685
- aia --system-prompt helpful_assistant --chat
686
- aia --system-prompt code_expert --chat my_code.py
687
- ```
688
-
689
- ### `--regex PATTERN`
690
- **Deprecated.** No longer used; prompt parameters use ERB syntax.
691
-
692
- ```bash
693
- aia --regex '\{\{(\w+)\}\}' my_template_prompt
694
- aia --regex '<%=\s*(\w+)\s*%>' erb_prompt
695
- ```
696
-
697
- ## AI Parameters
698
-
699
- ### `-t, --temperature TEMP`
700
- Temperature for text generation (0.0 to 2.0). Higher values make output more creative and random.
701
-
702
- ```bash
703
- # Conservative/focused
704
- aia --temperature 0.1 analysis_prompt
705
-
706
- # Balanced (default ~0.7)
707
- aia --temperature 0.7 my_prompt
708
-
709
- # Creative
710
- aia --temperature 1.5 creative_writing
711
-
712
- # Very creative
713
- aia -t 2.0 brainstorm_ideas
714
- ```
715
-
716
- ### `--max-tokens TOKENS`
717
- Maximum tokens for text generation.
718
-
719
- ```bash
720
- aia --max-tokens 100 short_summary
721
- aia --max-tokens 4000 detailed_analysis
722
- ```
723
-
724
- ### `--top-p VALUE`
725
- Top-p sampling value (0.0 to 1.0). Alternative to temperature for controlling randomness.
726
-
727
- ```bash
728
- aia --top-p 0.1 precise_answer
729
- aia --top-p 0.9 creative_response
730
- ```
731
-
732
- ### `--frequency-penalty VALUE`
733
- Frequency penalty (-2.0 to 2.0). Positive values discourage repetition.
734
-
735
- ```bash
736
- # Discourage repetition
737
- aia --frequency-penalty 0.5 my_prompt
738
-
739
- # Encourage repetition
740
- aia --frequency-penalty -0.5 my_prompt
741
- ```
742
-
743
- ### `--presence-penalty VALUE`
744
- Presence penalty (-2.0 to 2.0). Positive values encourage discussing new topics.
745
-
746
- ```bash
747
- # Encourage new topics
748
- aia --presence-penalty 0.5 broad_discussion
749
-
750
- # Focus on current topics
751
- aia --presence-penalty -0.5 deep_dive
752
- ```
753
-
754
- ## Audio/Image Options
755
-
756
- ### `--speak`
757
- After each AI response, AIA runs a three-stage pipeline with a progress spinner
758
- for each stage:
759
-
760
- | Stage | What happens | Spinner |
761
- |-------|-------------|---------|
762
- | 1. Generation | LLM streams text to the terminal | `Processing...` |
763
- | 2. Conversion | Text is converted to an audio file | `Converting to audio...` |
764
- | 3. Playback | Audio file is played | `Speaking...` |
765
-
766
- **Local TTS (default):** `say` converts and plays in one step, so stages 2 and 3
767
- share a single `Speaking...` spinner.
768
-
769
- ```bash
770
- aia --chat --speak my_prompt
771
- aia --speak --voice Samantha my_prompt
772
- ```
773
-
774
- **Custom TTS script (e.g. OpenAI TTS):** AIA calls the script with two
775
- arguments — the text (`$1`) and the path to write the audio file (`$2`) — then
776
- plays the resulting file with `afplay`. The script is responsible **only** for
777
- conversion; AIA handles playback and shows both spinners.
778
-
779
- AIA does **not** call any TTS API itself. A ready-made script for OpenAI TTS is
780
- installed at `~/.config/aia/tts.sh`:
781
-
782
- ```bash
783
- # ~/.config/aia/tts.sh — called as: tts.sh "text" /path/to/output.mp3
784
- #!/usr/bin/env bash
785
- model="${SPEECH_MODEL:-tts-1}"
786
- voice="${AIA_AUDIO__VOICE:-alloy}"
787
- curl -s https://api.openai.com/v1/audio/speech \
788
- -H "Authorization: Bearer $OPENAI_API_KEY" \
789
- -H "Content-Type: application/json" \
790
- -d "{\"model\": \"$model\", \"input\": $(printf '%s' "$1" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'), \"voice\": \"$voice\"}" \
791
- --output "$2"
792
- ```
793
-
794
- ```yaml
795
- # ~/.config/aia/aia.yml
796
- audio:
797
- speak_command: ~/.config/aia/tts.sh
798
- speech_model: tts-1-hd
799
- voice: nova
800
- ```
801
-
802
- Or entirely from the CLI:
803
-
804
- ```bash
805
- aia --chat --speak \
806
- --speak-command ~/.config/aia/tts.sh \
807
- --speech-model tts-1-hd \
808
- --voice nova \
809
- my_prompt
810
- ```
811
-
812
- ### `--voice VOICE`
813
- Voice name passed to the `speak_command`.
814
-
815
- For macOS `say` (default), specify a macOS voice name (run `say -v '?'` to list
816
- available voices):
817
-
818
- ```bash
819
- aia --voice Samantha --speak my_prompt
820
- aia --voice Alex --speak my_prompt
821
- ```
822
-
823
- For a custom OpenAI TTS script, use an OpenAI voice name instead:
824
-
825
- ```bash
826
- aia --voice alloy --speak my_prompt
827
- aia --voice nova --speak my_prompt
828
- ```
829
-
830
- ### `--is, --image-size SIZE`
831
- Image size for image generation.
832
-
833
- ```bash
834
- aia --image-size 1024x1024 image_prompt
835
- aia --is 1792x1024 wide_image
836
- aia --is 1024x1792 tall_image
837
- ```
838
-
839
- **Common sizes**: `256x256`, `512x512`, `1024x1024`, `1792x1024`, `1024x1792`
840
-
841
- ### `--iq, --image-quality QUALITY`
842
- Image quality for image generation.
843
-
844
- ```bash
845
- aia --image-quality standard image_prompt
846
- aia --iq hd high_quality_image
847
- ```
848
-
849
- **Values**: `standard`, `hd`
850
-
851
- ### `--style, --image-style STYLE`
852
- Style for image generation.
853
-
854
- ```bash
855
- aia --image-style vivid colorful_image
856
- aia --style natural realistic_image
857
- ```
858
-
859
- **Values**: `vivid`, `natural`
860
-
861
- ## Tool Options
862
-
863
- ### `--rq LIBS, --require LIBS`
864
- Ruby libraries to require for Ruby directive execution.
865
-
866
- ```bash
867
- aia --require json,csv data_processing_prompt
868
- aia --rq "net/http,uri" web_request_prompt
869
- ```
870
-
871
- ### `--tools PATH_LIST`
872
- Add tool file(s) or directories. Comma-separated paths.
873
-
874
- ```bash
875
- # Single tool file
876
- aia --tools ./my_tool.rb my_prompt
877
-
878
- # Multiple tools
879
- aia --tools "./tool1.rb,./tool2.rb" my_prompt
880
-
881
- # Tool directory
882
- aia --tools ./tools/ my_prompt
883
-
884
- # Mixed paths
885
- aia --tools "./tools/,./special_tool.rb" my_prompt
886
- ```
887
-
888
- ### `--at, --allowed-tools TOOLS_LIST`
889
- Allow only these tools to be used. Security feature to restrict tool access.
890
-
891
- ```bash
892
- # Allow specific tools
893
- aia --allowed-tools "calculator,file_reader" my_prompt
894
- aia --at "web_scraper,data_analyzer" analysis_prompt
895
- ```
896
-
897
- ### `--rt, --rejected-tools TOOLS_LIST`
898
- Reject/block these tools from being used.
899
-
900
- ```bash
901
- # Block dangerous tools
902
- aia --rejected-tools "file_writer,system_command" my_prompt
903
- aia --rt "network_access" secure_prompt
904
- ```
905
-
906
- ### `--list-tools`
907
- List available tools and exit. Loads tools from `--require` and `--tools` options, then displays each tool's name and description.
908
-
909
- When combined with `--mcp-list`, MCP servers are also started and their tools are included in the output, grouped by server.
910
-
911
- **Output format depends on where stdout is directed:**
912
-
913
- | Output | Format | Descriptions |
914
- |--------|--------|-------------|
915
- | Terminal | Plain text, word-wrapped | First 3 sentences |
916
- | File/pipe | Markdown with headings | Full description |
917
-
918
- The markdown output uses `#` for the title, `##` for source sections (Local Tools, MCP server groups), and `###` for individual tool names. Any markdown headings within a tool's description are automatically adjusted to nest under the tool's heading level.
919
-
920
- ```bash
921
- # List local tools loaded via --require
922
- aia --require shared_tools --list-tools
923
-
924
- # List local tools loaded from a file path
925
- aia --tools ./my_tools/ --list-tools
926
-
927
- # Combine --require and --tools
928
- aia --require shared_tools --tools ./extras/ --list-tools
929
-
930
- # Include MCP server tools (requires --mcp-list)
931
- aia --require shared_tools --mcp-list --list-tools
932
-
933
- # Include only specific MCP servers
934
- aia --require shared_tools --mcp-list --mcp-use redis --list-tools
935
-
936
- # Redirect to a markdown file
937
- aia --require shared_tools --mcp-list --list-tools > tools.md
938
-
939
- # Pipe to a markdown renderer
940
- aia --require shared_tools --list-tools | glow -
941
- ```
942
-
943
- **Example terminal output:**
944
- ```
945
- Local Tools:
946
-
947
- calculator
948
- Perform advanced mathematical calculations with comprehensive
949
- error handling and validation. This tool supports basic arithmetic
950
- operations, parentheses, and common mathematical functions.
951
-
952
- weather_tool
953
- Retrieve comprehensive current weather information for any city
954
- worldwide using the OpenWeatherMap API. This tool provides real-time
955
- weather data including temperature, atmospheric conditions, humidity,
956
- and wind information.
957
- ```
958
-
959
- **Example markdown output (when redirected):**
960
- ```markdown
961
- # Available Tools
962
-
963
- > 20 tools from 2 sources
964
-
965
- ## Local Tools (15)
966
-
967
- ### `calculator`
968
-
969
- Perform advanced mathematical calculations with comprehensive error
970
- handling and validation. This tool supports basic arithmetic operations,
971
- parentheses, and common mathematical functions. ...full description...
972
-
973
- ## MCP: redis (5)
974
-
975
- ### `set`
976
-
977
- Set a Redis string value with an optional expiration time. ...full description...
978
- ```
979
-
980
- ## Utility Options
981
-
982
- ### Log Level Options
983
-
984
- AIA provides multiple log level options to control logging verbosity. These options set the log level for all three loggers:
985
- - **aia**: Used within the AIA codebase for application-level logging
986
- - **llm**: Passed to the RubyLLM gem's configuration (`RubyLLM.logger`)
987
- - **mcp**: Passed to the RubyLLM::MCP process (`RubyLLM::MCP.logger`)
988
-
989
- Only one log level option should be used at a time.
990
-
991
- ### `-d, --debug`
992
- Enable debug output (most verbose) and set all loggers to DEBUG level. Also sets `$DEBUG_ME = true` for the debug_me gem.
993
-
994
- ```bash
995
- aia --debug my_prompt
996
- aia -d --chat
997
- ```
998
-
999
- ### `--no-debug`
1000
- Explicitly disable debug output. Sets `$DEBUG_ME = false`.
1001
-
1002
- ```bash
1003
- aia --no-debug my_prompt
1004
- ```
1005
-
1006
- ### `--log-level LEVEL`
1007
- Set all loggers to the specified level. Only `--debug` / `--no-debug` exist as standalone flags; all other levels are set via this option.
1008
-
1009
- Valid values for LEVEL: `debug`, `info`, `warn`, `error`, `fatal`
1010
-
1011
- ```bash
1012
- aia --log-level info my_prompt
1013
- aia --log-level warn --chat
1014
- aia --log-level error my_prompt
1015
- aia --log-level fatal my_prompt
1016
- ```
1017
-
1018
- ### `--log-to FILE`
1019
- Redirect all logger output to FILE instead of STDOUT.
1020
-
1021
- ```bash
1022
- aia --log-to /var/log/aia.log my_prompt
1023
- aia --log-to ~/aia_debug.log --debug --chat
1024
- ```
1025
-
1026
- **Log Level Hierarchy** (from most to least verbose):
1027
- 1. `debug` - All messages including detailed debugging information (use `--debug` / `--no-debug`)
1028
- 2. `info` - Informational messages and above
1029
- 3. `warn` - Warnings, errors, and fatal messages (default)
1030
- 4. `error` - Only errors and fatal messages
1031
- 5. `fatal` - Only critical/fatal messages
1032
-
1033
- ### `-v, --[no-]verbose`
1034
- Enable/disable verbose output.
1035
-
1036
- ```bash
1037
- # Verbose mode
1038
- aia --verbose my_prompt
1039
- aia -v my_prompt
1040
-
1041
- # Quiet mode
1042
- aia --no-verbose my_prompt
1043
- ```
1044
-
1045
- ### `--[no-]thinking`
1046
- Show or hide raw thinking/reasoning blocks in the output. Default: **off**.
1047
-
1048
- Some local reasoning models (e.g. `qwen3` on Ollama) emit their chain-of-thought
1049
- wrapped in `<think>...</think>` tags as part of the streamed response. By default
1050
- AIA filters these blocks out so you only see the final answer. Pass `--thinking`
1051
- to display the reasoning as well.
1052
-
1053
- ```bash
1054
- # Show the model's reasoning
1055
- aia --chat --thinking -m ollama/qwen3:latest
1056
-
1057
- # Explicitly hide it (the default)
1058
- aia --chat --no-thinking -m ollama/qwen3:latest
1059
- ```
1060
-
1061
- Equivalent config key: `flags.thinking` (env: `AIA_FLAGS__THINKING`).
1062
-
1063
- ### `--refresh DAYS`
1064
- Refresh models database interval in days.
1065
-
1066
- ```bash
1067
- # Refresh immediately
1068
- aia --refresh 0
1069
-
1070
- # Refresh weekly
1071
- aia --refresh 7
1072
-
1073
- # Refresh monthly
1074
- aia --refresh 30
1075
- ```
1076
-
1077
- ### `--dump FILE`
1078
- Dump current configuration to a file for inspection or backup.
1079
-
1080
- ```bash
1081
- aia --dump current_config.yaml
1082
- aia --dump /tmp/aia_config_backup.yml
1083
- ```
1084
-
1085
- ### `--completion SHELL`
1086
- Show completion script for shell integration.
1087
-
1088
- ```bash
1089
- # Bash completion
1090
- aia --completion bash > ~/.bash_completion.d/aia
1091
-
1092
- # Zsh completion
1093
- aia --completion zsh > ~/.zsh/completions/_aia
1094
-
1095
- # Fish completion
1096
- aia --completion fish > ~/.config/fish/completions/aia.fish
1097
- ```
1098
-
1099
- **Supported shells**: `bash`, `zsh`, `fish`
1100
-
1101
- ### `--version`
1102
- Show AIA version and exit.
1103
-
1104
- ```bash
1105
- aia --version
1106
- ```
1107
-
1108
- ### `-h, --help`
1109
- Show help message and exit.
1110
-
1111
- ```bash
1112
- aia --help
1113
- aia -h
1114
- ```
1115
-
1116
- ## Usage Examples
1117
-
1118
- ### Basic Examples
1119
-
1120
- ```bash
1121
- # Simple prompt execution
1122
- aia hello_world
1123
-
1124
- # Chat mode
1125
- aia --chat
1126
-
1127
- # Use specific model
1128
- aia --model gpt-4 code_review my_script.py
1129
-
1130
- # Fuzzy prompt selection
1131
- aia --fuzzy
1132
- ```
1133
-
1134
- ### Advanced Examples
1135
-
1136
- ```bash
1137
- # Multi-model consensus
1138
- aia --model "gpt-4,claude-3-sonnet" --consensus analysis_prompt data.csv
1139
-
1140
- # Creative writing with voice output
1141
- aia --model gpt-4 --temperature 1.2 --speak --voice nova story_prompt
1142
-
1143
- # Secure tool usage
1144
- aia --tools ./safe_tools/ --allowed-tools "calculator,file_reader" --rejected-tools "system_command" analysis_prompt
1145
-
1146
- # Pipeline with custom configuration
1147
- aia --pipeline "extract,analyze,summarize" --temperature 0.3 --max-tokens 2000 --output report.md data_source.txt
1148
-
1149
- # Debug mode with verbose output
1150
- aia --debug --verbose --model claude-3-sonnet problematic_prompt
1151
- ```
1152
-
1153
- ### Configuration Examples
1154
-
1155
- ```bash
1156
- # Use custom configuration
1157
- aia --config-file ./project_config.yml --prompts-dir ./project_prompts/ my_prompt
1158
-
1159
- # Save output with markdown formatting
1160
- aia --output analysis.md --markdown --append data_analysis dataset.csv
1161
-
1162
- # Speak responses aloud (macOS say, default voice)
1163
- aia --speak my_prompt
1164
-
1165
- # Speak with a specific macOS voice
1166
- aia --speak --voice Samantha my_prompt
1167
- ```
1168
-
1169
- ## Environment Variables
1170
-
1171
- Many CLI options have corresponding environment variables with the `AIA_` prefix.
1172
- Use double underscore (`__`) for nested configuration sections:
1173
-
1174
- ```bash
1175
- # Model configuration (top-level, supports MODEL=ROLE syntax)
1176
- export AIA_MODEL="gpt-4"
1177
- export AIA_MODEL="gpt-4o=architect"
1178
- export AIA_MODEL="gpt-4o=architect,claude=security,gemini=performance"
1179
-
1180
- # LLM settings (nested under llm:)
1181
- export AIA_LLM__ADAPTER="ruby_llm"
1182
- export AIA_LLM__TEMPERATURE="0.8"
1183
- export AIA_LLM__MAX_TOKENS="2048"
1184
-
1185
- # Prompts settings (nested under prompts:)
1186
- export AIA_PROMPTS__DIR="/custom/prompts"
1187
- export AIA_PROMPTS__ROLES_PREFIX="roles"
1188
- export AIA_PROMPTS__SKILLS_PREFIX="skills"
1189
-
1190
- # Output settings (nested under output:)
1191
- export AIA_OUTPUT__FILE="./output.md"
1192
- export AIA_OUTPUT__APPEND="true"
1193
- export AIA_OUTPUT__HISTORY_FILE="~/.prompts/_prompts.log"
1194
-
1195
- # Audio settings (nested under audio:)
1196
- export AIA_AUDIO__VOICE="Samantha" # macOS voice (say -v '?'); or OpenAI voice for custom scripts
1197
- export AIA_AUDIO__SPEAK_COMMAND="say" # default; replace with a custom TTS script for OpenAI TTS
1198
- export AIA_AUDIO__SPEECH_MODEL="tts-1" # passed as SPEECH_MODEL to the speak_command script
1199
-
1200
- # Image settings (nested under image:)
1201
- export AIA_IMAGE__SIZE="1024x1024"
1202
- export AIA_IMAGE__QUALITY="hd"
1203
-
1204
- # Flags (nested under flags:)
1205
- export AIA_FLAGS__CHAT="true"
1206
- export AIA_FLAGS__VERBOSE="true"
1207
- export AIA_FLAGS__DEBUG="false"
1208
- export AIA_FLAGS__TOKENS="true"
1209
- export AIA_FLAGS__COST="true"
1210
- export AIA_FLAGS__NO_MCP="false"
1211
- export AIA_FLAGS__CONSENSUS="true"
1212
-
1213
- # Registry settings (nested under registry:)
1214
- export AIA_REGISTRY__REFRESH="7"
1215
-
1216
- # Paths settings (nested under paths:)
1217
- export AIA_PATHS__AIA_DIR="~/.config/aia"
1218
- export AIA_PATHS__CONFIG_FILE="~/.config/aia/aia.yml"
1219
- ```
1220
-
1221
- **Note**: The `AIA_MODEL` environment variable supports the same inline `MODEL=ROLE` syntax as the `--model` CLI option.
1222
-
1223
- See [Configuration](configuration.md#environment-variables) for a complete list.
1224
-
1225
- ## Configuration Precedence
1226
-
1227
- Options are resolved in this order (highest to lowest precedence):
1228
-
1229
- 1. Command line arguments (including inline `MODEL=ROLE` syntax)
1230
- 2. Environment variables (including inline syntax in `AIA_MODEL`)
1231
- 3. Configuration files (including array format with roles)
1232
- 4. Built-in defaults
1233
-
1234
- **Role-specific precedence**: When using the role feature, inline `MODEL=ROLE` syntax takes precedence over the `--role` flag, which takes precedence over roles in config files.
1235
-
1236
- ## Related Documentation
1237
-
1238
- - [Configuration Guide](configuration.md) - Detailed configuration options
1239
- - [Getting Started](guides/getting-started.md) - Basic usage tutorial
1240
- - [Advanced Prompting](advanced-prompting.md) - Advanced usage patterns
1241
- - [Directives Reference](directives-reference.md) - Prompt directive reference