Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
442 lines (309 loc) · 11.5 KB

CONTRIBUTING.md

File metadata and controls

442 lines (309 loc) · 11.5 KB

Contributing to oh-my-claudecode

Thank you for your interest in contributing to oh-my-claudecode (OMC). This guide covers everything from forking to submitting your PR.

1. Audience & Prerequisites

Before you start, make sure you have:

  • Node.js ≥ 20 (required; check with node --version)
  • npm (comes with Node.js)
  • git (for version control)
  • Claude Code installed (to test in-session skills and commands)
  • Basic familiarity with TypeScript, ESBuild, and git workflows

This guide assumes you're comfortable with terminal commands and git branching.

2. Fork & Clone

  1. Fork the repository on GitHub by clicking the "Fork" button at https://github.com/Yeachan-Heo/oh-my-claudecode

  2. Clone your fork:

    git clone https://github.com/<your-username>/oh-my-claudecode.git
cd oh-my-claudecode

  3. Add the upstream remote so you can sync with the main repository:

    git remote add upstream https://github.com/Yeachan-Heo/oh-my-claudecode.git

  4. Verify your remotes:

    git remote -v
# origin    https://github.com/<your-username>/oh-my-claudecode.git (fetch)
# origin    https://github.com/<your-username>/oh-my-claudecode.git (push)
# upstream  https://github.com/Yeachan-Heo/oh-my-claudecode.git (fetch)
# upstream  https://github.com/Yeachan-Heo/oh-my-claudecode.git (read-only)

  5. Check available branches:

    git branch -r
# origin/HEAD -> origin/main
# origin/main
# upstream/dev
# upstream/main

Note: The repo has two main branches:

  • upstream/dev — development branch (default for feature work)
  • upstream/main — release branch (stable, production-ready)

3. Install & Build

  1. Install dependencies:

    npm install

  2. Understand the build chain (from package.json):

    npm run build
# Runs: tsc && build-skill-bridge && build-mcp-server && build-bridge-entry && compose-docs && build:runtime-cli && build:team-server && build:cli
    • tsc — TypeScript compilation to JavaScript
    • build-skill-bridge.mjs — Bundles skills for plugin system
    • build-mcp-server.mjs — Builds MCP server for Claude Code integration
    • build-bridge-entry.mjs — Builds the plugin entry point
    • compose-docs — Assembles documentation from partials
    • build:runtime-cli.mjs — Bundles the CLI runtime
    • build:team-server.mjs — Builds the team server
    • build:cli.mjs — Bundles the CLI entry point

  3. Build once:

    npm run build

All TypeScript and bundling steps are handled. The output goes to dist/ and bridge/.

4. Linking Your Checkout as the Active OMC Plugin

Once built, you need to tell Claude Code to use your local checkout. Here are three flows:

Bootstrap: make the omc command available

All three flows below use the omc CLI. If you don't have it installed globally (via npm i -g oh-my-claude-sisyphus), create a symlink from your checkout:

# Create ~/.local/bin if it doesn't exist
mkdir -p ~/.local/bin

# Symlink omc to the checkout's bridge entry point
ln -sf "$PWD/bridge/cli.cjs" ~/.local/bin/omc

# Verify (you may need ~/.local/bin on your PATH)
omc --version

Flow A: omc --plugin-dir + omc setup --plugin-dir-mode (recommended — lowest friction)

Advantages: Single command, automatic env var handling, matches the OMC philosophy.

# From your checkout directory
omc --plugin-dir "$PWD" setup --plugin-dir-mode

Then launch Claude Code normally — it will use your local checkout.

Disable the .mcp.json server conflict: The repo ships .mcp.json with an MCP server named "t" (the OMC bridge). When using --plugin-dir, the plugin also registers its own "t" server, causing a name collision. To resolve this, add to your ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json):

{
  "disabledMcpjsonServers": ["t"]
}

This tells Claude Code to ignore the repo's .mcp.json entry and use the plugin's version instead.

Inside Claude Code:

/autopilot "your task here"

Rebuilding: After code changes:

npm run build
omc setup --plugin-dir-mode  # or just re-run build and restart Claude Code

Flow B: Marketplace lifecycle (if you prefer plugin system isolation)

Advantages: Uses Claude Code's native plugin system, marketplace semantics.

# Add local directory as a marketplace source
claude plugin marketplace add /path/to/oh-my-claudecode

# Install the plugin
claude plugin install oh-my-claudecode@oh-my-claudecode

# Run setup
/setup

Rebuilding: After code changes:

npm run build
claude plugin marketplace update oh-my-claudecode
claude plugin update oh-my-claudecode@oh-my-claudecode
/setup

Flow C: omc setup --no-plugin (fallback, bundled skills)

Advantages: Forces local bundled skills to ~/.claude/skills/, no plugin system.

omc --plugin-dir "$PWD" setup --no-plugin

This skips the plugin system entirely and installs agents/skills to your home directory.

Comparison table

