Contributing

First off, thanks for taking the time to contribute! This document provides guidelines and instructions for contributing to oh-my-opencode.

Code of Conduct
Getting Started
Project Structure
Development Workflow
Making Changes
Pull Request Process
Getting Help

Code of Conduct

Be respectful, inclusive, and constructive. We’re all here to make better tools together.

Language Policy

English is the primary language for all communications in this repository. This includes:

Issues and bug reports
Pull requests and code reviews
Documentation and comments
Discussions and community interactions

Need Help with English?If English isn’t your first language, don’t worry! We value your contributions regardless of perfect grammar. You can:

Use translation tools to help compose messages
Ask for help from other community members
Focus on clear, simple communication rather than perfect prose

Getting Started

Prerequisites

Bun (latest version) - The only supported package manager
TypeScript 5.7.3+ - For type checking and declarations
OpenCode 1.0.150+ - For testing the plugin

Development Setup

# Clone the repository
git clone https://github.com/code-yeongyu/oh-my-opencode.git
cd oh-my-opencode

# Install dependencies (bun only - never use npm/yarn)
bun install

# Build the project
bun run build

Testing Your Changes Locally

After making changes, you can test your local build in OpenCode:

Build the project:

bun run build

Update your OpenCode config (~/.config/opencode/opencode.json or opencode.jsonc):

{
  "plugin": [
    "file:///absolute/path/to/oh-my-opencode/dist/index.js"
  ]
}

For example, if your project is at /Users/yourname/projects/oh-my-opencode:

{
  "plugin": [
    "file:///Users/yourname/projects/oh-my-opencode/dist/index.js"
  ]
}

Remove "oh-my-opencode" from the plugin array if it exists, to avoid conflicts with the npm version.

Restart OpenCode to load the changes.
Verify the plugin is loaded by checking for OmO agent availability or startup messages.

Project Structure

oh-my-opencode/
├── src/
│   ├── index.ts         # Plugin entry (OhMyOpenCodePlugin)
│   ├── plugin-config.ts # JSONC multi-level config (Zod v4)
│   ├── agents/          # 11 agents (Sisyphus, Hephaestus, Oracle, etc.)
│   ├── hooks/           # 46 lifecycle hooks across 39 directories
│   ├── tools/           # 26 tools across 15 directories
│   ├── mcp/             # 3 built-in remote MCPs
│   ├── features/        # 19 feature modules
│   ├── config/          # Zod v4 schema system
│   ├── shared/          # Cross-cutting utilities
│   ├── cli/             # CLI: install, run, doctor, mcp-oauth
│   ├── plugin/          # 8 OpenCode hook handlers
│   └── plugin-handlers/ # 6-phase config loading pipeline
├── packages/            # Monorepo: comment-checker, opencode-sdk
└── dist/                # Build output (ESM + .d.ts)

Where to look for specific tasks

Task	Location	Notes
Add new agent	`src/agents/` + `src/agents/builtin-agents/`	Follow createXXXAgent factory pattern
Add new hook	`src/hooks/{name}/` + register in `src/plugin/hooks/create-*-hooks.ts`	Match event type to tier
Add new tool	`src/tools/{name}/` + register in `src/plugin/tool-registry.ts`	Follow createXXXTool factory
Add new feature module	`src/features/{name}/`	Standalone module, wire in plugin/
Add new MCP	`src/mcp/` + register in `createBuiltinMcps()`	Remote HTTP only
Add new skill	`src/features/builtin-skills/skills/`	Implement BuiltinSkill interface
Add new command	`src/features/builtin-commands/`	Template in templates/
Add new CLI command	`src/cli/cli-program.ts`	Commander.js subcommand
Modify config schema	`src/config/schema/` + update root schema	Zod v4, add to OhMyOpenCodeConfigSchema

Development Workflow

Build Commands

# Type check only
bun run typecheck

# Full build (ESM + TypeScript declarations + JSON schema)
bun run build

# Clean build output and rebuild
bun run rebuild

# Build schema only (after modifying src/config/schema.ts)
bun run build:schema

# Run tests
bun test

Code Style & Conventions

Convention	Rule
Package Manager	Bun only (`bun run`, `bun build`, `bunx`)
Types	Use `bun-types`, not `@types/node`
Directory Naming	kebab-case (`ast-grep/`, `claude-code-hooks/`)
File Operations	Never use bash commands (mkdir/touch/rm) for file creation in code
Tool Structure	Each tool: `index.ts`, `types.ts`, `constants.ts`, `tools.ts`, `utils.ts`
Hook Pattern	`createXXXHook(input: PluginInput)` function naming
Exports	Barrel pattern (`export * from "./module"` in index.ts)
Tests	Given/When/Then style (not Arrange-Act-Assert)

Anti-Patterns (Do Not Do):

Using npm/yarn instead of bun
Using @types/node instead of bun-types
Suppressing TypeScript errors with as any, @ts-ignore, @ts-expect-error
Generic AI-generated comment bloat
Direct bun publish (use GitHub Actions only)
Local version modifications in package.json
Empty catch blocks catch(e) {}
Catch-all files (utils.ts, helpers.ts, service.ts)

Making Changes

Adding a New Agent

Create a new .ts file in src/agents/
Define the agent configuration following existing patterns
Add to builtinAgents in src/agents/index.ts
Update src/agents/types.ts if needed
Run bun run build:schema to update the JSON schema

// src/agents/my-agent.ts
import type { AgentConfig } from "./types";

