Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The opcode project welcomes contributions to enhance its capabilities as a GUI application and toolkit for Claude Code. This guide outlines the standards and procedures for contributing to both the core application (Frontend/Backend) and the specialized CC Agents library. The goal is to maintain high code quality, ensure security, and provide a consistent experience for all users.
Contributors are encouraged to review existing issues and pull requests to avoid duplicated efforts. The project structure supports various contribution areas including bug fixes, new features, documentation, and internationalization.
Sources: CONTRIBUTING.md:1-7, README.md:310-318
Workflow for Core Contributions
To contribute to the opcode repository, developers must follow a structured GitHub-based workflow. This ensures that every change is tracked, tested, and described adequately before being merged into the main codebase.
Pull Request Process
- Fork and Branch: Fork the repository and create a new branch specifically for the feature or fix.
- Implementation and Testing: Make changes and verify they pass all automated and manual tests.
- Submission: Submit a pull request with a descriptive title using specific prefixes.
Title Prefix Standards
| Prefix | Usage |
|---|---|
Feature: | New functionality or features |
Fix: | Bug fixes |
Docs: | Documentation updates |
Refactor: | Code restructuring without changing behavior |
Improve: | Performance enhancements |
Other: | Miscellaneous changes |
Sources: CONTRIBUTING.md:9-28
Development Lifecycle
The following diagram illustrates the standard contribution flow from local development to pull request submission:
Sources: CONTRIBUTING.md:9-14, CONTRIBUTING.md:71-76
Coding Standards
opcode is a multi-language project utilizing React/TypeScript for the frontend and Rust for the backend. Specific standards apply to each layer.
Frontend (React/TypeScript)
- All new code must be written in TypeScript.
- Components must be functional components utilizing React hooks.
- Styling is managed through Tailwind CSS.
- JSDoc comments are required for all exported functions and components to maintain internal documentation.
Backend (Rust)
- Adhere to standard Rust conventions.
- Mandatory use of
cargo fmtfor formatting andcargo clippyfor linting. - Explicit Result Handling: All
Resulttypes must be handled explicitly; "swallowing" errors is not permitted. - Documentation must use triple-slash
///comments.
Security Requirements
- Input Validation: All data received from the frontend must be validated on the backend.
- Data Safety: Use prepared statements for database interactions to prevent injection.
- Privacy: Never log sensitive data such as tokens or passwords.
Sources: CONTRIBUTING.md:43-69
Testing Requirements
Contributors are expected to provide thorough testing for any new functionality. This includes both automated unit tests and manual verification.
Automated Testing
- Rust: Execute
cargo testto run the backend test suite. - Custom Agents: When contributing CC Agents, they should be capable of generating their own tests or verifying their logic. For example, the Unit Tests Bot aims for >80% overall coverage and 100% critical path coverage.
Hook Validation Logic
For contributions involving the hooksManager, developers must ensure that command patterns do not introduce security risks. The project maintains a list of dangerous patterns that are blocked or warned against during validation.
CC Agent Contributions
The project includes a library of pre-built AI agents. Contributors can add new agents by following specific guidelines.
Agent Structure
Agents are stored as .opcode.json files. A standard agent contribution must include:
- A unique, descriptive Name.
- A focused Single Purpose.
- A System Prompt that defines behavior and capabilities using the latest models (Sonnet for efficiency, Opus for complex reasoning).
- A Default Task to guide user interaction.
Contribution Steps for Agents
- Design and test the agent within the opcode application.
- Export the agent to a
.opcode.jsonfile. - Place the file in the
cc_agents/directory. - Update the
cc_agents/README.mdtable with the new agent's details.
Sources: cc_agents/README.md:73-101
Summary
Contributing to opcode requires adherence to strict language-specific standards and a structured PR process. Whether modifying the TypeScript frontend, the Rust backend, or creating new AI agents, contributors must prioritize security through input validation and maintain reliability through comprehensive testing. Following these guidelines ensures the toolkit remains a powerful, secure, and community-driven interface for Claude Code.
Sources: CONTRIBUTING.md:78-80 assistant
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The opcode project welcomes contributions to enhance its capabilities as a GUI application and toolkit for Claude Code. This guide outlines the standards and procedures for contributing to both the core application (Frontend/Backend) and the specialized CC Agents library. The goal is to maintain high code quality, ensure security, and provide a consistent experience for all users.
Contributors are encouraged to review existing issues and pull requests to avoid duplicated efforts. The project structure supports various contribution areas including bug fixes, new features, documentation, and internationalization.
Sources: CONTRIBUTING.md:1-7, README.md:310-318
Workflow for Core Contributions
To contribute to the opcode repository, developers must follow a structured GitHub-based workflow. This ensures that every change is tracked, tested, and described adequately before being merged into the main codebase.
Pull Request Process
- Fork and Branch: Fork the repository and create a new branch specifically for the feature or bug fix.
- Implementation and Testing: Make changes and verify they pass all automated and manual tests.
- Submission: Submit a pull request with a descriptive title using specific prefixes.
Title Prefix Standards
| Prefix | Usage |
|---|---|
Feature: | New functionality or features |
Fix: | Bug fixes |
Docs: | Documentation updates |
Refactor: | Code restructuring without changing behavior |
Improve: | Performance enhancements |
Other: | Miscellaneous changes |
Sources: CONTRIBUTING.md:9-28
Development Lifecycle
The following diagram illustrates the standard contribution flow from local development to pull request submission:
Sources: CONTRIBUTING.md:9-14, CONTRIBUTING.md:71-76
Coding Standards
opcode is a multi-language project utilizing React/TypeScript for the frontend and Rust for the backend. Specific standards apply to each layer.
Frontend (React/TypeScript)
- All new code must be written in TypeScript.
- Components must be functional components utilizing React hooks.
- Styling is managed through Tailwind CSS.
- JSDoc comments are required for all exported functions and components to maintain internal documentation.
Backend (Rust)
- Adhere to standard Rust conventions.
- Mandatory use of
cargo fmtfor formatting andcargo clippyfor linting. - Explicit Result Handling: All
Resulttypes must be handled explicitly; "swallowing" errors is not permitted. - Documentation must use triple-slash
///comments.
Security Requirements
- Input Validation: All data received from the frontend must be validated on the backend.
- Data Safety: Use prepared statements for database interactions to prevent injection.
- Privacy: Never log sensitive data such as tokens or passwords.
Sources: CONTRIBUTING.md:43-69
Testing Requirements
Contributors are expected to provide thorough testing for any new functionality. This includes both automated unit tests and manual verification.
Automated Testing
- Rust: Execute
cargo testto run the backend test suite. - Custom Agents: When contributing CC Agents, they should be capable of generating their own tests or verifying their logic. For example, the Unit Tests Bot aims for >80% overall coverage and 100% critical path coverage.
Hook Validation Logic
For contributions involving the hooksManager, developers must ensure that command patterns do not introduce security risks. The project maintains a list of dangerous patterns that are flagged during validation.
CC Agent Contributions
The project includes a library of pre-built AI agents. Contributors can add new agents by following specific guidelines.
Agent Structure
Agents are stored as .opcode.json files. A standard agent contribution must include:
- A unique, descriptive Name.
- A focused Single Purpose.
- A System Prompt that defines behavior using the latest models (Sonnet for efficiency, Opus for complex reasoning).
- A Default Task to guide user interaction.
Contribution Steps for Agents
- Design and test the agent within the opcode application.
- Export the agent to a
.opcode.jsonfile. - Place the file in the
cc_agents/directory. - Update the
cc_agents/README.mdtable with the new agent's details.
Sources: cc_agents/README.md:73-101
Summary
Contributing to opcode requires adherence to strict language-specific standards and a structured PR process. Whether modifying the TypeScript frontend, the Rust backend, or creating new AI agents, contributors must prioritize security through input validation and maintain reliability through comprehensive testing. Following these guidelines ensures the toolkit remains a powerful, secure, and community-driven interface for Claude Code.
Sources: CONTRIBUTING.md:78-80