Piebald-AI/tweakcc: Customize Claude Code's Prompts, Themes & UX

Piebald-AI/tweakcc: Customize Claude Code's Prompts, Themes & UX

Claude Code ships with sensible defaults, but power users quickly hit walls: you can't edit the system prompt that shapes every response, you're stuck with Anthropic's stock themes, and the thinking spinner says "Thinking…" whether you're debugging a kernel module or writing a React^{↗ Bright Coding Blog} component. For developers who treat their AI assistant as a daily driver, these constraints accumulate into friction. tweakcc solves this by patching Claude Code's compiled JavaScript^{↗ Bright Coding Blog} to unlock deep customization—system prompts, UI themes, input highlighters, thinking verbs, and even private features that haven't been officially released. From the team behind Piebald, tweakcc turns Claude Code from a black-box tool into something you can tune to your workflow.

What is Piebald-AI/tweakcc?

tweakcc is an open-source CLI tool (TypeScript, MIT License) maintained by Piebald-AI. With 2,322 GitHub stars and 185 forks, it has gained traction among developers who want more control over Claude Code without forking the project or maintaining a custom build. The tool works by modifying Claude Code's minified cli.js—either directly for npm-based installs or by extracting, patching, and repacking the native Bun-compiled binary using node-lief, the team's Node.js bindings for the LIEF executable instrumentation library.

The project's relevance stems from a simple reality: Claude Code is a closed-source product distributed as compiled JavaScript. Without tweakcc, customization requires either accepting what Anthropic ships or running unsupported forks. tweakcc provides a supported, reversible middle path. It stores your customizations in ~/.tweakcc/config.json and can reapply them automatically after Claude Code updates—addressing the maintenance burden that kills most patching workflows.

Key Features

tweakcc's feature set targets three layers: behavior (what Claude does), presentation (what you see), and performance (how it runs).

System prompt customization is the headline capability. tweakcc decomposes Claude Code's dynamically assembled system prompt into individual markdown^{↗ Smart Converter} files—one per tool description, agent prompt, and utility instruction. You edit these in ~/.tweakcc/system-prompts, run tweakcc --apply, and your changes are injected into the compiled output. When Anthropic updates prompts, tweakcc generates HTML diffs showing your changes alongside theirs, so you can merge rather than restart.

Toolsets let you restrict which built-in tools Claude can access. Unlike Claude Code's permission system, excluded tools are stripped from the system prompt entirely—reducing token usage and preventing Claude from even knowing about capabilities you've disabled. Create a "research" toolset with only WebFetch and WebSearch, or trim bloated descriptions you'll never use.

UI personalization covers themes (with a graphical HSL/RGB picker), custom thinking verbs and spinner animations, input pattern highlighters with regex-driven color coding, user message styling, and table format overrides (Unicode box-drawing, ASCII/markdown, or clean variants).

Performance patches include non-blocking MCP startup (cutting initialization time by roughly 50%), configurable parallel connection batching, token count rounding to reduce terminal rendering load, and statusline throttling for custom status commands.

Advanced unlocks include AGENTS.md support (falling back from CLAUDE.md), session memory, /remember skill, Opus plan with 1M context execution, auto-accept plan mode, and bypassing sudo permission checks—features either missing from Claude Code or gated behind unreleased code.

Use Cases

1. Prompt engineering at scale
Teams running Claude Code for specific domains—internal APIs, regulated industries, specialized languages—need consistent behavior. tweakcc lets you version-control system prompts in Git, share them across machines, and automatically reapply after updates. The conflict-resolution diffing prevents the "update broke my prompts" scenario.

2. Terminal ergonomics for long sessions
Developers in slow SSH sessions or tmux panes benefit from token count rounding (reducing flicker), custom statusline pacing, and spinner animations that actually indicate progress rather than freezing when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set.

3. Cost-optimized model routing
The opusplan[1m] alias uses Opus 4.5 for planning (where reasoning quality matters) and Sonnet 4.5 with 1M context for execution (where context anxiety causes skipped steps). Stay under 200k tokens and you pay standard rates; exceed it and premium pricing kicks in automatically.

4. Cross-platform standardization
Teams mixing macOS, Linux, Windows, NixOS, and various Node version managers can apply identical customizations everywhere. tweakcc detects installations across npm, yarn, pnpm, bun, Homebrew, nvm, fnm, volta, and Nix—including resolving makeBinaryWrapper shims to the underlying binary.

5. Rapid prototyping without forks
The adhoc-patch command with sandboxed --script mode lets you test one-off modifications without maintaining a fork. Scripts run under Node.js 20+'s --experimental-permission sandbox, and can be distributed via Gist or pastebin for team sharing.

Installation & Setup

The fastest path is npx:

npx tweakcc

Or with pnpm:

pnpm dlx tweakcc

For global installation or programmatic use:

npm install -g tweakcc
# or
npm install tweakcc

To build from source:

git clone https://github.com/Piebald-AI/tweakcc.git
cd tweakcc
pnpm i
pnpm build
node dist/index.mjs

On first run, tweakcc creates ~/.tweakcc/ (or respects TWEAKCC_CONFIG_DIR / XDG_CONFIG_HOME). It downloads system prompt definitions for your detected Claude Code version and populates system-prompts/ with editable markdown files. Run npx tweakcc --apply after any configuration change to patch your installation.

Nix/NixOS note: The Nix store is read-only, so patching requires sudo npx tweakcc --apply. Changes are lost on nix-collect-garbage or rebuilds—reapply afterward. Restore originals with sudo nix store repair /nix/store/<hash>-claude-code-<version>.

