Adding a New Language

Relevant source files

The following files were used as context for generating this wiki page:

• src/lang/backends/index.ts
• src/hooks/system-enhancer.ts
• src/agents/architect.ts
• src/agents/coder.ts
• src/agents/explorer.ts

Adding a new language to the OpenCode Swarm framework involves defining language-specific profiles that contain constraints, checklists, and discovery patterns. These profiles ensure that specialized agents, such as the Coder and Reviewer, adhere to the idiomatic practices and architectural requirements of the target language.

The system relies on a detection mechanism to identify the primary language of a project and inject the corresponding constraints into the system prompts during agent delegation. This process is orchestrated by the Architect and supported by the System Enhancer hook.

Architecture Overview

The integration of a new language is handled through a tiered injection system. When an agent is dispatched to work on specific files, the framework detects the language profile based on file paths and suffixes.

The diagram above illustrates the flow from file detection to the injection of language-specific constraints into agent prompts.
Sources: src/hooks/system-enhancer.ts:511-536, src/lang/backends/index.ts

Implementation Steps

1. Define the Language Profile

A language profile must be registered within the language backend system. This profile includes display names and a set of prompts tailored for different agent roles.

Key components of a language profile:

• Display Name: Human-readable name (e.g., "TypeScript", "Python").
• Coder Constraints: Guidelines for implementation (e.g., "Use async/await", "No any types").
• Reviewer Checklist: Specific items for the Reviewer to verify (e.g., "Check for type safety", "Verify error handling").
• Test Constraints: Guidance for the Test Engineer (e.g., "Use bun:test", "Mock external APIs").

Sources: src/hooks/system-enhancer.ts:525-535, src/hooks/system-enhancer.ts:559-569, src/hooks/system-enhancer.ts:593-603

2. Configure Detector Patterns

The system uses the getProfileForFile function to match file paths to language profiles. For a new language to be recognized, its associated file extensions or directory patterns must be mapped.

Component	Responsibility
getProfileForFile	Matches a specific file path to a defined language profile.
Coder Constraints	List of unique constraints (max 10) injected into the Coder's prompt.
Reviewer Checklist	List of items (max 10) added to the Reviewer's checklist.
Test Constraints	Specialized rules for the Test Engineer agent.

Sources: src/hooks/system-enhancer.ts:511-536, src/hooks/system-enhancer.ts:544-572

3. Integrate with System Enhancer

The system-enhancer.ts hook is responsible for the actual injection of these constraints during the experimental.chat.system.transform phase. It extracts file paths from the current task text and retrieves the matching profile.

// Example logic used by the System Enhancer to build constraints
const filePaths = currentTaskText.match(/\bsrc\/\S+\.[a-zA-Z0-9]+\b/g) ?? [];
for (const filePath of filePaths) {
    const profile = getProfileForFile(filePath);
    if (!profile) continue;
    // Add unique constraints from profile.prompts.coderConstraints
}

Sources: src/hooks/system-enhancer.ts:515-532

Agent Awareness and Context

Once a language is added and detected, multiple agents modify their behavior based on the injected context:

Architect Orchestration

The Architect agent identifies the language through the {{PROJECT_LANGUAGE}} placeholder and manages the delegation of tasks to specialized agents. If the language is unresolved, the Architect triggers MODE: DISCOVER to populate project metadata.
Sources: src/agents/architect.ts:133-142

Explorer Discovery

The Explorer agent analyzes the codebase structure and identifies the languages in use, reporting them in the PROJECT summary.
Sources: src/agents/explorer.ts:60-64

Coder Implementation

The Coder receives language-specific rules as "Skills" or injected constraints. These include cross-platform rules, such as using path.join() for file paths and os.EOL for line endings.
Sources: src/agents/coder.ts:134-142, src/hooks/system-enhancer.ts:886-896

Conclusion

Adding a new language requires defining a structured profile and ensuring the detection patterns correctly map source files to that profile. This enables the Swarm to maintain high standards of code quality and idiomatic consistency across diverse technical stacks.