export const myAgent: AgentConfig = {
  name: "my-agent",
  model: "anthropic/claude-sonnet-4-6",
  description: "Description of what this agent does",
  prompt: `Your agent's system prompt here`,
  temperature: 0.1,
  // ... other config
};

Adding a New Hook

Create a new directory in src/hooks/ (kebab-case)
Implement createXXXHook() function returning event handlers
Export from src/hooks/index.ts
Register in appropriate create-*-hooks.ts file

// src/hooks/my-hook/index.ts
import type { PluginInput } from "@opencode-ai/plugin";

export function createMyHook(input: PluginInput) {
  return {
    onSessionStart: async () => {
      // Hook logic here
    },
  };
}

Adding a New Tool

Create a new directory in src/tools/ with required files:
- index.ts - Main exports
- types.ts - TypeScript interfaces
- constants.ts - Constants and tool descriptions
- tools.ts - Tool implementations
- utils.ts - Helper functions
Add to builtinTools in src/tools/index.ts
Register in src/plugin/tool-registry.ts

Adding a New MCP Server

Create configuration in src/mcp/
Add to src/mcp/index.ts
Document in README if it requires external setup

Built-in MCPs are remote HTTP servers only. For stdio MCPs, use skills or user configuration.

Pull Request Process

Fork the repository and create your branch from dev
Make changes following the conventions above
Build and test locally:

bun run typecheck  # Ensure no type errors
bun run build      # Ensure build succeeds
bun test           # Run test suite

Test in OpenCode using the local build method described above
Commit with clear, descriptive messages:
- Use present tense (“Add feature” not “Added feature”)
- Reference issues if applicable (“Fix #123”)
Push to your fork and create a Pull Request
Describe your changes clearly in the PR description

PR Checklist

Code follows project conventions
bun run typecheck passes
bun run build succeeds
bun test passes
Tested locally with OpenCode
Updated documentation if needed (README, AGENTS.md)
No version changes in package.json

The CI system runs tests in two modes:

Isolated: Mock-heavy tests run separately
Batch: All other tests run together

Your PR must pass both modes.

Publishing

Important: Publishing is handled exclusively through GitHub Actions.

Never run bun publish directly (OIDC provenance issues)
Never modify package.json version locally

Maintainers use GitHub Actions workflow_dispatch:

gh workflow run publish -f bump=patch  # or minor/major

Getting Help

Project Knowledge: Check AGENTS.md for detailed project documentation
Code Patterns: Review existing implementations in src/
Issues: Open an issue for bugs or feature requests
Discussions: Start a discussion for questions or ideas
Discord: Join the community server for real-time help

Development Tips

Logger Usage

Logger writes to /tmp/oh-my-opencode.log. Check there for debugging:

tail -f /tmp/oh-my-opencode.log

Testing Strategy

The project uses Bun’s test framework with given/when/then style:

import { describe, test, expect } from "bun:test";

describe("MyFeature", () => {
  describe("#given some context", () => {
    describe("#when action happens", () => {
      test("#then expected outcome", async () => {
        // Test implementation
        expect(result).toBe(expected);
      });
    });
  });
});

Never use “Arrange-Act-Assert” comments. Use describe blocks with #given/#when/#then prefixes instead.

Multi-Level Config System

Configuration follows this priority:

Project (.opencode/oh-my-opencode.jsonc)
  ↓
User (~/.config/opencode/oh-my-opencode.jsonc)
  ↓
Defaults (built-in)

Project config overrides user config, which overrides defaults.

Model Resolution

3-step resolution process:

Override (in config)
Category default
Provider fallback
System default

See src/config/schema/ for full schema definition.

Thank You

Thank you for contributing to Oh My OpenCode! Your efforts help make AI-assisted coding better for everyone. If you have questions about contributing, don’t hesitate to ask in Discord or open a discussion.

Extending

Resources

Table of Contents

Code of Conduct

Language Policy

Getting Started

Prerequisites

Development Setup

Testing Your Changes Locally

Project Structure

Development Workflow

Build Commands

Code Style & Conventions

Making Changes

Adding a New Agent

Adding a New Hook

Adding a New Tool

Adding a New MCP Server

Pull Request Process

PR Checklist

Publishing

Getting Help

Development Tips

Logger Usage

Testing Strategy

Multi-Level Config System

Model Resolution

Thank You

Build docs developers (and LLMs) love

Extending

Resources

​Table of Contents

​Code of Conduct

​Language Policy

​Getting Started

​Prerequisites

​Development Setup

​Testing Your Changes Locally

​Project Structure

​Development Workflow

​Build Commands

​Code Style & Conventions

​Making Changes

​Adding a New Agent

​Adding a New Hook

​Adding a New Tool

​Adding a New MCP Server

​Pull Request Process

​PR Checklist

​Publishing

​Getting Help

​Development Tips

​Logger Usage

​Testing Strategy

​Multi-Level Config System

​Model Resolution

​Thank You

Build docs developers (and LLMs) love

Table of Contents

Code of Conduct

Language Policy

Getting Started

Prerequisites

Development Setup

Testing Your Changes Locally

Project Structure

Development Workflow

Build Commands

Code Style & Conventions

Making Changes

Adding a New Agent

Adding a New Hook

Adding a New Tool

Adding a New MCP Server

Pull Request Process

PR Checklist

Publishing

Getting Help

Development Tips

Logger Usage

Testing Strategy

Multi-Level Config System

Model Resolution

Thank You