Contributing to Claude Code Toolbox

Thank you for your interest in contributing to the Claude Code Toolbox! We appreciate your help in improving our installation scripts, sub-agents, slash commands, and documentation.

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

Commit Conventions

We follow the Conventional Commits specification to maintain a clear and consistent commit history.

Commit Message Format

type: description

[optional body]

[optional footer]

Commit Types

Below are the conventional commit types we use. These types are used by Release Please to automatically:

Generate CHANGELOG.md entries
Create release PRs
Bump version numbers according to semantic versioning

Version Bump Rules:

feat: Triggers a minor version bump (0.x.0)
fix: Triggers a patch version bump (0.0.x)
feat! or fix! or BREAKING CHANGE:: Triggers a major version bump (x.0.0)
Other types (chore, docs, ci, test): No version bump but may appear in changelog

feat

For new features or functionality:

No scopes needed
Example: feat: add automatic Node.js version detection
Example: feat: implement Linux installation script
Example: feat: add performance-optimizer sub-agent
Example: feat: create debug slash command

fix

For bug fixes or reverting previous commits:

No scopes needed
Example: fix: resolve Git Bash detection on Windows 11
Example: fix: handle spaces in installation paths
Example: fix: correct Node.js version comparison logic
Example: fix: restore PowerShell execution policy after install

chore

For maintenance tasks and infrastructure:

No scopes needed
Example: chore: update PowerShell script analyzer rules
Example: chore: reorganize agent templates directory
Example: chore: update release workflow
Example: chore: bump minimum Node.js version to 18

docs

For documentation improvements:

No scopes needed
Example: docs: update installation instructions for Windows
Example: docs: add troubleshooting guide for proxy setups
Example: docs: clarify sub-agent frontmatter fields
Example: docs: add new slash commands

ci

For changes to CI/CD configuration files and pipelines:

No scopes needed
Example: ci: add GitHub Actions lint workflow
Example: ci: configure release automation
Example: ci: add PowerShell script validation
Example: ci: update security scanning configuration

test

For test-related changes:

No scopes needed
Example: test: add installation script unit tests
Example: test: implement sub-agent validation tests
Example: test: cover edge cases in path detection
Example: test: add cross-platform compatibility tests

Example Commit Messages

feat: add automatic Git Bash installation for Windows

- Detect existing Git installation
- Install via winget or direct download
- Configure CLAUDE_CODE_TOOLBOX_GIT_BASH_PATH environment variable
- Verify installation with claude doctor

fix: handle corporate proxy authentication

Resolve installation failures behind corporate proxies by:
- Supporting authenticated proxy settings
- Using system proxy configuration
- Providing fallback download methods

docs: add macOS installation guide

- Document Homebrew installation method
- Include manual installation steps
- Add troubleshooting section for common issues

How to Contribute

Reporting Issues

Check existing issues to avoid duplicates
Use issue templates when available
Include:
- Clear description of the problem
- Steps to reproduce
- Expected vs actual behavior
- System information (OS, versions)
- Error messages and logs

Submitting Pull Requests

Fork the repository and create a feature branch from main
Make your changes following our guidelines
Test thoroughly on relevant platforms
Commit with clear messages following our conventions
Push to your fork
Open a Pull Request with a clear description

Development Setup

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality. Pre-commit is automatically installed as a dev dependency when you set up the project:

# Create and activate virtual environment
uv venv
# Activate the venv as shown by uv output (platform-specific)

# Install all dependencies including pre-commit
uv sync

# Install the git hooks
uv run pre-commit install

# Run manually on all files
uv run pre-commit run --all-files

Configured hooks:

Ruff: Python linting with --fix for auto-correction
ty: Python type checking
Markdownlint: Markdown formatting and style checking
PSScriptAnalyzer: PowerShell script analysis (Windows only)
Shellcheck: Shell script linting
Commitizen: Commit message format validation
JSON/YAML validators: Syntax checking
File formatting: End-of-file fixing, trailing whitespace removal

Development Guidelines

PowerShell Scripts (Windows)

Compatibility: Target PowerShell 5.1 minimum
Error Handling: Use proper try-catch blocks
Logging: Use consistent Write-Info/Ok/Warn/Err functions
Testing: Test on Windows 10 and 11
Linting: Must pass PSScriptAnalyzer checks
Documentation: Include clear comments and usage examples

Shell Scripts (Linux/macOS)

