# tweakcc

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 [[toolbox/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](https://github.com/lief-project/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 [[toolbox/flue|flue]] / [[toolbox/library-skills|library-skills]] / [[toolbox/agent-skill-linter|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

```bash
# 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:

```typescript
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](https://github.com/Piebald-AI/tweakcc) — TypeScript, MIT, ~2,000 stars, 155+ forks. Latest release v4.0.11 (March 5, 2026).