Metadata-Version: 2.4
Name: xtrshow
Version: 0.3.1
Summary: The bridge between your local codebase and LLMs.
Author-email: Michael Godfrey <michael@aloecraft.org>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Aloecraft-org/xtrshow
Project-URL: Repository, https://github.com/Aloecraft-org/xtrshow
Keywords: cli,tui,llm,ai,copilot,patch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: windows-curses; sys_platform == "win32"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# xtrshow

<div align="center">

<svg style="height:96px; width:96px;" version="1.1" viewBox="0.0 0.0 768.0 768.0" fill="none" stroke="none" stroke-linecap="square" stroke-miterlimit="10" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg"><clipPath id="p.0"><path d="m0 0l768.0 0l0 768.0l-768.0 0l0 -768.0z" clip-rule="nonzero"/></clipPath><g clip-path="url(#p.0)"><path fill="#000000" fill-opacity="0.0" d="m0 0l768.0 0l0 768.0l-768.0 0z" fill-rule="evenodd"/><g filter="url(#shadowFilter-p.1)"><use xlink:href="#p.1" transform="matrix(1.0 0.0 0.0 1.0 0.0 2.805028083989503)"/></g><defs><filter id="shadowFilter-p.1" filterUnits="userSpaceOnUse"><feGaussianBlur in="SourceAlpha" stdDeviation="6.7076616" result="blur"/><feComponentTransfer in="blur" color-interpolation-filters="sRGB"><feFuncR type="linear" slope="0" intercept="0.0"/><feFuncG type="linear" slope="0" intercept="0.0"/><feFuncB type="linear" slope="0" intercept="0.0"/><feFuncA type="linear" slope="0.75" intercept="0"/></feComponentTransfer></filter></defs><g id="p.1"><defs><linearGradient id="p.2" gradientUnits="userSpaceOnUse" gradientTransform="matrix(26.422419929653632 0.0 0.0 26.422419929653632 0.0 0.0)" spreadMethod="pad" x1="1.245462624943264" y1="1.3215563632917704" x2="1.245366976172699" y2="27.74397629277228"><stop offset="0.0" stop-color="#d4e5f5"/><stop offset="1.0" stop-color="#70a4d5"/></linearGradient></defs><path fill="url(#p.2)" d="m32.90814 383.99213c0 -192.78651 157.17273 -349.07086 351.0551 -349.07086c93.10559 0 182.39783 36.777004 248.23346 102.24048c65.83557 65.463486 102.821655 154.25104 102.821655 246.83038c0 192.7865 -157.17273 349.07086 -351.0551 349.07086c-193.88239 0 -351.0551 -156.28436 -351.0551 -349.07086z" fill-rule="evenodd"/></g><g filter="url(#shadowFilter-p.3)"><use xlink:href="#p.3" transform="matrix(1.0 0.0 0.0 1.0 0.0 3.082887664041986)"/></g><defs><filter id="shadowFilter-p.3" filterUnits="userSpaceOnUse"><feGaussianBlur in="SourceAlpha" stdDeviation="3.0828876" result="blur"/><feComponentTransfer in="blur" color-interpolation-filters="sRGB"><feFuncR type="linear" slope="0" intercept="0.0"/><feFuncG type="linear" slope="0" intercept="0.0"/><feFuncB type="linear" slope="0" intercept="0.0"/><feFuncA type="linear" slope="0.5" intercept="0"/></feComponentTransfer></filter></defs><g id="p.3"><defs><linearGradient id="p.4" gradientUnits="userSpaceOnUse" gradientTransform="matrix(18.853705803581917 -18.8518815453568 18.8518815453568 18.853705803581917 0.0 0.0)" spreadMethod="pad" x1="-8.983571918760429" y1="10.95738858167813" x2="-8.983639598240526" y2="29.811094385138574"><stop offset="0.0" stop-color="#1076d2"/><stop offset="1.0" stop-color="#093053"/></linearGradient></defs><path fill="url(#p.4)" d="m221.25984 560.0285c-94.63638 -94.65381 -98.48603 -244.2471 -8.598419 -334.126q87.41051 -87.402054 162.11848 -187.50893q79.96332 104.10927 171.99176 196.15459c94.63635 94.65378 98.48602 244.24707 8.598389 334.12598c-89.88757 89.87891 -239.47382 86.00812 -334.11023 -8.64563z" fill-rule="evenodd"/></g><g filter="url(#shadowFilter-p.5)"><use xlink:href="#p.5" transform="matrix(1.0 0.0 0.0 1.0 0.0 2.578420209973758)"/></g><defs><filter id="shadowFilter-p.5" filterUnits="userSpaceOnUse"><feGaussianBlur in="SourceAlpha" stdDeviation="14.707419" result="blur"/><feComponentTransfer in="blur" color-interpolation-filters="sRGB"><feFuncR type="linear" slope="0" intercept="0.0"/><feFuncG type="linear" slope="0" intercept="0.0"/><feFuncB type="linear" slope="0" intercept="0.0"/><feFuncA type="linear" slope="0.85" intercept="0"/></feComponentTransfer></filter></defs><g id="p.5"><path fill="#00ff00" d="m270.38263 510.87988c-66.065445 -66.05673 -68.76584 -170.46252 -6.031494 -233.19684q85.294556 -85.294586 110.563995 -230.60641q32.82498 146.81036 122.64859 236.62216c66.06543 66.05673 68.76581 170.46252 6.031494 233.19684c-62.734314 62.734314 -167.14716 60.041016 -233.21259 -6.015747z" fill-rule="evenodd"/><path stroke="#00ff00" stroke-width="22.060367454068242" stroke-linejoin="round" stroke-linecap="butt" d="m270.38263 510.87988c-66.065445 -66.05673 -68.76584 -170.46252 -6.031494 -233.19684q85.294556 -85.294586 110.563995 -230.60641q32.82498 146.81036 122.64859 236.62216c66.06543 66.05673 68.76581 170.46252 6.031494 233.19684c-62.734314 62.734314 -167.14716 60.041016 -233.21259 -6.015747z" fill-rule="evenodd"/></g><defs><linearGradient id="p.6" gradientUnits="userSpaceOnUse" gradientTransform="matrix(16.53370895591199 -16.533708955911997 16.533708955911997 16.53370895591199 0.0 0.0)" spreadMethod="pad" x1="-5.748601497030276" y1="12.723670094197697" x2="-5.751968584823707" y2="29.257378707256184"><stop offset="0.0" stop-color="#ffffff"/><stop offset="0.36" stop-color="#d9ead3"/><stop offset="0.75" stop-color="#d9ead3"/><stop offset="1.0" stop-color="#ffffff"/></linearGradient></defs><path fill="url(#p.6)" d="m295.60068 485.6921c-51.410324 -51.41031 -53.50435 -132.66888 -4.6771545 -181.49606q85.58432 -85.58432 84.03119 -258.3061q7.352844 172.87123 97.464874 262.98325c51.41031 51.41034 53.504364 132.66888 4.6771545 181.49606c-48.82718 48.82721 -130.08575 46.733154 -181.49606 -4.6771545z" fill-rule="evenodd"/><path stroke="#ffffff" stroke-width="11.031496062992126" stroke-linejoin="round" stroke-linecap="butt" d="m295.60068 485.6921c-51.410324 -51.41031 -53.50435 -132.66888 -4.6771545 -181.49606q85.58432 -85.58432 84.03119 -258.3061q7.352844 172.87123 97.464874 262.98325c51.41031 51.41034 53.504364 132.66888 4.6771545 181.49606c-48.82718 48.82721 -130.08575 46.733154 -181.49606 -4.6771545z" fill-rule="evenodd"/><path fill="#ffffff" d="m472.6946 353.82178c28.54486 28.54486 22.756287 80.6138 -12.929138 116.299225c-35.685425 35.685425 -87.75433 41.474 -116.299194 12.929138c31.510498 0.91067505 64.9617 -13.481354 90.35434 -38.873993c25.39264 -25.39264 39.784668 -58.843872 38.873993 -90.35437z" fill-rule="evenodd"/></g></svg>

**Code Extraction & Patching Made Easy**

[![PyPI Version](https://img.shields.io/pypi/v/xtrshow.svg)](https://pypi.org/project/xtrshow/)
[![Python Versions](https://img.shields.io/pypi/pyversions/xtrshow.svg)](https://pypi.org/project/xtrshow/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[![CI Status](https://github.com/Aloecraft-org/xtrshow/actions/workflows/main.yml/badge.svg)](https://github.com/Aloecraft-org/xtrshow/actions/workflows/main.yml)
[![Downloads](https://static.pepy.tech/badge/xtrshow)](https://pepy.tech/project/xtrshow)

</div>

`xtrshow` is a CLI suite designed to optimize the "Context Injection" and "Code Application" loop when working with AI coding assistants (ChatGPT, Claude, Gemini, etc.).

It solves the two biggest points of friction in AI-assisted development:

1.  **Getting code INTO the LLM:** Quickly selecting relevant files and formatting them so the model can reference exact lines.
2.  **Getting code OUT of the LLM:** Applying changes safely without manually copy-pasting dozens of snippets.

## Installation

```bash
pip install xtrshow
```

## `xtrshow` and `xtrpatch` Commands: Quickstart

The workflow consists of three steps: **Extract, Prompt, Apply**.

1. **Extract Context:** Run `xtrshow` to interactively select files and copy them to your clipboard.
```bash
xtrshow | pbcopy  # (MacOS/Linux)
```
2. **Prompt:** Paste the context into your LLM, then ask it to reply using the **Search & Replace Block** format. Print a copy-pasteable instruction block with:
```bash
xtrshow -p
```
3. **Apply:** Save the LLM's response to a file (e.g., `changes.txt`) and apply it.
```bash
xtrpatch changes.txt
```

> **Tip:** Iterating on the same set of files? Skip reselection and re-export the last selection with `xtrshow --update`.

👉 **[Read the Full Getting Started Guide](doc/GETTING_STARTED.md)**

## Features

### `xtrshow` (The Extractor)

* **Interactive TUI:** Browse and select files with a fast, keyboard-driven interface.
* **LLM-Optimized Output:** Formats code with line numbers and file headers so the model can anchor edits to exact locations.
* **Smart Filtering:** Automatically ignores noise directories like `node_modules`, `.git`, and build artifacts.
* **Re-Export:** Re-run the last selection without touching the TUI via `--update`.
* **Multi-File Export:** Dump separate files for RAG pipelines via `--multi`.

### `xtrpatch` (The Patcher)

* **Safety First:** Automatic, versioned atomic backups for every modified file.
* **Checksum Verification:** Detects when a file has changed since its last backup, guarding against silent overwrites.
* **Robust Matching:** "Fuzzy" whitespace matching handles common LLM indentation errors.
* **Wildcard Anchors:** `~~~~` lets the model skip volatile interior lines and anchor only on stable signatures — dramatically reducing failed patches.
* **Conflict Detection:** Catches overlapping edit blocks before they corrupt a file.
* **Full Lifecycle:** Create files, delete sections, delete whole files (`! DELETE FILE`), and modify existing code.
* **Undo Button:** Built-in `--revert` command to instantly unwind changes.

👉 **[See Detailed Feature List](doc/FEATURES.md)**

## Prompting the LLM

To use `xtrpatch` effectively, instruct the LLM to output code as Search and Replace Blocks. Standard git diffs are often too fragile for LLM generation.

Run `xtrshow -p` to print a copy-pasteable instruction block for this purpose.

## Advanced Workflows

For power users of **Google Gemini**, we have developed a comprehensive "Developer Protocol" that turns the LLM into a more reliable pair programmer with persistent state management and standardized output formats.

👉 **[See the Gemini Protocol](doc/GEMINI.md)**

## License

Apache 2.0
