CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

patch-creation

Create and register new patches for tweakcc. Use when adding new customizations to Claude Code.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

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:

// 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

FilePurpose
src/patches/*.tsIndividual patch implementations
src/patches/index.tsPatch registry, definitions, and application logic
src/types.tsConfig type definitions (MiscConfig, etc.)
src/defaultSettings.tsDefault values for all settings
src/ui/components/MiscView.tsxUI for misc settings

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

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

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

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

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

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

  7. 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
Repository

Piebald-AI/tweakcc

Path

.claude/skills/patch-creation/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.