🐈 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.

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:

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

pip install ctxcat

Or with exact token counting (adds tiktoken):

pip install 'ctxcat[accurate]'

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

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

Usage

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

# 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

(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) with a test suite. Read it over coffee, break it, fix it.

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

See CONTRIBUTING.md for details.

License

MIT — do whatever you want with it.