Compatibility: Target bash 4.0+
Portability: Test on multiple distributions/versions
Error Handling: Use set -euo pipefail
Style: Follow Google Shell Style Guide
Linting: Must pass shellcheck with --severity=warning
Cross-platform: Consider differences between Linux and macOS

Python Scripts

Compatibility: Python 3.12 (managed by uv)
Style: Must pass all pre-commit hooks (Ruff, ty)
Error Handling: Comprehensive try-except blocks
Cross-platform: Test on Windows, Linux, and macOS
Dependencies: Use uv for package management

General Guidelines

Security First
- Never hardcode secrets or API keys
- Validate all inputs
- Use HTTPS for downloads
- Implement proper error handling
User Experience
- Clear, informative messages
- Graceful fallbacks
- Minimal user interaction required
- Support common edge cases
Code Quality
- Self-documenting code
- Consistent formatting
- Modular functions
- Avoid code duplication

Testing

Python Tests

ALWAYS run the full test suite after making ANY changes to the codebase:

# Run all tests (REQUIRED before committing)
uv run pytest

# Run with coverage report
uv run pytest --cov=scripts

# Run specific test files
uv run pytest tests/test_setup_environment.py
uv run pytest tests/test_install_claude.py

# Run tests matching a pattern
uv run pytest -k "test_colors"

# Run tests with verbose output
uv run pytest -v

If any tests fail, they MUST be fixed before proceeding. The codebase must maintain 100% test pass rate at all times.

Code Quality & Linting

CRITICAL: Always use pre-commit for code quality checks. DO NOT use ruff format or ruff check --fix directly.

# Run all pre-commit hooks (this is the CORRECT way to validate code)
uv run pre-commit run --all-files

# Run specific pre-commit hooks
uv run pre-commit run ruff-check       # Linting + autofix
uv run pre-commit run ty               # Type checking
uv run pre-commit run shellcheck       # Shell script linting
uv run pre-commit run markdownlint     # Markdown linting
uv run pre-commit run psscriptanalyzer # PowerShell linting (Windows only)

Before Submitting

Test your changes:

Run Python Tests (MANDATORY)
```
uv run pytest
```
Run Pre-commit Hooks
```
uv run pre-commit run --all-files
```

Test Installation Scripts

# Windows - test bootstrap scripts
.\scripts\windows\install-claude.ps1 -Verbose
.\scripts\windows\setup-environment.ps1

# Linux/macOS - test bootstrap scripts
bash scripts/linux/install-claude.sh
bash scripts/linux/setup-environment.sh

Components
- Test in Claude Code
- Verify functionality works as expected
- Check tool permissions and configurations
Documentation
- Run markdownlint via pre-commit: uv run pre-commit run markdownlint
- Check for broken links
- Verify code examples work
- Ensure formatting is correct

Project Structure

claude-code-toolbox/
├── scripts/
│   ├── install_claude.py            # Cross-platform Claude installer
│   ├── setup_environment.py         # Cross-platform environment setup
│   ├── windows/                     # Windows bootstrap scripts
│   │   ├── install-claude.ps1       # Claude installation script
│   │   └── setup-environment.ps1    # Environment setup script
│   ├── linux/                       # Linux bootstrap scripts
│   │   ├── install-claude.sh        # Claude installation script
│   │   └── setup-environment.sh     # Environment setup script
│   ├── macos/                       # macOS bootstrap scripts
│   │   ├── install-claude.sh        # Claude installation script
│   │   └── setup-environment.sh     # Environment setup script
│   └── hooks/                       # Git hooks and validators
├── tests/                           # Test suite
│   ├── test_install_claude.py       # Tests for installer
│   └── test_setup_environment.py    # Tests for environment setup
├── docs/                            # Technical documentation
├── .github/                         # GitHub workflows and templates
│   └── workflows/
│       ├── lint.yml                 # Linting and validation
│       └── release-please.yml       # Automated releases
├── pyproject.toml                   # Python project configuration
├── .pre-commit-config.yaml          # Pre-commit hook configuration
├── release-please-config.json       # Release automation config
├── .release-please-manifest.json   # Version tracking
├── CLAUDE.md                        # Claude Code instructions
├── README.md                        # User documentation
└── CONTRIBUTING.md                  # This file

Adding New Features

