Contributing

May 10, 2026 · View on GitHub

Thank you for your interest in contributing to tweakcc! This document provides guidelines and workflows for contributing to the project.

Development Setup

Prerequisites

  • Node.js: 24.x (20.0.0 or higher required)
  • pnpm: 11.0.9 or higher
pnpm install

Running in Development

# Build for development (no minification)
pnpm build:dev

# Watch mode for iterative development
pnpm watch

# Run the CLI locally after building
pnpm start

Code Style

This project uses ESLint and Prettier for code formatting and linting.

Prettier Configuration

  • Quotes: Single quotes
  • Print Width: 80 characters
  • Semicolons: Yes
  • Indentation: 2 spaces (no tabs)
  • Arrow Function Parentheses: Avoid when possible
  • Trailing Commas: ES5

Running Linting and Formatting

# Lint and type-check
pnpm lint

# Format code
pnpm format

# Check formatting without modifying files (used in CI)
pnpm prettier --check src

Pre-commit hooks are configured via Husky and lint-staged to automatically format staged files before commit.

TypeScript Best Practices

  • Use strict type checking (enabled in tsconfig.json)
  • Avoid any types - prefer unknown with type guards
  • Use @/ alias for imports within the src/ directory
  • Define interfaces for all configuration objects (see src/types.ts)

Naming Conventions

  • Components: PascalCase (e.g., ThinkingVerbsView)
  • Functions: camelCase (e.g., findClaudeInstallation)
  • Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_CONFIG_PATH)
  • Files: camelCase (e.g., systemPromptSync.ts) or PascalCase for React components (e.g., MainView.tsx)

Making Changes

Branching Strategy

  1. Create a new branch from main for your feature or fix:

    git checkout -b your-branch-name

  2. Branch naming conventions:

    • feature/your-feature-name
    • fix/your-fix-description
    • docs/your-documentation-update

Development Workflow

  1. Make your changes following the code style guidelines
  2. Run linting and tests locally: 
    pnpm lint
pnpm run test
  3. Build your changes: 
    pnpm build:dev
  4. Test your changes by running the CLI locally: 
    pnpm start

Testing

Run tests before submitting:

# Run all tests once
pnpm run test

# Run tests in watch mode for development
pnpm run test:dev

Test files are located in:

  • src/tests/*.test.ts - Unit tests for core functionality
  • src/patches/*.test.ts - Tests for specific patches

Testing patterns:

  • Use Vitest globals (describe, it, expect, beforeEach, afterEach)
  • Mock dependencies using vi.mock()
  • Test edge cases and error conditions

Commit Messages

Follow these conventions for clear, meaningful commit messages:

<type> <subject> (#<issue-number>)

<body>

Types:

  • Add - New features
  • Fix - Bug fixes
  • Prompts for - Update for new Claude version
  • Sort - Sorting or reorganization changes
  • Update - Updates to existing features
  • Refactor - Code refactoring (no functional changes)

Examples:

  • Add support for dangerously bypassing permissions
  • Fix remaining patching errors
  • Prompts for 2.1.34
  • Add auto-accept plan mode patch

Submitting Pull Requests

Before Submitting

  1. Ensure all tests pass: pnpm run test
  2. Ensure linting passes: pnpm lint
  3. Ensure formatting is correct: pnpm format
  4. Rebuild the project: pnpm build:dev
  5. Test your changes locally with pnpm start

PR Description Template

## Summary

<Brief description of what this PR changes>

## Changes

- Change 1
- Change 2

## Testing

- [ ] Tests added/updated
- [ ] Manual testing completed
- [ ] All existing tests pass

## Related Issues

Closes #(issue-number) or Relates to #(issue-number)

Review Process

  1. PRs will be reviewed by maintainers
  2. Address review feedback promptly
  3. Keep the PR focused on a single change if possible
  4. Ensure commit history is clean (squash/rebase as needed)

What Happens After Merge

  • Your changes will be included in the next release
  • You'll be credited in the changelog
  • Your contribution is greatly appreciated! 🎉

Types of Contributions Welcome

  • Bug fixes - Help squash issues
  • New features - Propose new patches or customizations
  • Documentation improvements - Clarify usage or add examples
  • Test coverage - Add tests for existing functionality
  • Performance improvements - Optimize CLI startup or execution
  • Prompt updates - Contribute prompts for new Claude versions

Reporting Issues

When reporting bugs, please include:

  • Version: tweakcc --version
  • Operating System: macOS / Linux / WSL
  • Node.js version: node --version
  • Steps to reproduce: Clear reproduction steps
  • Expected behavior: What you expected to happen
  • Actual behavior: What actually happened
  • Logs: Relevant error messages or logs

Getting Help

  • Check existing Issues for similar problems
  • Read the README for usage documentation
  • Ask questions in a new issue with the question label

Thank you for contributing! 🙌