Language Support and Runtimes
Relevant source files
The following files were used as context for generating this wiki page:
The Language Support and Runtimes system in OpenCode Swarm provides the infrastructure for identifying project languages and frameworks to inject context-aware constraints and checklists into AI agent prompts. This system ensures that agents like the Coder, Reviewer, and Test Engineer operate with awareness of the specific technical stack used in a repository, adhering to language-specific best practices and architectural patterns.
By automating the detection of file profiles, the system allows the orchestrator to dynamically enhance system messages with relevant coding standards and review criteria. This multi-layered detection approach covers file extensions, project-wide framework signatures, and environment-specific runtime requirements, ensuring cross-platform portability and safety.
Detection Architecture
The system utilizes a registry of language profiles to map file paths to specific prompts and constraints. This process is primarily driven by the detector and framework-detector modules, which are integrated into the system-enhancer hook to influence agent behavior during task execution.
Language Profiling
Each supported language is defined as a LanguageProfile, which contains metadata and specific prompt blocks for different agent roles. These profiles are stored in a central registry and accessed via file path patterns.
The diagram shows how a file path is processed by the detector to retrieve a Language Profile, which then provides specialized constraints for the orchestrator to inject into agent prompts.
Sources: src/lang/detector.ts, src/hooks/system-enhancer.ts:402-495
Core Components
| Component | Description |
|---|---|
LanguageProfile | Data structure defining display names, extensions, and agent-specific prompt strings. |
getProfileForFile | Main entry point for retrieving a profile based on a specific file path. |
detectFramework | Analyzes project structure (e.g., package.json) to identify high-level frameworks. |
LANGUAGE_REGISTRY | The central repository of all supported language definitions. |
Sources: src/lang/detector.ts:10-35, src/lang/registry.ts
Runtime Portability and Safety
OpenCode Swarm maintains strict runtime contracts to ensure the plugin remains portable and safe across different host environments, including Windows, macOS, and Linux. These invariants are non-negotiable for maintaining system stability.
Runtime Invariants
The system is designed to be "Node-ESM-loadable," meaning the main plugin bundle must be loadable in standard Node.js environments without relying on Bun-specific features at the top level.
- Subprocess Isolation: All subprocesses (git, npm, test runners) must use array-form spawn, explicit
cwd, and mandatory timeouts. Stdin is typically set to'ignore'to prevent blocking under specific runtimes like Bun on Windows. - Containment: Runtime state is strictly contained within the
.swarm/directory. Tools are prohibited from creating state files in arbitrary locations to prevent repository pollution. - Platform Awareness: AI agents are explicitly instructed on platform differences, such as the inability of
fs.renameSyncto atomically overwrite directories on Windows.
Sources: AGENTS.md:35-100, src/agents/architect.ts:320-330
Environment Injection
The system injects environment profiles for agents like the Coder and Test Engineer. These profiles include audience-specific information regarding the execution environment.
This flow illustrates the dynamic injection of execution environment details into the agent prompt before task implementation begins.
Sources: src/hooks/system-enhancer.ts:1140-1165
Prompt Enhancement Logic
The system-enhancer.ts hook is responsible for the actual assembly of the language-aware system prompt. It retrieves constraints based on the files currently involved in a task.
Constraint Injection Protocol
- Extract Paths: The system parses the current task text to find source file paths (e.g.,
src/**/*.ts). - Lookup Profiles: It calls
getProfileForFilefor each path. - Deduplicate Constraints: It collects unique constraints across all identified profiles, capped at a maximum of 10 items per category.
- Inject Text: The resulting blocks (e.g.,
[LANGUAGE-SPECIFIC CONSTRAINTS]) are appended to the system message.
Sources: src/hooks/system-enhancer.ts:402-495
Agent-Specific Contexts
| Agent | Injected Context | Purpose |
|---|---|---|
| Coder | Language-specific syntax and style rules. | Ensure implementation follows project conventions. |
| Reviewer | Specialized checklists for logic and security. | Standardize quality gates across different languages. |
| Test Engineer | Testing framework constraints and best practices. | Ensure tests are valid for the specific runtime. |
Sources: src/hooks/system-enhancer.ts:1010-1090
Implementation Details
Language Profile Definition
The LanguageProfile interface defines how language-specific knowledge is stored and formatted for the agents.
export interface LanguageProfile {
name: string;
displayName: string;
extensions: string[];
prompts: {
coderConstraints: string[];
reviewerChecklist: string[];
testConstraints?: string[];
};
}
Sources: src/lang/detector.ts:10-25
Framework Detection
Framework detection often relies on the existence of specific configuration files or dependency patterns. For instance, detection of the Tailwind design system involves checking for tailwind.config files. This information is used by agents like the Designer to reuse existing components rather than reinventing styles.
Sources: src/lang/framework-detector.ts, src/agents/architect.ts:120-135
Summary
Language Support and Runtimes in OpenCode Swarm provide a structured way to enforce technical standards across a multi-agent workflow. By combining static file-based detection with runtime-aware environment injection, the system ensures that AI agents produce code that is not only functional but also compliant with the specific idioms and constraints of the project stack. This infrastructure is critical for maintaining cross-platform safety and consistent quality throughout the development lifecycle.