Platform Awareness Engine
Relevant source files
The following files were used as context for generating this wiki page:The Platform Awareness Engine is a foundational component of caro responsible for detecting the user's environment to ensure the generation of compatible and executable shell commands. Its primary goal is to prevent platform-incompatibility failures, such as generating GNU-specific command flags on BSD-based systems like macOS. This engine enables caro to provide accurate, reliable commands tailored to the user's specific operating system, Unix flavor, shell type, and hardware architecture.
This system is critical for fulfilling caro's core value of safety and its mission to democratize terminal access. By understanding the execution context, the engine allows for both seamless local use and advanced cross-platform command generation for tasks like remote server management.
Sources: specs/006-intelligent-prompt-generation/spec.md:11-20, CONTRIBUTING.md:73-80, 203-207
Core Architecture
The engine is built around a set of data structures that capture the platform's characteristics. This information is managed by the Configuration Manager and used by various agents throughout the command generation lifecycle. The main goal is to create a PlatformConfig object that informs the entire system.
Sources: specs/006-intelligent-prompt-generation/spec.md:143-166
Data Models
The key data structures defining the platform context are outlined below.
This diagram shows the main configuration structs and enums used to represent the detected platform environment.
Sources: specs/006-intelligent-prompt-generation/spec.md:403-433, specs/002-implement-tdd-green/plan.md:214-230, specs/006-intelligent-prompt-generation/tasks.md:65-82
The table below details the fields within the PlatformConfig struct.
| Field | Type | Description |
|---|---|---|
os | Platform | The detected operating system (e.g., MacOS, Linux). |
unix_flavor | UnixFlavor | The variant of Unix-like utilities available (e.g., BSD on macOS, GNU on Linux). This is critical for flag compatibility. |
shell | ShellType | The user's current shell, typically detected from the $SHELL environment variable. |
arch | Architecture | The CPU architecture (e.g., aarch64 for Apple Silicon, x86_64 for Intel/AMD). |
target_os | Option<Platform> | An optional override for generating commands for a different OS. |
target_unix_flavor | Option<UnixFlavor> | An optional override for the target Unix flavor. |
Sources: specs/006-intelligent-prompt-generation/spec.md:409-416
Platform Detection
On its first run, caro automatically detects the user's platform characteristics and saves them to the configuration file. This process is handled by the PlatformDetector.
Sources: specs/006-intelligent-prompt-generation/tasks.md:13-16
Detection Flow
The detection logic follows a clear sequence to gather platform information.
This flowchart illustrates the step-by-step process of identifying the OS, Unix flavor, shell, and architecture.
Sources: specs/006-intelligent-prompt-generation/tasks.md:38-82, specs/002-implement-tdd-green/plan.md:281-291
Implementation and Testing
The implementation of the PlatformDetector is a critical task defined in the project specifications. It is validated by a dedicated contract test suite to ensure its accuracy across different environments.
The tests verify that:
- The correct OS and Unix flavor are identified (e.g., macOS is correctly identified as
BSD). - The shell is correctly parsed from the
$SHELLenvironment variable. - A sensible fallback (e.g.,
sh) is used if the shell is unknown. - The CPU architecture is correctly identified.
Sources: specs/006-intelligent-prompt-generation/tasks.md:7-91
Integration with Command Generation
The detected platform information is not just static data; it is actively used by the multi-agent system to guide command generation and validation.
Agent Coordination
The Orchestrator Agent uses the PlatformConfig to select the correct prompt template and provide context to other agents.
This sequence diagram shows how the Orchestrator uses platform information to select a BSD-specific prompt for the Generator Agent, leading to a compatible command.
Sources: specs/006-intelligent-prompt-generation/spec.md:295-314, 345-370
Prompt Engineering
Platform context is directly injected into the prompt templates given to the LLM. This explicitly instructs the model to generate commands compatible with the user's environment, significantly reducing the chance of platform-related errors.
A prompt template might contain sections like this:
CRITICAL REQUIREMENTS:
1. Generate commands compatible with {{unix_flavor}} utilities
2. NEVER use GNU-specific long options if platform is BSD
3. Current platform context:
- OS: {{os}}
- Unix Flavor: {{unix_flavor}}
- Shell: {{shell}}
This ensures the model is fully aware of the constraints imposed by the user's system.
Sources: specs/006-intelligent-prompt-generation/spec.md:316-343
Cross-Platform Generation
A key feature enabled by the Platform Awareness Engine is the ability to generate commands for a target platform that is different from the local one. This is designed for developers and DevOps engineers who work on one OS (e.g., macOS) but deploy to another (e.g., Linux).
This is configured via the target_os and target_unix_flavor fields in config.toml.
[platform]
# Detected local platform
os = "macos"
unix_flavor = "bsd"
# Override for cross-platform generation
target_os = "linux"
target_unix_flavor = "gnu"
When a target is set, caro will:
- Warn the user that they are in cross-platform mode.
- Use prompt templates and validation rules for the target platform (e.g.,
base-gnu.toml). - Generate a command compatible with the target (e.g.,
ls -lh --sort=sizefor Linux). - Provide instructions for local testing if possible (e.g., "install 'coreutils' via Homebrew").
Sources: specs/006-intelligent-prompt-generation/spec.md:65-87, 415-416
Summary
The Platform Awareness Engine is a cornerstone of caro's reliability and safety. By systematically detecting, configuring, and utilizing platform-specific information, it elevates caro from a generic command generator to an intelligent, context-aware assistant. This ensures that users receive commands that not only match their intent but are also guaranteed to be executable in their specific terminal environment, which is a key differentiator and a core part of the project's mission.
Sources: specs/001-create-a-comprehensive/tasks.md:104, CONTRIBUTING.md:73-80