Map

tweakcc — Claude Code Customization Tool

Sources ↳ show in map Markdown

tweakcc — Claude Code Customization Tool

Source: https://github.com/Piebald-AI/tweakcc Fetched: 2026-05-06

Overview

tweakcc is a CLI tool that modifies Claude Code's functionality and appearance. From the team behind Piebald, it enables deep customization of Anthropic's Claude Code without forking the project.

What It Does

The tool patches Claude Code's minified cli.js file (or native binaries) to support:

  • System prompt customization across all 17 built-in tools and agent workflows
  • Theme creation with HSL/RGB color pickers
  • Custom thinking verbs and spinner animations
  • Input pattern highlighters with regex-based styling
  • Toolsets to selectively enable/disable tools
  • UI modifications (input box borders, message styling, token displays)
  • Performance optimizations (MCP startup, token rounding, statusline throttling)
  • Advanced features (AGENTS.md support, session memory, auto-accept plan mode)

How It Works

tweakcc reads customizations from ~/.tweakcc/config.json and applies patches by:

  1. For npm installations: Modifying cli.js directly
  2. For native binaries: Extracting embedded JS via node-lief, patching, and repacking

When Claude Code updates, customizations persist in the config file and can be reapplied with tweakcc --apply.

Installation & Usage

# Run without installation
npx tweakcc

# Or install globally
npm install -g tweakcc
tweakcc

Key commands:

  • npx tweakcc — Interactive TUI for configuration
  • npx tweakcc --apply — Apply saved customizations
  • npx tweakcc --restore — Revert to original Claude Code
  • npx tweakcc unpack <path> — Extract JS from native binary
  • npx tweakcc repack <path> — Repackage JS into binary
  • npx tweakcc adhoc-patch — One-off patches via string/regex/script

Supported Platforms

  • OS: Windows, macOS, Linux
  • Installation types: npm, native binaries, Homebrew, nvm, fnm, Nix/NixOS, custom locations
  • Claude Code versions: Verified with 2.1.62; system prompt patching works back to 2.0.14

Major Features

System Prompts

Access markdown files in ~/.tweakcc/system-prompts/ to customize all prompt components. Automatic conflict detection when Anthropic updates prompts.

Themes

Create custom color schemes with visual color picker; switch between themes using /theme command in Claude Code.

Thinking Customization

  • Modify verb lists and format strings (e.g., "Claude is {verb}ing...")
  • Configure spinner animations with custom phases and speeds

Input Pattern Highlighters

Regex-based pattern matching with custom colors and styling for input box content — similar to the former ultrathink rainbow highlighting.

Toolsets

Collections of built-in tools that Claude can call; tools not in the active toolset aren't sent to the model.

Advanced Features

  • Opus Plan 1M: Combines Opus 4.5 planning with Sonnet 4.5's 1M context window for execution
  • MCP Optimization: Non-blocking connections and configurable parallel batch sizes (default 3, range 1-20)
  • Table Formatting: Choose between default, ascii, clean, or clean-top-bottom styles
  • Token Count Rounding: Round token estimates to custom multiples (e.g., 50, 1000)
  • Statusline Customization: Configure throttling intervals and fixed-interval pacing
  • AGENTS.md Support: Falls back to alternative instruction file names (GEMINI.md, CRUSH.md, etc.)
  • Auto-Accept Plan Mode: Automatically approve plans without user prompts (2.1.22+)
  • Session Memory: Unlock conversation persistence and /remember skill
  • Permissions Bypass: Optionally allow --dangerously-skip-permissions under sudo
  • Escape Sequence Filtering: Remove problematic scroll sequences

API Access

tweakcc can be imported as an npm package for programmatic use:

import * as tweakcc from 'tweakcc';

const installations = await tweakcc.findAllInstallations();
const content = await tweakcc.readContent(installation);
const modified = content.replace(/old/g, 'new');
await tweakcc.writeContent(installation, modified);

Functions organize into categories: config, installation, I/O, backup, and utilities.

Configuration

Configuration stored in one of:

  • TWEAKCC_CONFIG_DIR environment variable
  • ~/.tweakcc/ (default)
  • ~/.claude/tweakcc/
  • $XDG_CONFIG_HOME/tweakcc

Config format: config.json containing version info, installation path, applied status, and settings object.

Remote Configuration

Apply configs from HTTP URLs:

npx tweakcc --apply --config-url https://example.com/config.json

Remote settings merge into remoteConfig.settings without overwriting local config.

Limitations & Notes

  • Patches verified against CC 2.1.62; some non-system-prompt features may not work on significantly different versions
  • System prompt patching guaranteed if version's prompts exist in tweakcc repo
  • Native binary patching on Nix requires sudo due to read-only store; changes lost after nix-collect-garbage
  • No backup created by adhoc-patch; use --apply first to enable --restore

License & Stats

  • License: MIT (Copyright © 2026 Piebald LLC)
  • Language: TypeScript (95.7%), JavaScript (4.0%), Python (0.3%)
  • Repository: github.com/Piebald-AI/tweakcc
  • Stars: 2,000+
  • Forks: 155+
  • Latest Release: v4.0.11 (March 5, 2026)

Technical Details

Uses node-lief (LIEF bindings) for native binary manipulation, Ink+React for UI components, and sandboxed Node.js with --experimental-permission for safe ad-hoc patch execution.