patch-cc 0.1.0__tar.gz

patch_cc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Lint
+        run: uv run ruff check src/
+
+      - name: Format check
+        run: uv run ruff format --check src/
+
+      - name: Type check
+        run: uv run mypy src/patch_cc

patch_cc-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Verify metadata
+        run: |
+          uv tool run --from twine twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/patch-cc
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

patch_cc-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+
+# uv
+.uv/
+
+# Editors / OS
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# Local artifacts
+*.orig
+*.patched
+content*.js
+claude-*.bin

patch_cc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 André Freire Ferreira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

patch_cc-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: patch-cc
+Version: 0.1.0
+Summary: Interactive patcher for the Claude Code native binary
+Project-URL: Homepage, https://github.com/anfreire/patch-cc
+Project-URL: Repository, https://github.com/anfreire/patch-cc
+Project-URL: Issues, https://github.com/anfreire/patch-cc/issues
+Author-email: André Freire Ferreira <anfreire.dev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bun,claude,claude-code,cli,patch,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: blessed>=1.47.0
+Requires-Dist: lief>=0.15; sys_platform == 'darwin'
+Requires-Dist: rich>=13.7
+Description-Content-Type: text/markdown
+
+# patch-cc
+
+[![CI](https://github.com/anfreire/patch-cc/actions/workflows/ci.yml/badge.svg)](https://github.com/anfreire/patch-cc/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/patch-cc)](https://pypi.org/project/patch-cc/)
+
+An interactive patcher for the **Claude Code native binary**. Pick the tweaks
+you want — inline and live thinking, detailed tool calls, subagent model
+overrides, your own startup name — and apply them to your installed `claude`
+in one keystroke. Pure Python; no Node, no Bun.
+
+## Requirements
+
+- **Linux or macOS**
+- **Python 3.11+**
+- **[uv](https://docs.astral.sh/uv/)** — how patch-cc is run and installed
+  below. Install it with `curl -LsSf https://astral.sh/uv/install.sh | sh`.
+  Not using uv? `pipx install patch-cc` (or `pip install patch-cc`) works too;
+  it is an ordinary PyPI package.
+- **macOS only:** the Xcode command line tools, for `codesign` — a patched
+  binary has to be re-signed or macOS refuses to run it.
+
+```bash
+uvx patch-cc                   # fullscreen menu, no install needed
+```
+
+The menu is a single centered panel: move with `↑ ↓`, toggle with `space`,
+press `s` to save. Patches that carry a setting — subagent models, the startup
+name, the `--version` marker — open a centered modal on `enter`, and the row
+then shows what you chose. Everything choosable is a picker: the agent names
+and model aliases are **discovered from your binary itself**, so the menu can
+never offer something your build would reject. Typing exists only for the two
+genuinely free-text values.
+
+A patched binary records what was applied inside itself, so the menu always
+comes up showing the real current state, and `patch-cc status` answers
+exactly.
+
+Prefer it always available on your PATH? Install it:
+
+```bash
+uv tool install patch-cc
+patch-cc                       # then just run it
+```
+
+## What it can do
+
+| Group | Patch | |
+|---|---|---|
+| Output & diffs | Detailed tool calls | Show full read/search calls, not collapsed summaries |
+| | Colour new files as diffs | Created files render with `+` lines and green |
+| Thinking | Always show thinking | Thinking blocks stay inline — no `ctrl+o` |
+| Live thinking | Stream thinking live | See reasoning as it is generated, inline and in order |
+| Subagents | Show subagent prompts | Prompt blocks visible during normal use |
+| | Override subagent models | Pick the model per built-in agent (discovered from your binary) |
+| Chrome | Disable spinner tips | No rotating tips on the spinner |
+| | Custom startup name | Defaults to `<your username>'s Code` |
+| | Mark `--version` | Appends `(patched)` — or any marker you choose |
+
+## Usage
+
+Everything the menu does is also a non-interactive subcommand (shown with
+`uvx`; drop it if you installed the tool):
+
+```bash
+uvx patch-cc apply                            # the default patch set
+uvx patch-cc apply tool-calls live-thinking   # just these
+uvx patch-cc apply --brand                    # + branding as <username>'s Code
+uvx patch-cc apply --brand "Ada's Code"       # + branding, explicit name
+uvx patch-cc apply --model Explore=haiku --model general-purpose=opus
+uvx patch-cc apply --suffix "(mine)"          # custom --version marker
+uvx patch-cc status                           # exactly what is applied
+uvx patch-cc doctor                           # do all patches match this build?
+uvx patch-cc list                             # patches + your binary's agents/models
+uvx patch-cc restore                          # put the original back
+```
+
+`--model` and `--brand` imply their patches; agents and models are validated
+against what your installed binary actually ships.
+
+## After a Claude update
+
+Claude auto-updates roughly daily and replaces the binary, which reverts the
+patch. Re-run `patch-cc` — the menu remembers your last selection — or re-apply
+your set explicitly:
+
+```bash
+uvx patch-cc apply --brand --model Explore=haiku
+```
+
+`uvx patch-cc status` tells you whether the current binary is patched, and the
+startup name / `--version` marker are visible tells too.
+
+## Why native-only, and why it stays small
+
+Claude Code now ships only as a Bun single-file executable; the npm package is a
+wrapper that downloads it. patch-cc edits the JavaScript bundle embedded in the
+binary's `.bun` section in place. It also drops the module's 154 MB of stale
+precompiled bytecode — editing the source invalidates it anyway — so a patched
+binary is *smaller* than the original (≈113 MB vs 267 MB), not larger.
+
+See [docs/INTERNALS.md](docs/INTERNALS.md) for the container format and
+[docs/PLAYBOOK.md](docs/PLAYBOOK.md) for repairing a patch after an update.
+
+## Credits
+
+The patch set is a Python port of
+[a-connoisseur/patch-claude-code](https://github.com/a-connoisseur/patch-claude-code),
+with the subagent-model override idea from
+[aleks-apostle/claude-code-patches](https://github.com/aleks-apostle/claude-code-patches).
+
+## License
+
+MIT

patch_cc-0.1.0/README.md

@@ -0,0 +1,113 @@
+# patch-cc
+
+[![CI](https://github.com/anfreire/patch-cc/actions/workflows/ci.yml/badge.svg)](https://github.com/anfreire/patch-cc/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/patch-cc)](https://pypi.org/project/patch-cc/)
+
+An interactive patcher for the **Claude Code native binary**. Pick the tweaks
+you want — inline and live thinking, detailed tool calls, subagent model
+overrides, your own startup name — and apply them to your installed `claude`
+in one keystroke. Pure Python; no Node, no Bun.
+
+## Requirements
+
+- **Linux or macOS**
+- **Python 3.11+**
+- **[uv](https://docs.astral.sh/uv/)** — how patch-cc is run and installed
+  below. Install it with `curl -LsSf https://astral.sh/uv/install.sh | sh`.
+  Not using uv? `pipx install patch-cc` (or `pip install patch-cc`) works too;
+  it is an ordinary PyPI package.
+- **macOS only:** the Xcode command line tools, for `codesign` — a patched
+  binary has to be re-signed or macOS refuses to run it.
+
+```bash
+uvx patch-cc                   # fullscreen menu, no install needed
+```
+
+The menu is a single centered panel: move with `↑ ↓`, toggle with `space`,
+press `s` to save. Patches that carry a setting — subagent models, the startup
+name, the `--version` marker — open a centered modal on `enter`, and the row
+then shows what you chose. Everything choosable is a picker: the agent names
+and model aliases are **discovered from your binary itself**, so the menu can
+never offer something your build would reject. Typing exists only for the two
+genuinely free-text values.
+
+A patched binary records what was applied inside itself, so the menu always
+comes up showing the real current state, and `patch-cc status` answers
+exactly.
+
+Prefer it always available on your PATH? Install it:
+
+```bash
+uv tool install patch-cc
+patch-cc                       # then just run it
+```
+
+## What it can do
+
+| Group | Patch | |
+|---|---|---|
+| Output & diffs | Detailed tool calls | Show full read/search calls, not collapsed summaries |
+| | Colour new files as diffs | Created files render with `+` lines and green |
+| Thinking | Always show thinking | Thinking blocks stay inline — no `ctrl+o` |
+| Live thinking | Stream thinking live | See reasoning as it is generated, inline and in order |
+| Subagents | Show subagent prompts | Prompt blocks visible during normal use |
+| | Override subagent models | Pick the model per built-in agent (discovered from your binary) |
+| Chrome | Disable spinner tips | No rotating tips on the spinner |
+| | Custom startup name | Defaults to `<your username>'s Code` |
+| | Mark `--version` | Appends `(patched)` — or any marker you choose |
+
+## Usage
+
+Everything the menu does is also a non-interactive subcommand (shown with
+`uvx`; drop it if you installed the tool):
+
+```bash
+uvx patch-cc apply                            # the default patch set
+uvx patch-cc apply tool-calls live-thinking   # just these
+uvx patch-cc apply --brand                    # + branding as <username>'s Code
+uvx patch-cc apply --brand "Ada's Code"       # + branding, explicit name
+uvx patch-cc apply --model Explore=haiku --model general-purpose=opus
+uvx patch-cc apply --suffix "(mine)"          # custom --version marker
+uvx patch-cc status                           # exactly what is applied
+uvx patch-cc doctor                           # do all patches match this build?
+uvx patch-cc list                             # patches + your binary's agents/models
+uvx patch-cc restore                          # put the original back
+```
+
+`--model` and `--brand` imply their patches; agents and models are validated
+against what your installed binary actually ships.
+
+## After a Claude update
+
+Claude auto-updates roughly daily and replaces the binary, which reverts the
+patch. Re-run `patch-cc` — the menu remembers your last selection — or re-apply
+your set explicitly:
+
+```bash
+uvx patch-cc apply --brand --model Explore=haiku
+```
+
+`uvx patch-cc status` tells you whether the current binary is patched, and the
+startup name / `--version` marker are visible tells too.
+
+## Why native-only, and why it stays small
+
+Claude Code now ships only as a Bun single-file executable; the npm package is a
+wrapper that downloads it. patch-cc edits the JavaScript bundle embedded in the
+binary's `.bun` section in place. It also drops the module's 154 MB of stale
+precompiled bytecode — editing the source invalidates it anyway — so a patched
+binary is *smaller* than the original (≈113 MB vs 267 MB), not larger.
+
+See [docs/INTERNALS.md](docs/INTERNALS.md) for the container format and
+[docs/PLAYBOOK.md](docs/PLAYBOOK.md) for repairing a patch after an update.
+
+## Credits
+
+The patch set is a Python port of
+[a-connoisseur/patch-claude-code](https://github.com/a-connoisseur/patch-claude-code),
+with the subagent-model override idea from
+[aleks-apostle/claude-code-patches](https://github.com/aleks-apostle/claude-code-patches).
+
+## License
+
+MIT

patch_cc-0.1.0/docs/CONDUCT.md

@@ -0,0 +1,54 @@
+# CONDUCT.md — patch-cc
+
+How we build here. What the project *is* and how to use it live in the
+[README](../README.md); this file is the *how*, not the *what*. Read it before
+touching a matcher or the container layer.
+
+## Mindset
+
+Every change reaches for the **minimal, elegant, graceful** form — the simplest
+shape that already absorbs every case, found rather than bolted on.
+
+- **Grace, not branches.** Dissolve edge cases into the common path instead of
+  guarding them with an `if`. Empty, missing, already-applied, absent-on-this-
+  build should flow through the *same* code as the normal case. A special-case
+  branch you could dissolve is a miss, not a smaller win.
+- **DRY — one source of truth.** Every value, rule, and fact has one home;
+  everything else links to it. This holds for the docs too: if it's in the
+  README, don't restate it here. Two copies drift, and the reader can't tell
+  which one is true.
+- **Cut, don't accrete.** Keep the smallest surface that does the job. Delete
+  superseded code, flags, and comments in the same change; add no abstraction
+  for a caller that doesn't exist yet.
+
+## Guidelines
+
+- **Never corrupt the user's binary.** Writes are staged, re-extracted, and
+  verified byte-exact before replacing the original, and a pristine backup
+  always exists for `restore`. A bug should leave a working `claude`, never a
+  brick.
+
+- **Explicit invocations are hermetic.** A non-interactive command's arguments
+  are its whole input; no saved state may silently change what it does, so the
+  same command always yields the same result. Persisted choices belong to the
+  interactive UI alone — they pre-fill a prompt, never trigger an action.
+
+- **Anchor matchers on meaning.** String literals, `case` labels, prop names,
+  control-flow shape — never a minified local that changes every build. A new
+  upstream shape earns a narrow new branch, not a looser regex. Full rules and
+  the repair loop: [PLAYBOOK.md](PLAYBOOK.md).
+
+- **Report absent apart from broken.** A matcher that finds nothing may be a
+  shape this build simply lacks — most patches carry several — not a regression.
+  Keep "gone", "already applied", and "not on this build" as distinct signals;
+  never collapse them into one number.
+
+- **Port faithfully.** When you change a patch, verify its output against the
+  upstream reference on a real bundle — byte-identical where behaviour must not
+  change. The JS→Python porting traps are in [PLAYBOOK.md](PLAYBOOK.md).
+
+- **The user controls commits and releases.** Don't commit, push, or publish
+  unless asked.
+
+The binary format, and why the ELF write is in-place and the bytecode is
+dropped: [INTERNALS.md](INTERNALS.md).

patch_cc-0.1.0/docs/INTERNALS.md

@@ -0,0 +1,115 @@
+# Internals
+
+How patch-cc gets from a 267 MB binary to a patched, smaller one.
+
+## The shape of a native Claude binary
+
+Claude Code ships as a [Bun](https://bun.sh) single-file executable. The whole
+app — a ~20 MB minified JS bundle plus a few asset modules — is embedded in the
+binary:
+
+- **Linux**: an ELF section named `.bun`
+- **macOS**: a Mach-O section `__BUN,__bun`
+- **Windows**: a PE `.bun` section (not supported here)
+
+Inside that section is a *Bun module graph*: a flat arena of payloads, a module
+table describing them, and a trailer.
+
+```
+.bun section
+└── [u64 size prefix]           (u32 on Bun < 1.3.4)
+    └── Bun blob
+        ├── payload arena       name / contents / sourcemap / bytecode / ... bytes
+        ├── module table        N records × 52 bytes (36 on old Bun)
+        ├── compileExecArgv
+        ├── offsets struct       32 bytes: byteCount, modulesPtr, entryId, argvPtr, flags
+        └── "\n---- Bun! ----\n"  15-byte trailer
+```
+
+Every pointer is a `(u32 offset, u32 length)` pair relative to the blob start,
+and pointers live in only two places: the module table and the offsets struct.
+That is what makes rewriting tractable — move a payload, fix the handful of
+pointers that describe it.
+
+A module record (new 52-byte format) is six such pairs — `name`, `contents`,
+`sourcemap`, `bytecode`, `moduleInfo`, `bytecodeOriginPath` — followed by four
+`u8` flags (`encoding`, `loader`, `moduleFormat`, `side`).
+
+The module we patch is the entrypoint, named `/$bunfs/root/src/entrypoints/cli.js`
+(or `claude` / `claude.exe` on other builds). Its `contents` is the JS we edit.
+
+Code: `src/patch_cc/bun/blob.py`.
+
+## The 154 MB bytecode, and why we drop it
+
+The entry module also carries ~154 MB of precompiled Bun **bytecode** — more
+than half the binary. Every other module has none.
+
+Any edit to `contents` invalidates that bytecode; Bun detects the mismatch and
+recompiles from source at launch. So keeping it buys nothing:
+
+| binary | size | startup |
+|---|---|---|
+| original (valid bytecode) | 267 MB | ~100 ms |
+| patched, bytecode kept | 267 MB | ~650 ms |
+| patched, bytecode dropped | **113 MB** | ~650 ms |
+
+Patching pays the recompile cost either way, so patch-cc drops the entry
+module's bytecode (`rebuild(..., drop_bytecode=True)`). The result runs source,
+guaranteeing our edits are authoritative, and is ~154 MB smaller.
+
+`doctor` asserts the patched binary has `bytecode == 0`. If a future Bun build
+makes bytecode authoritative over source, that assert is the tripwire — every
+patch would silently no-op otherwise.
+
+## Writing it back without ballooning
+
+`.bun` is the last *allocated* ELF section; only non-allocated metadata
+(`.comment`, `.symtab`, `.strtab`, `.shstrtab`) follows it. patch-cc rewrites
+the ELF bytes in place:
+
+1. Splice the new (smaller) blob over the old `.bun` bytes.
+2. Shift `e_shoff`, `e_phoff`, and the trailing non-alloc sections/segments by
+   the size delta.
+3. Grow or shrink the containing `PT_LOAD` segment's `filesz`/`memsz` to match.
+
+`.bun` keeps its original file offset. This is deliberately *not* done with a
+general ELF library: LIEF rebuilds the binary and relocates `.bun` so its file
+offset equals its virtual address (`0x20000000`), which inflates the file to
+~715 MB. Raw in-place surgery avoids that entirely.
+
+Guards refuse anything that could corrupt the mapping: allocated sections after
+`.bun`, growth into a header table, an unrelated spanning segment, or a
+misaligned `PT_LOAD` shift. If any fires, the write aborts rather than guesses.
+
+Code: `src/patch_cc/bun/elf.py`. macOS uses LIEF (`macho.py`) — Mach-O segment
+growth is page-aligned and bounded, with no relocation pathology, and every
+edit is followed by an ad-hoc `codesign` (mandatory on Apple Silicon).
+
+## The manifest
+
+Every patched bundle ends with a single comment line:
+
+```
+//patch-cc {"v":1,"tool":"0.1.0","patches":[...],"brand":...,"models":{...}}
+```
+
+That line is why `patch-cc status` can name exactly what is applied: several
+patches are value flips (`verbose:!0`) that leave no other trace. A comment
+can't collide with code and travels with the bundle through extract/repack.
+The menu also reads it to pre-select the current patch set — the binary is the
+state.
+
+## Safety
+
+- Before the first patch of a version, the pristine binary is copied to
+  `~/.local/share/patch-cc/backups/`. `restore` copies it back — never an
+  inverse patch (insertions cascade, so a reverse diff is meaningless).
+- Patching always starts from that pristine copy, so re-applying never stacks
+  edits on edits, and an apply where **no** patch changes anything leaves the
+  binary untouched entirely (stripping bytecode for nothing would only slow
+  startup).
+- Every write is verified: patch-cc re-extracts the JS from the binary it just
+  wrote and asserts it equals what it meant to write.
+- Patching a binary that is already marked, when no pristine backup exists, is
+  refused unless `--force` — there is nothing clean to start from.