Custom Agents JSON Spec
Relevant source files
The following files were used as context for generating this wiki page:
The Custom Agents JSON Spec defines a standardized format for exporting, importing, and managing AI-powered agents within the opcode ecosystem. These agents are specialized configurations of the Claude Code CLI, encapsulated in .opcode.json files to allow for portability and community sharing.
The specification ensures that all necessary metadata, including system prompts, model aliases, and UI identifiers, are preserved during transmission between the opcode application and the local storage or remote repositories like GitHub.
Sources: cc_agents/README.md:59-67, src-tauri/src/commands/agents.rs:88-93
Schema Definition
The agent specification uses a wrapper object that includes versioning and metadata alongside the core agent configuration.
Root Object Structure
| Field | Type | Description |
|---|---|---|
version | Integer | The version of the export format (currently 1). |
exported_at | String (ISO 8601) | Timestamp of when the agent was exported. |
agent | Object | The core agent definition containing behavior and identity data. |
Sources: src-tauri/src/commands/agents.rs:88-93, src/lib/api.ts:117-127
Core Agent Object
The agent object contains the technical instructions and identity metadata required to initialize a Claude Code session.
| Field | Type | Description |
|---|---|---|
name | String | The display name of the agent. |
icon | String | A string identifier for the UI icon (e.g., bot, shield, code). |
model | String | Model alias to use (e.g., sonnet, opus). |
system_prompt | String | The primary instruction set defining the agent's role and behavior. |
default_task | String (Optional) | A default task description or placeholder for the agent. |
hooks | String (Optional) | A JSON string representing specific hook configurations. |
Sources: src-tauri/src/commands/agents.rs:96-103, src/lib/api.ts:104-115
Architectural Flow
The following diagram illustrates how the JSON specification is handled during the import and execution lifecycle.
The architecture leverages a Rust backend to validate the JSON schema before persisting it to a local SQLite database for usage.
Sources: src-tauri/src/commands/agents.rs:188-212, src-tauri/src/commands/agents.rs:1047-1070
Identity and UI Assets
Agents use standardized icon identifiers to provide visual context in the opcode interface.
| Icon Identifier | Category | Typical Use Case |
|---|---|---|
bot | General | General purpose assistants |
shield | Security | Security scanners and audit bots |
code | Development | Unit test generators and refactoring bots |
terminal | System | CLI and system operations |
database | Data | Data processing and query bots |
git-branch | VCS | Version control and Git workflow bots |
Sources: cc_agents/README.md:23-30, src-tauri/src/commands/agents.rs:271-285
Example Implementation
The following JSON snippet demonstrates a standard implementation of the spec for a Security Scanner agent.
{
"version": 1,
"exported_at": "2025-06-23T14:29:55.510402+00:00",
"agent": {
"default_task": "Review the codebase for security issues.",
"icon": "shield",
"model": "opus",
"name": "Security Scanner",
"system_prompt": "# AI SAST Agent\n<role>\nYou are an advanced SAST agent...\n</role>"
}
}
Sources: cc_agents/security-scanner.opcode.json:1-12, src-tauri/src/commands/agents.rs:88-103
Execution Logic
When an agent defined by this spec is executed, the backend translates the JSON fields into CLI arguments for the claude binary.
- System Prompt: The
system_promptfield is passed via the--system-promptflag. - Model Selection: The
modelalias is passed via the--modelflag. - Task: The
default_task(or a user-provided override) is passed via the-p(prompt) flag. - Isolation: The execution is flagged with
--output-format stream-jsonto allow opcode to parse real-time metrics.
Sources: src-tauri/src/commands/agents.rs:462-482, src-tauri/src/commands/agents.rs:485-496
Import and Validation Sequence
The application supports importing agents from local files or GitHub. The following sequence shows the validation steps.
The validation logic handles version checks and ensures that naming conflicts are resolved by appending suffixes to imported agents.
Sources: src-tauri/src/commands/agents.rs:1047-1115, src/lib/api.ts:518-527
Conclusion
The Custom Agents JSON Spec provides a structured and versioned methodology for defining autonomous agent behaviors. By encapsulating roles, prompts, and metadata into a single JSON schema, opcode enables a portable and extensible ecosystem for specialized AI development workflows.
Sources: cc_agents/README.md:59-67, src-tauri/src/commands/agents.rs:88-103