How madbomber/aia works
Main Components
• CLI/Entry Point:
• The executable scripts in the “bin” directory (e.g., bin/aia, bin/console, bin/setup) define the entry points.
• The “justfile” and “main.just” indicate some scripting and task automation methods.
• Core Library:
• “lib/aia.rb” and the “lib/aia” subdirectory implement the core application logic.
• Look at files such as cli.rb, main.rb, config.rb, prompt.rb, logging.rb, and dynamic_content.rb – they represent the business logic, configuration management, and directive processing.
• Tool and Backend Integration:
• Under “lib/aia/tools” you find separate Ruby files for various external integrations (ai_client_backend.rb, client.rb, editor.rb, fzf.rb, glow.rb, llm.rb, mods.rb, sgpt.rb, etc.). These files encapsulate communication with different AI backends and external command-line tools.
• Directives and Dynamic Processing Subsystem:
• The system for managing prompt directives is spread through files like directives.rb and user_query.rb, indicating that the tool parses prompt files, substitutes shell commands and ERB templates, and then dispatches these prompts to backend AI processors.
• Testing and Documentation:
Relationships and Data Flow
• A client “User Interface” block that represents the command-line input.
• “Configuration Manager” (using files like configuration.yml, environment variable integration from .envrc, and configuration overrides via //config directives) as an independent module feeding configuration values into the rest of the system.
• A “Prompt Manager” component that handles loading prompt files, processing directives (//config, //include, //ruby, //shell), and inserting dynamic content (ERB, shell substitution). Indicate that it interacts with “Roles” and “Prompt Sequences”.
Architectural Patterns & Design Principles
• Modularity: The system is segmented into distinct directories for CLI, core logic, backend tools, and tests.
• Separation of Concerns: There is a clear separation between prompt processing, configuration management, and AI backend interactions.
• Extensibility: The design (e.g., support for plugins via “roles” and dynamic directive parsing) allows the easy addition of new prompt directives or backend processors.
• Integration with External Tools: Notice how external programs (fzf, ripgrep, etc.) are integrated to support user interaction and file search.