tweakcc Patch Creation Guide
A complete developer guide for writing and registering new patches for tweakcc, the Claude Code customization tool, enabling safe edits to Claude Code's minified source.
This is developer documentation for tweakcc contributors; it executes nothing and requests no permissions. Generated patches use showDiff for transparency and return null on failure. However, patches inherently modify the Claude Code executable, and the surrounding project enables risky capabilities (permission-check bypass, installer warning suppression); the skill itself offers no confirmation or rollback guidance, so points are deducted.
Internally consistent: failure handling (return null with console.error), registration checklist, and testing steps are given, making the main path plausible. Nothing was executed; multi-version pattern drift is only hand-waved ('try multiple patterns'), and failure feedback for edge cases is thin, hence deductions within the static cap.
Trigger condition is clear ('use when adding new customizations to Claude Code via tweakcc'), audience well-defined (tweakcc contributors). But heavy dependence on Claude Code's minified internals means patterns break across versions; non-fit boundaries and Chinese-environment considerations are absent, so points are deducted.
Well layered: overview, step-by-step guide, key-files table, registration checklist, patch groups, pattern tips, examples, and testing instructions. Repository has MIT license, versioning (4.3.3), CI and tests. The skill itself lacks version/changelog and maintenance ownership is only inferable from the repo, so deductions apply.
Provides a uniform template plus concrete correctness/performance tips ([$\w]+ identifiers, boundary-character anchoring), giving clear marginal value for contributors. But outputs are code sketches requiring per-version adaptation, and representative outputs could not be verified statically, so effectiveness stays below the cap.
Examples cross-check against the repository structure (src/patches, types.ts, defaultSettings.ts, index.ts), and the repo includes vitest tests and CI. However, tests do not cover the skill's own key path (the patch-authoring workflow) and no third-party execution evidence exists, so verifiability remains capped.
- Patches authored per this skill directly modify the Claude Code executable; always review the showDiff output before applying and ensure a backup exists (run tweakcc --apply first to create one).
- Regex patterns are tightly coupled to specific Claude Code versions and may silently fail after upgrades; revalidate per version.
- The project ecosystem includes high-risk examples such as permission-check bypasses; users must assess compliance and security implications themselves.
- No execution was performed; this assessment is a static source review only.
What does this skill do, and when should you use it?
This is the built-in patch-creation skill from the Piebald-AI/tweakcc repository — essentially a contributor-facing guide to patch development. It explains how to locate and replace code in Claude Code's minified cli.js (or the JS embedded in the native binary) using regular expressions, and how to register a new patch in tweakcc's config types, default settings, patch registry, and optional UI. It includes full code templates, a registration checklist, high-performance regex writing tips, and a testing workflow. It targets developers who want to add new customization capabilities to tweakcc, not end users.
Walks developers through a five-step process: create a patch file under src/patches/ (matching minified code with a regex and doing string replacement, returning null on failure and calling showDiff for debugging); add config types and defaults in src/types.ts and src/defaultSettings.ts for configurable patches; register the patch in src/patches/index.ts's PATCH_DEFINITIONS array and patchImplementations object; optionally add UI controls in MiscView.tsx; then build with npm run build and verify with npx tweakcc --apply.
- Open-source contributors adding new feature patches to tweakcc, such as unlocking features or changing UI behavior
- Maintainers adapting existing patch regexes after a new Claude Code release, handling multi-version differences
- Developers extending tweakcc's settings system with their own configurable options
- Contributors adding UI controls like toggles or inputs for new patches
- Users deciding between a formal upstream patch and tweakcc's adhoc-patch/API routes after understanding the patch mechanism and its three groups (ALWAYS_APPLIED / MISC_CONFIGURABLE / FEATURES)
What are this skill's strengths and limitations?
- Complete copyable code templates and a step-by-step registration checklist make onboarding clear
- Practical performance and correctness tips: use [$\w]+ for identifiers ($ is valid in minified JS) and start patterns with boundary characters, reducing match time from 1.5s to 30ms
- Mandates showDiff debugging and returning null on failure, making patches observable and revertible
- Offers guidance for handling multiple Claude Code versions where code patterns may change
- Covers only internal tweakcc patch development, not the repo's 4.0.0 adhoc-patch / API routes (consult the README separately)
- Techniques are experiential (e.g., counting braces to find function ends) with no automated tooling
- No automated test suite documented; verification relies on manually running Claude Code
- It is contributor documentation, not an end-user feature guide — regular users don't need this skill
How do you install this skill?
The skill ships inside the tweakcc repository at .claude/skills/patch-creation/SKILL.md. Clone the repo to use it: git clone https://github.com/Piebald-AI/tweakcc.git && cd tweakcc. No separate installation command is documented in the source.
How do you use this skill?
Follow SKILL.md's steps: 1) create src/patches/myPatch.ts, locating minified code with a regex like /,somePattern([$\w]+)/ and replacing it; 2) update src/types.ts and src/defaultSettings.ts if the patch is configurable; 3) import the function in src/patches/index.ts, add a PATCH_DEFINITIONS entry and a patchImplementations implementation; 4) run npm run build to compile, npx tweakcc --apply to apply, then run Claude Code to verify behavior.
How does this skill compare with similar options?
The repository itself offers two alternative routes: tweakcc adhoc-patch for one-off patches via string/regex/sandboxed-script modes without forking or opening a PR, and the npm-installable tweakcc API for programmatic patching. This skill covers the third route — writing the patch formally into tweakcc's codebase.