Metadata-Version: 2.5
Name: ctxcat
Version: 0.1.0
Summary: cat your repo into LLM context — pack any repository into a single, token-aware, LLM-ready document. Zero dependencies.
Project-URL: Homepage, https://github.com/kamilkubik89/ctxcat
Project-URL: Issues, https://github.com/kamilkubik89/ctxcat/issues
Project-URL: Changelog, https://github.com/kamilkubik89/ctxcat/blob/main/CHANGELOG.md
Author: ctxcat contributors
License: MIT
License-File: LICENSE
Keywords: ai,chatgpt,claude,cli,codebase,context,gpt,llm,prompt,repository
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
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.9
Provides-Extra: accurate
Requires-Dist: tiktoken>=0.5; extra == 'accurate'
Description-Content-Type: text/markdown

<div align="center">

# 🐈 ctxcat

### `cat` your repo into LLM context.

**Pack any repository into a single, clean, token-aware document — ready to paste into Claude, ChatGPT, Gemini or any LLM.**

One file. Zero dependencies. Respects `.gitignore`. Fits your context window.

[![PyPI](https://img.shields.io/pypi/v/ctxcat?color=blue)](https://pypi.org/project/ctxcat/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://pypi.org/project/ctxcat/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![CI](https://github.com/kamilkubik89/ctxcat/actions/workflows/ci.yml/badge.svg)](https://github.com/kamilkubik89/ctxcat/actions)
[![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](pyproject.toml)

<img src="docs/demo.gif" alt="ctxcat demo" width="700">

</div>

---

## Why?

You paste code into an LLM **dozens of times a day**. And every time it's the same dance:

😩 open file → copy → paste → open next file → copy → paste → *"wait, which files did I already paste?"* → the model has no idea how your project is structured → you blow past the context window → start over.

**ctxcat ends the dance:**

```bash
ctxcat --copy
```

That's it. Your entire repo — file tree, every relevant file, properly fenced and labeled — is on your clipboard, trimmed to fit your context window. Paste it. Ask your question. Done.

## Install

```bash
pip install ctxcat
```

Or with exact token counting (adds `tiktoken`):

```bash
pip install 'ctxcat[accurate]'
```

No `pip`? It's a **single file** — just grab it:

```bash
curl -O https://raw.githubusercontent.com/kamilkubik89/ctxcat/main/ctxcat/cli.py
python3 cli.py --help
```

## Usage

```bash
ctxcat                              # pack current dir → stdout
ctxcat ~/projects/myapp -o ctx.md   # pack a repo → file
ctxcat --copy                       # pack → clipboard, ready to paste
ctxcat --list                       # what would be packed, with token counts
ctxcat -i 'src/**' -i '*.md'        # only source + docs
ctxcat -x 'tests/*' -x '*.sql'      # everything except tests and SQL
ctxcat --max-tokens 100000          # guarantee it fits a 100k window
ctxcat -f xml                       # XML output (great for Claude)
ctxcat -f txt | less                # plain text, pipe-friendly
```

## What makes it smart

🧠 **Git-aware.** Inside a git repo, ctxcat asks `git ls-files` — so it respects your `.gitignore` *exactly*, including nested and global ignores. No half-baked reimplementation.

✂️ **Token budget with priorities.** `--max-tokens 100000` doesn't just truncate. It drops files in *reverse order of importance* — tests go first, then generic files, while your README, configs and core source survive. You always know what was trimmed.

🧹 **Sane defaults.** `node_modules`, lockfiles, binaries, images, `.env`, build artifacts, ML model weights — automatically skipped. The stuff you'd never paste anyway.

🔢 **Token counts, always.** Uses `tiktoken` when available, a proven ~4-chars/token heuristic otherwise. Every run tells you exactly how big your context is *before* you paste it.

🛡️ **Fence-safe Markdown.** Files containing ` ``` ` won't break your output — ctxcat picks a longer fence automatically. It's the little things.

📋 **Clipboard built in.** `--copy` works on macOS, Windows, X11 and Wayland. No plugins.

## Example output

````markdown
# Repository: myapp

## File tree

```
├── src/
│   ├── main.py
│   └── util.py
├── README.md
└── pyproject.toml
```

## Files

### README.md
...

### src/main.py

```python
def main():
    ...
```
````

The LLM sees your project the way *you* see it: structure first, then code, every file labeled.

## vs. alternatives

|  | **ctxcat** | repomix | gitingest |
|---|:---:|:---:|:---:|
| Zero dependencies | ✅ | ❌ (Node) | ❌ |
| Single file, curl-able | ✅ | ❌ | ❌ |
| True `.gitignore` support (via git) | ✅ | partial | partial |
| Priority-based token budget | ✅ | ❌ | ❌ |
| Works offline, nothing leaves your machine | ✅ | ✅ | ⚠️ web service |
| Install size | ~15 KB | ~10 MB+ | — |

*(All of these are great projects — ctxcat just optimizes hard for simplicity.)*

## All options

```
ctxcat [path] [options]

  -o, --output FILE      write to FILE instead of stdout
  -f, --format {md,xml,txt}  output format (default: md)
  -i, --include GLOB     only include matching paths (repeatable)
  -x, --exclude GLOB     exclude matching paths (repeatable)
      --max-tokens N     trim lowest-priority files to fit N tokens
      --max-file-kb KB   skip files larger than KB (default: 256)
  -c, --copy             copy result to clipboard
  -l, --list             list files + token counts, don't pack
  -q, --quiet            no summary on stderr
      --version          print version
```

## Philosophy

1. **Do one thing well.** Pack repo → LLM-ready text. That's it.
2. **Zero friction.** No config file, no account, no server, no telemetry.
3. **Your code stays yours.** Everything runs locally. Nothing is uploaded, ever.
4. **Boring technology.** Pure Python stdlib. Auditable in one sitting — it's one file.

## Contributing

PRs welcome! The whole tool is one file ([`ctxcat/cli.py`](ctxcat/cli.py)) with a test suite. Read it over coffee, break it, fix it.

```bash
git clone https://github.com/kamilkubik89/ctxcat
cd ctxcat
python -m pytest        # run tests
python -m ctxcat .      # run from source
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

[MIT](LICENSE) — do whatever you want with it.

---

<div align="center">

**If ctxcat saved you a copy-paste marathon, a ⭐ makes the cat purr.**

</div>