Real Code Examples

Custom thinking verbs via config.json

{
  "thinkingVerbs": {
    "format": "Claude is {verb}ing...",
    "verbs": [
      "Accomplishing",
      "Baking",
      "Cogitating",
      "Fermenting",
      "Moonwalking",
      "Noodling"
    ]
  }
}

The {} placeholder is replaced with a randomly selected verb. After tweakcc --apply, Claude Code displays "Claude is Baking..." instead of the default "Thinking…". The format field supports any string with a single {} substitution point.

Ad-hoc patch from remote URL

npx tweakcc adhoc-patch --script '@https://gist.githubusercontent.com/bl-ue/2402a16b966176c994ea7bd5d11b0b09/raw/eeb0b78a6387f0e6a15182eeabd95f0e84e4ccd7/patch_cc.js'

This downloads and executes a sandboxed patch script. The script receives Claude Code's JavaScript as a global js variable and returns modified content. The --experimental-permission sandbox prevents filesystem and network access by the script itself, though you should still review the diff tweakcc prints before confirming application.

API: Reading and modifying native binary content

const tweakcc = require('tweakcc');

const nativeInst = {
  path: '/home/user/.local/share/claude/versions/2.0.76',
  kind: 'native'
};

// Extract 10.6 MB of JavaScript from Bun binary
let content = await tweakcc.readContent(nativeInst);

// Modify system prompt branding
content = content.replace(/Claude Code/g, 'My App');
content = content.replace(/Anthropic(?: PBC)?/g, 'My Corp');

// Repack into binary
await tweakcc.writeContent(nativeInst, content);

The readContent/writeContent API abstracts over npm installs (direct file I/O) and native installs (LIEF-based extraction/repacking). This lets tools built on tweakcc ignore installation mechanics entirely.

Remote config application

npx tweakcc@latest --apply --config-url https://gist.githubusercontent.com/bl-ue/27323f9bfd4c18aaab51cad11c1148dc/raw/b24b5fe08874ce50f4be6c093d9589d184f91a70/config.json

Fetches a shared configuration without overwriting your local config.json. The remote settings merge under remoteConfig.settings, useful for testing team configurations or community presets.

Advanced Usage & Best Practices

Version-control your prompts. Initialize a Git repository in ~/.tweakcc (tweakcc auto-generates a .gitignore). This protects your work and lets you branch between prompt sets—e.g., a "thorough" branch with expanded tool descriptions versus a "minimal" branch for cost-sensitive tasks.

Understand the backup model. tweakcc backs up your original cli.js or native binary before first modification. If you patch an already-patched file without a clean backup, you create a corrupted restore point. Fix: install a different Claude Code version to force a fresh backup, or manually delete ~/.tweakcc/cli.backup.js / ~/.tweakcc/native-binary.backup and reinstall Claude Code clean.

Use --string and --regex ad-hoc patches for simple replacements. Reserve --script for logic that needs to inspect or transform code structure. The vars global exposes obfuscated internal names (React variable, module loader, Ink components) so your scripts remain robust across minification changes.

Monitor version compatibility. tweakcc verifies against Claude Code 2.1.162. Non-system-prompt patches may break on newer/older versions. System prompt patching is version-agnostic as long as prompt definitions exist in the data/prompts directory.

Comparison with Alternatives

tweakcc occupies a unique position: it's the only tool that modifies Claude Code in-place while preserving update paths. Alternatives either work around it (wrappers) or require more manual maintenance (static prompt repos). The cost is complexity—tweakcc must track Claude Code's compiled output structure, and patches can break on architectural changes.

FAQ

Does tweakcc work with the native Claude Code installer?
Yes. It extracts JavaScript from the Bun-compiled binary using node-lief, patches it, and repacks. Supports macOS (with ad-hoc signing), Windows, and Linux.

Will my changes survive Claude Code updates?
No—the compiled output is overwritten. But your config persists; run npx tweakcc --apply to reapply all customizations.

Is tweakcc free?
Yes, MIT License. No pricing or paid tiers are mentioned in the repository.

Can I break Claude Code with bad patches?
Yes. Malformed patches can corrupt the installation. tweakcc creates backups and supports --restore, but adhoc-patch does not backup automatically—run --apply first to establish a restore point.

Does it work with Claude Code versions other than 2.1.162?
System prompt patching works for any version with prompt definitions. Other patches may break; test after updates.

How do I disable all color output?
Set FORCE_COLOR=0—a convention Claude Code respects, independent of tweakcc.

Can I use tweakcc programmatically in my own tool?
Yes. The 4.0.0 API exposes config, installation detection, I/O, backup, and utility functions. npm install tweakcc to add as a dependency.

Conclusion

tweakcc is for developers who have outgrown Claude Code's defaults but aren't ready to abandon it for a less capable alternative. It delivers genuine depth—system prompt surgery, UI theming, performance tuning, and feature unlocks—through a mechanism (compiled JS patching) that sounds fragile but is executed with surprising robustness. The 2,322-star traction and active maintenance by a team building commercial AI tooling ([INTERNAL_LINK: Piebald AI developer tools]) suggest this isn't a weekend project.

The ideal user is technically comfortable, runs Claude Code daily, and has specific friction points: bloated system prompts, slow MCP startup, missing AGENTS.md support, or just the desire to make the spinner say "Fermenting" instead of "Thinking." If that's you, start with npx tweakcc and explore incrementally. The config file and backup system make it safe to experiment.

For the latest version, documentation, and prompt definitions, visit https://github.com/Piebald-AI/tweakcc.