Map

tweakcc

Toolbox toolboxclaude-codecustomizationclitypescriptwatchlistTypeScriptMIT ↳ show in map Markdown
title
tweakcc
type
toolbox
summary
CLI that patches an installed Claude Code to change prompts, themes, spinners and toolsets
tags
claude-code, customization, cli, typescript, watchlist
repo
https://github.com/Piebald-AI/tweakcc
language
TypeScript
license
MIT
created
2026-05-06
updated
2026-05-06

CLI that patches an installed Claude Code so you can change its system prompts, themes, thinking verbs, spinners, input highlighters, toolsets, and a long tail of UI/perf knobs — without forking. Maintained by Piebald LLC.

It is a binary patcher, not a wrapper or a plugin loader. You run npx tweakcc, configure things in a TUI, and tweakcc rewrites Claude Code's cli.js (or, for native installs, extracts the embedded JS, patches it, and repacks the binary). Settings live in ~/.tweakcc/config.json and are reapplied after each Claude Code upgrade with tweakcc --apply.

Listed on watchlist — every release of Claude Code is a potential break, and the project's value depends entirely on Piebald keeping up with Anthropic.

How it works

Two paths depending on the install:

  • npm installs — directly edits the minified cli.js in place.
  • Native binaries — uses node-lief (LIEF bindings) to extract the embedded JS blob from the binary, applies the same patches, then repacks. Required for Homebrew, the Anthropic-shipped native CCs, and similar.

Patches are version-pinned. The README lists CC 2.1.62 as the verified target; the system-prompt patches reach back to 2.0.14 because tweakcc keeps a per-version corpus of original prompts in-repo. Other patches (UI, perf) are best-effort on older versions.

For ad-hoc work, tweakcc adhoc-patch runs a one-off string/regex/script substitution inside a sandboxed Node (--experimental-permission). The TUI is built with Ink + React.

What it can change

  • System prompts — edits live as markdown files in ~/.tweakcc/system-prompts/, covering all 17 built-in tools and agent workflows. Conflict detection when Anthropic ships new prompts.
  • Themes — visual HSL/RGB color picker; themes selected via Claude Code's own /theme command.
  • Thinking verbs and spinners — replace the verb list and the format string ("Claude is {verb}ing..."); configure spinner phases and speeds.
  • Input pattern highlighters — regex → color in the input box (the old ultrathink rainbow effect lives here).
  • Toolsets — selectively disable tools by removing them from the prompt that goes to the model. Not just UI hiding.
  • AGENTS.md support — fall back to other instruction-file names (GEMINI.md, CRUSH.md, etc.) for cross-harness portability with flue / library-skills / agent-skill-linter conventions.
  • Auto-accept plan mode (2.1.22+), session memory + /remember skill, MCP non-blocking startup with batch sizes 1-20, table style picker, token rounding, statusline throttling, scroll-escape filtering, optional --dangerously-skip-permissions under sudo.
  • Opus Plan 1M — Opus 4.5 for planning with Sonnet 4.5's 1M-context window for execution.

Usage

# Configure interactively
npx tweakcc

# Apply saved config (run after every CC upgrade)
npx tweakcc --apply

# Revert to stock CC
npx tweakcc --restore

# One-off patch
npx tweakcc adhoc-patch

# Native-binary surgery
npx tweakcc unpack /path/to/cc
npx tweakcc repack /path/to/cc

Config dir resolution: TWEAKCC_CONFIG_DIR → ~/.tweakcc/ → ~/.claude/tweakcc/ → $XDG_CONFIG_HOME/tweakcc.

Configs can be loaded over HTTP for shared team setups: npx tweakcc --apply --config-url https://example.com/config.json. Remote config merges into remoteConfig.settings without overwriting local.

Programmatic API

Also published as a library, so you can build your own patch tooling:

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);

Categories: config, installation, I/O, backup, utilities.

Limitations

  • Tied to specific Claude Code versions — non-system-prompt patches may silently fail on a CC release tweakcc hasn't seen.
  • Patches a closed-source third-party binary; nothing prevents Anthropic from changing internals enough that tweakcc has to chase.
  • Nix/NixOS binary patches need sudo (read-only store) and get garbage-collected by nix-collect-garbage.
  • adhoc-patch skips the backup step — run a regular --apply first if you want --restore to work afterward.

Repo

github.com/Piebald-AI/tweakcc — TypeScript, MIT, ~2,000 stars, 155+ forks. Latest release v4.0.11 (March 5, 2026).

Linked from