# tweakcc — Claude Code Customization Tool

# 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

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

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

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:

```bash
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.