Add README improvements and contributing documentation (#480)

2026-09-24 16:57:40 +00:00 · 2026-02-06 14:29:38 -07:00
parent 3292439075
commit 04220e73f8
5 changed files with 473 additions and 0 deletions
@@ -0,0 +1,123 @@
+# AGENTS.md
+
+This document provides guidelines for agentic coding assistants working in this repository.
+
+## Development Commands
+
+```bash
+# Build
+pnpm build           # Production build (typecheck + minify)
+pnpm build:dev       # Development build (no minification)
+pnpm watch           # Watch mode for iterative development
+
+# Testing
+pnpm test            # Run all tests once
+pnpm test:dev        # Run tests in watch mode
+npx vitest run <test-file>     # Run single test file
+pnpm run test -- <pattern>     # Run tests matching pattern
+
+# Linting & Formatting
+pnpm lint            # Typecheck + ESLint
+pnpm format          # Format code with Prettier
+
+# Run CLI
+pnpm start           # Run built CLI
+node dist/index.mjs  # Alternative run command
+```
+
+## Code Style
+
+### Formatting
+
+- **Prettier**: 80 char width, single quotes, 2 spaces, semicolons required
+- **No comments**: Do not add comments unless explicitly requested
+- **Section dividers**: Use `// ======` lines for major code sections
+
+### Imports
+
+```typescript
+// Group imports in this order:
+import fs from 'node:fs/promises'; // Node.js built-ins (use node: prefix)
+import path from 'node:path';
+import chalk from 'chalk'; // Third-party libraries
+import ink from 'ink';
+import { getConfig } from '@/config'; // Internal imports (use @/ alias)
+import { PatchConfig } from '@/types';
+```
+
+### TypeScript
+
+- **Strict mode** enabled in tsconfig.json
+- **Avoid `any`**: Use `unknown` with type guards or `as unknown as Type` for assertions
+- **Interfaces** for complex objects, types for simple unions
+- **Custom errors**: Extend `Error` class with `name` property
+
+```typescript
+export class CustomError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CustomError';
+  }
+}
+```
+
+### Naming Conventions
+
+- **Files**: camelCase for logic (`config.ts`), PascalCase for React components (`MainView.tsx`)
+- **Functions**: camelCase (`getConfig`, `detectInstallation`)
+- **Constants**: UPPER_SNAKE_CASE (`CONFIG_DIR`, `DEFAULT_CONFIG`)
+- **Components**: PascalCase with descriptive names (`ThinkingVerbsView`)
+- **Interfaces**: PascalCase, descriptive (`StringsPrompt`, `MarkdownPrompt`)
+
+### Error Handling
+
+```typescript
+try {
+  const result = await someAsyncOperation();
+  return result;
+} catch (error) {
+  debug('Error occurred:', error);
+  return null; // Graceful fallback
+}
+```
+
+### React Patterns
+
+- Use hooks: `useState`, `useEffect`, `useCallback`
+- Context API for state management
+- Ink components: `Box`, `Text`, `Newline`
+- Explicit prop types with interfaces
+
+### Writing Patches
+
+- **Identifier matching**: Use `[$\\w]+` instead of `\\w+` (includes `$` for React refs)
+- **Word boundaries**: Use `,` `;` `}` `{` literal characters at regex start instead of `\\b` for performance
+- **Avoid `\\b`**: Performance issue in V8, use literal alternatives
+
+### Testing
+
+```typescript
+// Use Vitest globals
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+describe('functionName', () => {
+  beforeEach(() => {
+    vi.mock('some-module');
+  });
+
+  it('should do something', () => {
+    expect(result).toBe(expected);
+  });
+});
+```
+
+- Test files in `src/tests/*.test.ts` and `src/patches/*.test.ts`
+- Mock dependencies with `vi.mock()`
+- Test edge cases and error conditions
+
+### CLI Patterns
+
+- Use `ink` for CLI rendering
+- Use `chalk` for terminal colors
+- Use `commander` for CLI argument parsing
+- Add shebang to index.tsx for executable support
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## Unreleased

+- Add comprehensive documentation for thinking verbs and thinking indicator customizations
+- Add contributing guidelines and AGENTS.md for developer experience
 - Add a fallback for WASMagic when it's not available (#399) - @signadou
 - Add opusplan[1m] model alias for 1M context support (#404) - @mike1858
 - Add MCP startup optimization settings (#407) - @mike1858
@@ -0,0 +1 @@
+AGENTS.md
@@ -0,0 +1,225 @@
+# Contributing
+
+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**: 22.x (20.0.0 or higher required)
+- **pnpm**: 10.13.1 or higher
+
+```bash
+pnpm install
+```
+
+### Running in Development
+
+```bash
+# 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
+
+```bash
+# 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:
+
+   ```bash
+   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:
+   ```bash
+   pnpm lint
+   pnpm run test
+   ```
+3. Build your changes:
+   ```bash
+   pnpm build:dev
+   ```
+4. Test your changes by running the CLI locally:
+   ```bash
+   pnpm start
+   ```
+
+### Testing
+
+Run tests before submitting:
+
+```bash
+# 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:
+
+```text
+<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
+
+```markdown
+## 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](https://github.com/Piebald-AI/tweakcc/issues) for similar problems
+- Read the [README](https://github.com/Piebald-AI/tweakcc#readme) for usage documentation
+- Ask questions in a new issue with the `question` label
+
+Thank you for contributing! 🙌
@@ -120,6 +120,7 @@ $ pnpm dlx tweakcc
  - _Missing documentation for above features coming soon_
 - [Configuration directory](#configuration-directory)
 - [Building from source](#building-from-source)
+- [Contributing](#contributing)
 - [Related projects](#related-projects)
 - [System prompts](#system-prompts)
 - [Toolsets](#toolsets)
@@ -133,6 +134,114 @@ tweakcc works by patching Claude Code's minified `cli.js` file. For npm-based in

 tweakcc is verified to work with Claude Code **2.1.32.** In newer or earlier versions various patches might not work. However, if we have the [system prompts for your version](https://github.com/Piebald-AI/tweakcc/tree/main/data/prompts) then system prompt patching is guaranteed to work with that version, even if it's significantly different from the verified CC version&mdash;the version number stated above is only relevant for the non-system-prompt patches. We get the latest system prompts within minutes of each new CC release, so unless you're using a CC version older than 2.0.14, your version is supported.

+## Feature: Thinking verbs customization
+
+Customize the thinking verbs that appear while Claude is generating responses, along with the format string. You can change from the default `"Thinking… "` format to something more fun like `"Claude is {verb}ing..."` or anything else you prefer.
+
+Here's a demo showing a custom thinking verb format in action:
+
+![Claude Code showing "Claude is Baking..." as the thinking verb](./assets/demo.gif)
+
+To customize thinking verbs, you can use the tweakcc UI or edit [`~/.tweakcc/config.json`](#configuration-directory) manually.
+
+**Via the UI:**
+
+1. Run `npx tweakcc`
+2. Navigate to the **"Thinking verbs"** section
+3. Use the tab key to switch between **Format** and **Verbs** sections
+4. Edit the format string: the `{}` placeholder will be replaced with a randomly selected verb
+5. Add, edit, or remove verbs from the list
+6. Apply changes when satisfied
+
+**Via `config.json`:**
+
+In `.settings.thinkingVerbs`, configure the `format` and `verbs`:
+
+```json
+"thinkingVerbs": {
+  "format": "{}… ",
+  "verbs": [
+    "Accomplishing",
+    "Baking",
+    "Cogitating",
+    "Fermenting",
+    "Moonwalking",
+    "Noodling"
+  ]
+}
+```
+
+Here's the schema:
+
+```typescript
+{
+  format: string;    // Format string, use {} as placeholder for the verb
+  verbs: string[];   // Array of verbs (Claude randomly selects one)
+}
+```
+
+**Examples of different formats:**
+
+- Default format: `"{}… "` → displays as `"Thinking… "`
+- Custom format: `"Claude is {verb}ing..."` → displays as `"Claude is Baking..."`
+- Custom format: `"✻ {verb} (generating)"` → displays as `"✻ Baking (generating)"`
+- Custom format: `"<{verb}> "` → displays as `"<Baking> "`
+
+**Reset to defaults:**
+
+To reset to the default verbs and format, run `npx tweakcc`, navigate to **Thinking verbs**, and press `Ctrl+R` to restore defaults (which include 200+ fun verbs like "Beboppin'", "Fermenting", "Moonwalking", etc.).
+
+## Feature: Thinking indicator customizations
+
+Customize the thinking indicator (spinner) animation that appears alongside the thinking verb. You can change the animation phases, speed, and whether it reverses direction.
+
+The thinking indicator consists of a sequence of characters that cycle through while Claude is thinking, displayed alongside the thinking verb (e.g., `Thinking·` → `Thinking✢` → `Thinking✳` → etc.).
+
+**Via `config.json`:**
+
+In `.settings.thinkingStyle`, configure the animation:
+
+```json
+"thinkingStyle": {
+  "updateInterval": 120,
+  "phases": [
+    "·",
+    "✢",
+    "✳",
+    "✶",
+    "✻",
+    "✽"
+  ],
+  "reverseMirror": true
+}
+```
+
+Here's the schema:
+
+```typescript
+{
+  updateInterval: number;   // Animation speed in milliseconds (lower = faster)
+  phases: string[];          // Array of characters that cycle through
+  reverseMirror: boolean;    // Whether to reverse the animation sequence
+}
+```
+
+**Examples of different animations:**
+
+| Animation       | Phases                                               | Description                  |
+| --------------- | ---------------------------------------------------- | ---------------------------- |
+| Default stars   | `['·', '✢', '✳', '✶', '✻', '✽']`                     | Classic star burst animation |
+| Simple dots     | `['.', '..', '...']`                                 | Classic loading dots         |
+| Braille spinner | `['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']` | Braille-style spinner        |
+| Arrow spinner   | `['←', '↖', '↑', '↗', '→', '↘', '↓', '↙']`           | Rotating arrow               |
+| Minimal         | `['○', '◐', '◑', '●']`                               | Minimal circle animation     |
+
+**Speed customization:**
+
+- `updateInterval: 60` → Very fast animation (60ms per phase)
+- `updateInterval: 120` → Default speed (120ms per phase)
+- `updateInterval: 250` → Slower animation (250ms per phase)
+
 ## Feature: Input pattern highlighters

 For a few weeks, when you typed the word "ultrathink" into the Claude Code input box, it would be highlighted rainbow. That's gone now, but the underlying highlighting infrastructure is still present in Claude Code today, and tweakcc lets you specify custom highlighters comprised of a **regular expression**, **format string**, and **colors & styling**.
@@ -534,6 +643,19 @@ pnpm build
 node dist/index.mjs
 ```

+## Contributing
+
+Contributions are welcome! Whether you're fixing a bug, adding a new feature, improving documentation, or adding tests, we appreciate your help.
+
+For detailed guidelines on development setup, code style, testing, and submitting pull requests, see the [CONTRIBUTING.md](https://github.com/Piebald-AI/tweakcc/blob/main/CONTRIBUTING.md) file.
+
+### Quick Start
+
+1. Fork the repository and create a new branch
+2. Make your changes following the code style guidelines
+3. Run tests and linting: `pnpm test && pnpm lint`
+4. Submit a pull request with a clear description
+
 ## Related projects

 - [**cc-mirror**](https://github.com/numman-ali/cc-mirror) - Create multiple isolated Claude Code variants with custom providers (Z.ai, MiniMax, OpenRouter, LiteLLM). Uses tweakcc to customize system prompts, themes, thinking styles, and toolsets.