tweakcc: Patching Claude Code's Prompts, Themes and Toolsets

What tweakcc actually changes in Claude Code

Claude Code ships as a minified JavaScript bundle, either installed through npm or wrapped in a Bun binary for native installs. Neither form exposes configuration for system prompts, thinking verbs or the input box border. tweakcc exists to edit that bundle after installation. The README describes it as a CLI tool that upgrades your Claude Code experience, and the feature list is long: custom system prompts, custom toolsets reachable through a /toolset command, input pattern highlighters, session naming with /title or /rename, custom themes, thinking verbs, spinner animations, user message styling, table formats, and per-subagent model selection.

The audience is narrow but real. If you use Claude Code as a plain chat client, most of these patches are cosmetic. If you treat it as an agent harness you configure, the interesting items are the ones that change behavior rather than appearance: rewriting the system prompt, swapping which model each subagent uses, and adding the opusplan[1m] alias that pairs Opus for planning with Sonnet's 1M context for execution. The project also bundles fixes, including a workaround for a frozen spinner when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set, and a startup change that the README claims speeds up Claude Code startup by roughly 50 percent through non-blocking MCP connections with a configurable parallel connection batch size. That number comes from the project's own issue reference, not from an independent measurement.

How the patching mechanism works

tweakcc does not wrap Claude Code or intercept its network traffic. It locates the installed Claude Code files, unpacks them if necessary, rewrites portions of the compiled JavaScript, and repacks the result. The repository layout reflects this: a src directory for the tool itself, a data directory that holds the patch definitions and prompt text, and a tools directory. The package is ESM (type module) and exposes both a binary at dist/index.mjs and a library entry at dist/lib/index.mjs with type declarations.

Because the target is minified code, the patches are necessarily pattern-based. That is the central design constraint. A patch that matches a string in Claude Code's bundle today may match nothing after Anthropic changes that string, which is why the project tracks releases closely and why the README points users at tweakcc --restore when something goes wrong. Version 4.0.0 added two escape hatches for this: adhoc-patch, which runs sandboxed scripts so you can write a one-off patch without forking tweakcc, and remote config, which applies customizations from a URL into a config file. The adhoc-patch path is the honest admission that the maintainers cannot cover every user's edge case in the main tree.

The README also documents unpack and repack as separate commands, which matters for anyone who wants to inspect what is being changed before committing to it.

Installing tweakcc and applying a first theme

The README's demo shows the interactive path: run the tool, create a theme, change the UI colors, adjust the thinking format, apply, then launch Claude Code and switch themes with /config. The package is published to npm, so no global install is required.

npx tweakcc

That launches the interactive interface. You should see a menu of customization categories rather than a one-shot command that immediately rewrites files; the demo GIF walks through creating a new theme and applying changes before starting Claude. If you prefer a persistent install, the package name is tweakcc and the binary is also called tweakcc.

npm i -g tweakcc
tweakcc --restore

The second command is the undo path. Run it if a patch breaks your Claude Code install. The README references --restore alongside unpack and repack as the recovery commands, though it does not spell out what state a partial restore leaves behind.

For programmatic use, version 4.0.0 exposes a library entry point. The README instructs npm i tweakcc to add it to your project and points at the API section.

npm i tweakcc

What the library exports is described in the README's API section, which is beyond what the repository metadata here shows. Read that section before building on it.

The update treadmill is the real cost

Every Claude Code release is a potential breakage. tweakcc patches compiled output, so when Anthropic changes the bundle, a patch can silently stop applying. The project's own release cadence reflects this pressure: three patch releases between July and August 2026, all version 4.3.x, which is the shape of a project chasing an upstream moving target rather than shipping planned features.

There is a second failure mode that is easy to miss. If you install Claude Code through a package manager that verifies checksums, or through a managed environment that reinstalls the binary on update, your patches vanish or the verification fails. The README lists support for npm, yarn, pnpm, bun, Homebrew and Linuxbrew, nvm, fnm, n, volta, nvs, nodenv, Nix including NixOS and nix-darwin, plus custom locations. That breadth is impressive, but each of those installers updates Claude Code on its own schedule, and tweakcc's patches are not part of that update path. You reapply after each one.

This is also where tweakcc is the wrong tool. If you need a reproducible Claude Code configuration across a team, or you are running it inside CI where an unexpected prompt change could alter agent behavior, patching a binary is the wrong layer. A wrapper script or a custom system prompt passed at invocation time is more stable, even if it gives you less control over the interface.

tweakcc compared with forking or wrapping Claude Code

The obvious alternative is to fork Claude Code or build your own harness on the Anthropic API. Forking gives you the same control tweakcc offers without the fragility, because you own the source. The cost is that you now maintain a fork of a fast-moving product, and you lose upstream fixes until you merge them. tweakcc trades that maintenance burden for a different one: reapplying patches after each upstream release, but never having to merge code.

A lighter alternative is to leave Claude Code alone and control behavior from the outside, through AGENTS.md or CLAUDE.md files in your repository, or through environment variables. The README notes that tweakcc itself adds AGENTS.md support as a patch, which implies stock Claude Code does not read that file the same way. If your goal is only to influence what the agent does in a given repository, a checked-in instruction file is versioned, reviewable and survives updates. It cannot change theme colors or thinking verbs, and it cannot unlock features Anthropic has not shipped.

That last point is worth stating plainly. Several tweakcc patches, including session memory and the /remember skill, expose functionality the README describes as coming to Claude Code. Using them means running unreleased code paths through a patched binary. That is a legitimate choice for a personal machine and a bad one for anything you depend on.

Maintenance status, licence and upgrade cost

The repository is not archived and the last push was on 2026-09-10, a week before this writing, so the project is current. The most recent tagged release is v4.3.3 from 2026-08-13, with v4.3.2 and v4.3.1 before it in July. Development is active in the plain sense that commits and releases are recent, and the changelog file at the repository root is where release notes live.

The licence is MIT, declared in both the README metadata and package.json, with copyright held by Piebald LLC. MIT permits commercial use, modification and redistribution with the licence text retained. It offers no warranty, which matters here more than in a typical library: you are modifying another vendor's installed software, and neither the MIT grant nor the project's documentation addresses what Anthropic's terms say about patching Claude Code. That is a question for your own review, not something the repository answers.

The upgrade cost is the practical issue. You need to re-run tweakcc after each Claude Code update, and you need a way to notice when a patch stops applying. The README does not document a verification command that reports which patches are currently active, so the check is manual: run the tool and see whether your customizations still appear in Claude Code's interface.

Editorial conclusion

Adopt tweakcc if you already run Claude Code daily and want control over its prompts, theme colors, thinking verbs or subagent models without forking anything. Skip it if you need a stable, reproducible environment: it edits an installed binary, so a Claude Code update can wipe your customizations, and the README does not document rollback beyond the --restore flag. Before relying on it, verify that your installation type is one tweakcc detects, and run the unpack and repack commands once on a scratch machine to see exactly what gets rewritten.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Piebald-AI/tweakcc on GitHub
4. README
5. Releases