Discuss First: Open an issue for significant changes
Design: Document the approach in the issue
Implement: Follow coding guidelines
Test: Include test scenarios and ensure all tests pass
Document: Update relevant documentation
Submit: Create a pull request

CRITICAL: Testing Workflow After Code Changes

Testing is MANDATORY after ANY code changes:

Make your code changes
Run uv run pytest to check all tests pass
Fix any failing tests immediately
Run uv run pre-commit run --all-files for code quality validation
Only commit when ALL tests pass and all pre-commit hooks pass

Never skip the test suite. Even small changes can have unexpected impacts.

Documentation Requirements

Update README.md for user-facing changes
Add/update docs/ for detailed technical documentation
Include inline comments for complex logic
Update CLAUDE.md if changing development workflows

Important: Version Management

DO NOT manually edit CHANGELOG.md - automatically generated by Release Please
DO NOT manually edit version.txt - automatically updated by Release Please
DO NOT manually edit .release-please-manifest.json - managed by Release Please
Use conventional commits to trigger automatic versioning and changelog updates

Pull Request Process

Run tests: uv run pytest (MUST pass 100%)
Run pre-commit hooks: uv run pre-commit run --all-files
Update documentation as needed
Use conventional commits for automatic changelog generation
Push to your fork and open PR
Wait for CI checks to pass:
- Pre-commit validation (Ubuntu)
- PSScriptAnalyzer (Windows)
- Security scanning (Trivy)
Request review from maintainers
Address review feedback
Squash commits if requested
Merge after approval

Release Please Workflow:

After merging PRs to main, Release Please automatically:
- Creates/updates a release PR with:
  - Generated CHANGELOG.md entries from commit messages
  - Bumped version in version.txt
  - Updated .release-please-manifest.json
- The release PR title shows the new version number
When the release PR is merged:
- A GitHub release is created with the changelog
- A git tag is created for the version
- The main branch contains the updated version files
Version bump logic:
- feat: minor bump (0.x.0)
- fix: patch bump (0.0.x)
- Breaking changes: major bump (x.0.0)
- Other types: no version change

Review Process

Automated checks must pass:
- Pre-commit hooks (Ruff, markdownlint, shellcheck, etc.)
- PSScriptAnalyzer for PowerShell
- Trivy security scanning
- Commitizen validation
Code review by maintainers
Testing in relevant environments
Documentation review
Final approval and merge

CI/CD Pipeline

GitHub Actions Workflows

Lint and Validate (lint.yml):
- Triggers on pull requests
- Runs pre-commit hooks on Ubuntu
- Runs PSScriptAnalyzer on Windows
- Performs security scanning with Trivy
- Skips Release Please PRs
Release Please (release-please.yml):
- Triggers on pushes to main
- Automatically creates release PRs
- Generates CHANGELOG.md from commits
- Bumps version numbers
- Creates GitHub releases

Questions?

Open a question for general questions
Check existing issues for answers
Refer to documentation first
Contact maintainers if needed

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to Claude Code Toolbox!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to Claude Code Toolbox

Code of Conduct

Commit Conventions

Commit Message Format

Commit Types

feat

fix

chore

docs

ci

test

Example Commit Messages

How to Contribute

Reporting Issues

Submitting Pull Requests

Development Setup

Pre-commit Hooks

Development Guidelines

PowerShell Scripts (Windows)

Shell Scripts (Linux/macOS)

Python Scripts

General Guidelines

Testing

Python Tests

Code Quality & Linting

Before Submitting

Project Structure

Adding New Features

CRITICAL: Testing Workflow After Code Changes

Documentation Requirements

Important: Version Management

Pull Request Process

Review Process

CI/CD Pipeline

GitHub Actions Workflows

Questions?

License

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Claude Code Toolbox

Code of Conduct

Commit Conventions

Commit Message Format

Commit Types

feat

fix

chore

docs

ci

test

Example Commit Messages

How to Contribute

Reporting Issues

Submitting Pull Requests

Development Setup

Pre-commit Hooks

Development Guidelines

PowerShell Scripts (Windows)

Shell Scripts (Linux/macOS)

Python Scripts

General Guidelines

Testing

Python Tests

Code Quality & Linting

Before Submitting

Project Structure

Adding New Features

CRITICAL: Testing Workflow After Code Changes

Documentation Requirements

Important: Version Management

Pull Request Process

Review Process

CI/CD Pipeline

GitHub Actions Workflows

Questions?

License