Flow Command Plugin system? Files location Rebuild cost Use when
A (recommended) omc --plugin-dir "$PWD" setup --plugin-dir-mode Yes, via --plugin-dir Live from checkout Low (no copy on rebuild) Developing OMC itself
B claude plugin marketplace add + install Yes, full marketplace Plugin cache Medium (marketplace update) Testing plugin isolation
C omc setup --no-plugin No ~/.claude/skills/ Low (direct copy) Fallback / troubleshooting

5. Suggested Shell Aliases (Community, Not Enforced)

Add these to your .bashrc / .zshrc for a smoother dev workflow:

# Your OMC dev root (change path as needed)
export OMC_DEV_ROOT="$HOME/_Git/_Claude/oh-my-claudecode"

# Run OMC from your local checkout
alias omcdev='omc --plugin-dir "$OMC_DEV_ROOT"'

# Build quickly
alias omcbuild='(cd "$OMC_DEV_ROOT" && npm run build)'

# Run tests
alias omctest='(cd "$OMC_DEV_ROOT" && npm run test:run)'

# Full watch mode (tsc + esbuild)
alias omcwatch='(cd "$OMC_DEV_ROOT" && npm run dev:full)'

Then you can use:

omcbuild                                # Rebuild in 10–15 seconds
omcdev setup --plugin-dir-mode          # Link your checkout
omcwatch                                # Auto-rebuild on file changes
omctest                                 # Run test suite

6. Rebuilding After Changes

TypeScript changes only

If you only edited .ts files in src/ (no agent/skill markdown changes), choose one of:

# Option A: tsc-only quick feedback (no bundle rebuild)
npm run dev

# Option B: full bundle watch — tsc + esbuild steps in watch mode (recommended)
npm run dev:full

Choose one, not both. npm run dev gives faster feedback for type-checking but does not rebuild bundles under dist/ or bridge/. npm run dev:full rebuilds everything on every change — use this when you need the full artifact up to date (e.g., testing the CLI end-to-end).

Agent, skill, or command changes

After editing markdown files in agents/, skills/, or commands/:

npm run build
omc setup --plugin-dir-mode

The setup command re-reads the markdown files and refreshes the in-session command registry.

Full build (recommended)

npm run build

Runs the complete pipeline: tsc → esbuild bundles → docs composition → all bridge artifacts.

7. Running Tests & Lint

Run tests

# Interactive watch mode
npm test

# Run once and exit
npm run test:run

# Generate coverage report
npm run test:coverage

Run linter

npm run lint

Format code

npm run format

All of these should pass before you submit a PR. GitHub CI will verify them.

8. Rebasing onto Upstream

When you're ready to sync with the latest upstream changes:

For feature branches (target upstream/dev)

# Fetch the latest from upstream
git fetch upstream

# Rebase your branch onto dev
git rebase upstream/dev

# If conflicts: resolve them, then `git rebase --continue`

# Force-push to your fork (safe if no one else is on your branch)
git push --force-with-lease origin <your-branch>

# Re-run tests after rebase
npm run build
npm run test:run

For release branches (target upstream/main)

# Fetch the latest from upstream
git fetch upstream

# Rebase your branch onto main (only if your PR targets main)
git rebase upstream/main

# Force-push to your fork
git push --force-with-lease origin <your-branch>

# Re-run tests
npm run build
npm run test:run

Why --force-with-lease? It's safer than --force because it aborts if someone else pushed to your branch since the last fetch.

9. Submitting a PR

  1. Push your branch to your fork:

    git push origin <your-branch>

  2. Open a PR on GitHub:

  3. PR templates (if present):

    • Check .github/pull_request_template.md for required sections
    • GitHub will auto-populate the template when you open the PR

  4. Release workflow (advanced):

    • If your PR should trigger a release, you can invoke the /oh-my-claudecode:release skill
    • This is typically for maintainers; ask in the PR if unsure

  5. What happens next:

    • GitHub Actions will run tests, linting, and build checks
    • Reviewers will provide feedback
    • Update your PR by pushing more commits to the same branch
    • Once approved, a maintainer will merge your PR

10. Troubleshooting

"OMC_PLUGIN_ROOT is not set"

You're using claude --plugin-dir directly without the omc shim. Export it:

export OMC_PLUGIN_ROOT=/path/to/oh-my-claudecode
claude --plugin-dir /path/to/oh-my-claudecode

Or use the omc shim which sets it automatically:

omc --plugin-dir /path/to/oh-my-claudecode

"Skills/agents not showing up after rebuild"

After npm run build, you must re-run setup to refresh the in-session command registry:

omc setup --plugin-dir-mode

Then restart Claude Code.

Build fails with "esbuild: not found"

npm install
npm run build

If that doesn't work, clear and reinstall:

rm -rf node_modules package-lock.json
npm install
npm run build

Tests fail after rebase

# Clear caches and reinstall
npm ci
npm run test:run

Plugin still showing old version

The plugin cache may need a refresh:

npm run build
omc setup --plugin-dir-mode
# Restart Claude Code

Need more help?

Run the diagnostics tool:

omc doctor
omc doctor conflicts
omc doctor --plugin-dir /path/to/oh-my-claudecode

Or check the troubleshooting sections in:

Additional Resources

Happy contributing!