Patch Creation & Registration

Overview

Patches are code modifications applied to Claude Code's cli.js (or native binary). Each patch finds specific patterns in the minified code and replaces/injects new behavior.

Creating a New Patch

1. Create the patch file

Create src/patches/myPatch.ts:

````typescript // Please see the note about writing patches in ./index

import { showDiff } from './index';

/** Description of what this patch does. CC X.Y.Z: ``diff // Show before/after of the code change -oldCode +newCode `` */ export const writeMyPatch = ( file: string, configValue: string // Add parameters as needed ): string | null => { // Pattern to find in minified code // IMPORTANT: Use [$\w]+ for identifiers (not \w+) because $ is valid in JS identifiers // IMPORTANT: Start patterns with a boundary char (,;}{) for HIGH performance (e.g. 1.5s -> 30ms) const pattern = /,somePattern([$\w]+)/;

const match = file.match(pattern);

if (!match || match.index === undefined) { console.error('patch: myPatch: failed to find pattern'); return null; }

const replacement = ,newCode${match[1]};

const startIndex = match.index; const endIndex = startIndex + match[0].length;

const newFile = file.slice(0, startIndex) + replacement + file.slice(endIndex);

showDiff(file, newFile, replacement, startIndex, endIndex);

return newFile; }; ````

2. Add config type (if patch is configurable)

Edit src/types.ts - add to MiscConfig or create a new interface:

export interface MiscConfig {
  // ... existing fields ...
  myNewSetting: string | null; // null = disabled
}

3. Add default value

Edit src/defaultSettings.ts:

misc: {
  // ... existing fields ...
  myNewSetting: null,  // or a sensible default
},

4. Register in index.ts

Edit src/patches/index.ts:

4a. Add import:

import { writeMyPatch } from './myPatch';

4b. Add patch definition (in PATCH_DEFINITIONS array):

{
  id: 'my-patch',
  name: 'My patch',
  group: PatchGroup.FEATURES,  // or ALWAYS_APPLIED, MISC_CONFIGURABLE
  description: 'What this patch does for the user',
},

4c. Add patch implementation (in patchImplementations object):

'my-patch': {
  fn: c => writeMyPatch(c, config.settings.misc!.myNewSetting!),
  condition: !!config.settings.misc?.myNewSetting,
},

5. Add UI (optional)

Edit src/ui/components/MiscView.tsx to add a toggle or input for the setting.

Key Files

Registration Checklist

When adding a new patch, update these locations:

• src/patches/myPatch.ts - Create the patch file with exported function
• src/types.ts - Add config type (if configurable)
• src/defaultSettings.ts - Add default value (if configurable)
• src/patches/index.ts:

- [ ] Import the patch function - [ ] Add to PATCH_DEFINITIONS array (id, name, group, description) - [ ] Add to patchImplementations object (fn, condition)

• src/ui/components/MiscView.tsx - Add UI controls (optional)

Patch Groups

• PatchGroup.ALWAYS_APPLIED - Core patches that are always applied
• PatchGroup.MISC_CONFIGURABLE - User-configurable misc settings
• PatchGroup.FEATURES - Feature patches that can be enabled/disabled

Pattern Writing Tips

1. Use [$\w]+ for identifiers - Not \w+, because $ is valid in JS identifiers and common in minified code

1. Start patterns with boundary characters - Use ,, ;, {, } at the start to dramatically speed up matching (can reduce 1.5s to 30ms)

1. Don't use \b for word boundaries - It doesn't treat $ as a word character, so \b[$\w]+ won't match ,$=

1. Extract function bodies carefully - Count braces to find matching } when you need the full function

1. Use showDiff() for debugging - Always call it to log what the patch is changing

1. Return null on failure - Let the patch system know the patch couldn't be applied

1. Handle multiple CC versions - Code patterns may change between versions; try multiple patterns if needed

Example: Simple Toggle Patch

// Bypass a feature flag check
const pattern = /function [$\w]+\(\)\{return [$\w]+\("my_feature_flag"/;
const match = file.match(pattern);

if (!match || match.index === undefined) {
  console.error('patch: myPatch: failed to find feature flag');
  return null;
}

const insertIndex = match.index + match[0].indexOf('{') + 1;
const insertion = 'return true;';

const newFile =
  file.slice(0, insertIndex) + insertion + file.slice(insertIndex);

showDiff(file, newFile, insertion, insertIndex, insertIndex);
return newFile;

Example: Replace a Value

// Replace a hardcoded value
const pattern = /(someConfig=)\d+(;)/;
const match = file.match(pattern);

if (!match || match.index === undefined) {
  console.error('patch: myPatch: failed to find config value');
  return null;
}

const replacement = match[1] + newValue + match[2];
const startIndex = match.index;
const endIndex = startIndex + match[0].length;

const newFile = file.slice(0, startIndex) + replacement + file.slice(endIndex);

showDiff(file, newFile, replacement, startIndex, endIndex);
return newFile;

Testing

1. Run npm run build to compile
2. Run npx tweakcc --apply to apply patches
3. Check console output for patch success/failure
4. Run Claude Code to verify behavior