ctxcat 0.1.0__tar.gz

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

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: pip install pytest .
+      - name: Test
+        run: python -m pytest -v
+      - name: Smoke test (dogfood)
+        run: ctxcat . --list
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: pip install build && python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

ctxcat-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.idea/
+.vscode/

ctxcat-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0] - 2026-08-28
+
+### Added
+- Initial release 🎉
+- Pack any repository into Markdown, XML or plain text
+- Git-aware file discovery (`git ls-files`) with full `.gitignore` support
+- Fallback directory walker with sane default ignores (node_modules, lockfiles, binaries, .env, …)
+- Token counting: tiktoken when available, ~4 chars/token heuristic otherwise
+- `--max-tokens` budget with priority-based trimming (README/configs survive, tests go first)
+- `--include` / `--exclude` glob filters
+- `--copy` clipboard support (macOS, Windows, X11, Wayland)
+- `--list` dry-run mode with per-file token counts
+- Fence-safe Markdown output (handles files containing ```)
+- Single-file implementation, zero runtime dependencies

ctxcat-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to ctxcat
+
+Thanks for considering a contribution! ctxcat is intentionally tiny — the entire
+tool lives in one file: `ctxcat/cli.py`.
+
+## Ground rules
+
+1. **Zero runtime dependencies.** This is the core promise. PRs adding required
+   dependencies will be declined (optional extras like `tiktoken` are fine).
+2. **One file.** The implementation stays in `cli.py`. If it can't fit, it
+   probably doesn't belong in ctxcat.
+3. **Every feature needs a test.** See `tests/test_ctxcat.py`.
+
+## Development setup
+
+```bash
+git clone https://github.com/kamilkubik89/ctxcat
+cd ctxcat
+pip install pytest
+python -m pytest          # run the test suite
+python -m ctxcat .        # run from source
+```
+
+## Submitting changes
+
+- Open an issue first for anything non-trivial.
+- Keep PRs focused: one change per PR.
+- Run `python -m pytest` before pushing.
+
+## Reporting bugs
+
+Include: your OS, Python version (`python --version`), the exact command you
+ran, and what you expected vs. what happened.

ctxcat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ctxcat contributors
+
+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.

ctxcat-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+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>

ctxcat-0.1.0/README.md

@@ -0,0 +1,174 @@
+<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>

ctxcat-0.1.0/ctxcat/__init__.py

@@ -0,0 +1,4 @@
+"""ctxcat — cat your repo into LLM context."""
+from ctxcat.cli import __version__, main
+
+__all__ = ["main", "__version__"]

ctxcat-0.1.0/ctxcat/__main__.py

@@ -0,0 +1,4 @@
+from ctxcat.cli import main
+import sys
+
+sys.exit(main())

ctxcat-0.1.0/ctxcat/cli.py

@@ -0,0 +1,489 @@
+#!/usr/bin/env python3
+"""ctxcat — cat your repo into LLM context.
+
+Packs an entire repository into a single, clean, token-aware document
+ready to paste into Claude, ChatGPT, Gemini or any LLM.
+
+Zero dependencies. Single file. Respects .gitignore.
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+__version__ = "0.1.0"
+
+# ---------------------------------------------------------------------------
+# Defaults
+# ---------------------------------------------------------------------------
+
+DEFAULT_IGNORE_DIRS = {
+    ".git", ".hg", ".svn", ".idea", ".vscode", "__pycache__",
+    "node_modules", "vendor", "dist", "build", "target", "out",
+    ".next", ".nuxt", ".svelte-kit", ".turbo", ".cache", ".parcel-cache",
+    ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox", ".venv", "venv",
+    "coverage", ".coverage", ".gradle", ".terraform", ".serverless",
+    "Pods", "DerivedData", ".dart_tool", ".angular",
+}
+
+DEFAULT_IGNORE_FILES = {
+    "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb",
+    "Cargo.lock", "poetry.lock", "Pipfile.lock", "composer.lock",
+    "Gemfile.lock", "go.sum", "uv.lock", "flake.lock",
+    ".DS_Store", "Thumbs.db", ".env",
+}
+
+BINARY_EXTENSIONS = {
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".ico", ".icns",
+    ".svgz", ".tif", ".tiff", ".psd", ".ai", ".sketch",
+    ".mp3", ".mp4", ".wav", ".flac", ".ogg", ".avi", ".mov", ".mkv", ".webm",
+    ".zip", ".tar", ".gz", ".bz2", ".xz", ".zst", ".7z", ".rar", ".jar",
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+    ".exe", ".dll", ".so", ".dylib", ".bin", ".o", ".a", ".lib",
+    ".pyc", ".pyo", ".class", ".wasm", ".ttf", ".otf", ".woff", ".woff2",
+    ".eot", ".db", ".sqlite", ".sqlite3", ".parquet", ".pkl", ".pt", ".pth",
+    ".onnx", ".h5", ".npy", ".npz",
+}
+
+EXT_TO_LANG = {
+    ".py": "python", ".js": "javascript", ".jsx": "jsx", ".ts": "typescript",
+    ".tsx": "tsx", ".rb": "ruby", ".go": "go", ".rs": "rust", ".java": "java",
+    ".kt": "kotlin", ".swift": "swift", ".c": "c", ".h": "c", ".cpp": "cpp",
+    ".hpp": "cpp", ".cs": "csharp", ".php": "php", ".sh": "bash",
+    ".bash": "bash", ".zsh": "bash", ".fish": "fish", ".ps1": "powershell",
+    ".html": "html", ".htm": "html", ".css": "css", ".scss": "scss",
+    ".sass": "sass", ".less": "less", ".json": "json", ".yaml": "yaml",
+    ".yml": "yaml", ".toml": "toml", ".xml": "xml", ".md": "markdown",
+    ".rst": "rst", ".sql": "sql", ".graphql": "graphql", ".proto": "protobuf",
+    ".dockerfile": "dockerfile", ".tf": "hcl", ".vue": "vue",
+    ".svelte": "svelte", ".dart": "dart", ".ex": "elixir", ".exs": "elixir",
+    ".erl": "erlang", ".hs": "haskell", ".lua": "lua", ".r": "r",
+    ".scala": "scala", ".clj": "clojure", ".zig": "zig", ".nim": "nim",
+}
+
+# Files that matter most when trimming to a token budget.
+# Checked in order; source code (priority 2) is the default.
+PRIORITY_PATTERNS = [
+    (0, ["readme*", "*.md"]),
+    (1, ["pyproject.toml", "package.json", "cargo.toml", "go.mod",
+         "makefile", "dockerfile", "docker-compose*", "*.toml", "*.yaml", "*.yml"]),
+    (3, ["tests/*", "test/*", "*_test.*", "test_*", "*.spec.*", "*.test.*"]),
+]
+DEFAULT_PRIORITY = 2
+
+
+# ---------------------------------------------------------------------------
+# Data
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RepoFile:
+    path: Path          # absolute
+    rel: str            # relative, posix-style
+    content: str = ""
+    tokens: int = 0
+    priority: int = 2
+
+
+@dataclass
+class PackResult:
+    files: list[RepoFile] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    trimmed: list[str] = field(default_factory=list)
+    total_tokens: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Token counting
+# ---------------------------------------------------------------------------
+
+def make_token_counter():
+    """Return (fn, name). Uses tiktoken when available, else a heuristic."""
+    try:
+        import tiktoken  # type: ignore
+        enc = tiktoken.get_encoding("cl100k_base")
+        return (lambda text: len(enc.encode(text, disallowed_special=()))), "tiktoken/cl100k"
+    except Exception:
+        # ~4 chars per token is a solid approximation for code in English.
+        return (lambda text: max(1, (len(text) + 3) // 4)), "heuristic (~4 chars/token)"
+
+
+# ---------------------------------------------------------------------------
+# File discovery
+# ---------------------------------------------------------------------------
+
+def git_ls_files(root: Path) -> list[str] | None:
+    """Fast path: let git tell us what's tracked/untracked-but-not-ignored."""
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(root), "ls-files", "--cached", "--others",
+             "--exclude-standard", "-z"],
+            capture_output=True, check=True, timeout=15,
+        )
+        entries = [e for e in out.stdout.decode("utf-8", "replace").split("\0") if e]
+        return entries
+    except Exception:
+        return None
+
+
+def walk_files(root: Path) -> list[str]:
+    """Fallback: manual walk with sane default ignores."""
+    results: list[str] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(
+            d for d in dirnames
+            if d not in DEFAULT_IGNORE_DIRS and not d.startswith(".")
+        )
+        for name in sorted(filenames):
+            rel = os.path.relpath(os.path.join(dirpath, name), root)
+            results.append(rel.replace(os.sep, "/"))
+    return results
+
+
+def is_binary(path: Path) -> bool:
+    if path.suffix.lower() in BINARY_EXTENSIONS:
+        return True
+    try:
+        with open(path, "rb") as f:
+            chunk = f.read(2048)
+        return b"\0" in chunk
+    except OSError:
+        return True
+
+
+def matches_any(rel: str, patterns: list[str]) -> bool:
+    name = rel.rsplit("/", 1)[-1]
+    for pat in patterns:
+        if fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(name, pat):
+            return True
+        # allow directory-style patterns like "src/" or "src"
+        if rel.startswith(pat.rstrip("/") + "/"):
+            return True
+    return False
+
+
+def priority_of(rel: str) -> int:
+    low = rel.lower()
+    name = low.rsplit("/", 1)[-1]
+    for prio, pats in PRIORITY_PATTERNS:
+        for pat in pats:
+            if fnmatch.fnmatch(low, pat) or fnmatch.fnmatch(name, pat):
+                return prio
+    return DEFAULT_PRIORITY
+
+
+# ---------------------------------------------------------------------------
+# Packing
+# ---------------------------------------------------------------------------
+
+def collect(
+    root: Path,
+    include: list[str],
+    exclude: list[str],
+    max_file_kb: int,
+    count_tokens,
+) -> PackResult:
+    result = PackResult()
+    rels = git_ls_files(root)
+    if rels is None:
+        rels = walk_files(root)
+
+    seen = set()
+    for rel in rels:
+        if rel in seen:
+            continue
+        seen.add(rel)
+        path = root / rel
+        if not path.is_file():
+            continue
+
+        parts = rel.split("/")
+        name = parts[-1]
+
+        if any(p in DEFAULT_IGNORE_DIRS for p in parts[:-1]):
+            result.skipped.append(f"{rel} (ignored dir)")
+            continue
+        if name in DEFAULT_IGNORE_FILES:
+            result.skipped.append(f"{rel} (lockfile/junk)")
+            continue
+        if exclude and matches_any(rel, exclude):
+            result.skipped.append(f"{rel} (--exclude)")
+            continue
+        if include and not matches_any(rel, include):
+            continue
+        if is_binary(path):
+            result.skipped.append(f"{rel} (binary)")
+            continue
+        try:
+            size_kb = path.stat().st_size / 1024
+        except OSError:
+            continue
+        if size_kb > max_file_kb:
+            result.skipped.append(f"{rel} ({size_kb:.0f} KB > --max-file-kb {max_file_kb})")
+            continue
+        try:
+            content = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            result.skipped.append(f"{rel} (unreadable)")
+            continue
+
+        rf = RepoFile(path=path, rel=rel, content=content,
+                      tokens=count_tokens(content), priority=priority_of(rel))
+        result.files.append(rf)
+
+    result.files.sort(key=lambda f: (f.priority, f.rel))
+    result.total_tokens = sum(f.tokens for f in result.files)
+    return result
+
+
+def apply_budget(result: PackResult, max_tokens: int, overhead: int) -> None:
+    """Drop lowest-priority files (from the end) until we fit the budget."""
+    budget = max_tokens - overhead
+    while result.files and result.total_tokens > budget:
+        dropped = result.files.pop()  # list is sorted best-first
+        result.total_tokens -= dropped.tokens
+        result.trimmed.append(f"{dropped.rel} (~{dropped.tokens:,} tokens)")
+    result.trimmed.reverse()
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+
+def build_tree(rels: list[str]) -> str:
+    """Render a compact directory tree from relative paths."""
+    tree: dict = {}
+    for rel in rels:
+        node = tree
+        for part in rel.split("/"):
+            node = node.setdefault(part, {})
+
+    lines: list[str] = []
+
+    def render(node: dict, prefix: str) -> None:
+        entries = sorted(node.items(), key=lambda kv: (not kv[1], kv[0].lower()))
+        for i, (name, child) in enumerate(entries):
+            last = i == len(entries) - 1
+            connector = "└── " if last else "├── "
+            lines.append(prefix + connector + name + ("/" if child else ""))
+            if child:
+                render(child, prefix + ("    " if last else "│   "))
+
+    render(tree, "")
+    return "\n".join(lines)
+
+
+def lang_for(rel: str) -> str:
+    name = rel.rsplit("/", 1)[-1].lower()
+    if name == "dockerfile":
+        return "dockerfile"
+    if name == "makefile":
+        return "makefile"
+    return EXT_TO_LANG.get(Path(rel).suffix.lower(), "")
+
+
+def pick_fence(content: str) -> str:
+    """Choose a backtick fence longer than any run of backticks in content."""
+    longest = 0
+    for m in re.finditer(r"`+", content):
+        longest = max(longest, len(m.group(0)))
+    return "`" * max(3, longest + 1)
+
+
+def render_markdown(root: Path, result: PackResult) -> str:
+    parts = [
+        f"# Repository: {root.name}",
+        "",
+        "This document contains the full source of the repository, "
+        "packed for LLM consumption by ctxcat.",
+        "",
+        "## File tree",
+        "",
+        "```",
+        build_tree([f.rel for f in result.files]),
+        "```",
+        "",
+        "## Files",
+        "",
+    ]
+    for f in result.files:
+        fence = pick_fence(f.content)
+        lang = lang_for(f.rel)
+        parts.append(f"### {f.rel}")
+        parts.append("")
+        parts.append(f"{fence}{lang}")
+        parts.append(f.content.rstrip("\n"))
+        parts.append(fence)
+        parts.append("")
+    return "\n".join(parts)
+
+
+def render_xml(root: Path, result: PackResult) -> str:
+    def esc(s: str) -> str:
+        return s.replace("&", "&amp;").replace("<", "&lt;")
+
+    parts = [
+        f'<repository name="{root.name}" packed_by="ctxcat">',
+        "<file_tree>",
+        esc(build_tree([f.rel for f in result.files])),
+        "</file_tree>",
+    ]
+    for f in result.files:
+        parts.append(f'<file path="{f.rel}">')
+        parts.append(esc(f.content.rstrip("\n")))
+        parts.append("</file>")
+    parts.append("</repository>")
+    return "\n".join(parts)
+
+
+def render_plain(root: Path, result: PackResult) -> str:
+    sep = "=" * 72
+    parts = [f"Repository: {root.name}", ""]
+    for f in result.files:
+        parts += [sep, f"FILE: {f.rel}", sep, f.content.rstrip("\n"), ""]
+    return "\n".join(parts)
+
+
+RENDERERS = {"md": render_markdown, "xml": render_xml, "txt": render_plain}
+
+
+# ---------------------------------------------------------------------------
+# Clipboard
+# ---------------------------------------------------------------------------
+
+def copy_to_clipboard(text: str) -> bool:
+    cmds = []
+    if sys.platform == "darwin":
+        cmds = [["pbcopy"]]
+    elif os.name == "nt":
+        cmds = [["clip"]]
+    else:
+        cmds = [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "-b"]]
+    for cmd in cmds:
+        try:
+            subprocess.run(cmd, input=text.encode(), check=True, timeout=10)
+            return True
+        except Exception:
+            continue
+    return False
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def human(n: int) -> str:
+    return f"{n:,}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point; exits cleanly when piped into head/less."""
+    try:
+        return _main(argv)
+    except BrokenPipeError:
+        # Piped into `head`, `less` etc. and the reader closed early — fine.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        return 0
+
+
+def _main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="ctxcat",
+        description="Pack a repository into a single LLM-ready document.",
+        epilog="Examples:\n"
+               "  ctxcat                          # pack current dir to stdout\n"
+               "  ctxcat ~/proj -o context.md     # write to a file\n"
+               "  ctxcat -i 'src/**' -i '*.md'    # only src/ and markdown\n"
+               "  ctxcat -x 'tests/*' --copy      # skip tests, copy to clipboard\n"
+               "  ctxcat --max-tokens 100000      # fit a 100k context window\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("path", nargs="?", default=".", help="repository root (default: .)")
+    p.add_argument("-o", "--output", metavar="FILE", help="write output to FILE instead of stdout")
+    p.add_argument("-f", "--format", choices=sorted(RENDERERS), default="md",
+                   help="output format (default: md)")
+    p.add_argument("-i", "--include", action="append", default=[], metavar="GLOB",
+                   help="only include paths matching GLOB (repeatable)")
+    p.add_argument("-x", "--exclude", action="append", default=[], metavar="GLOB",
+                   help="exclude paths matching GLOB (repeatable)")
+    p.add_argument("--max-tokens", type=int, metavar="N",
+                   help="trim lowest-priority files to fit N tokens")
+    p.add_argument("--max-file-kb", type=int, default=256, metavar="KB",
+                   help="skip files larger than KB kilobytes (default: 256)")
+    p.add_argument("-c", "--copy", action="store_true", help="copy result to clipboard")
+    p.add_argument("-l", "--list", action="store_true",
+                   help="list files and token counts, don't pack")
+    p.add_argument("-q", "--quiet", action="store_true", help="suppress the summary on stderr")
+    p.add_argument("--version", action="version", version=f"ctxcat {__version__}")
+    args = p.parse_args(argv)
+
+    root = Path(args.path).expanduser().resolve()
+    if not root.is_dir():
+        print(f"ctxcat: error: not a directory: {root}", file=sys.stderr)
+        return 2
+
+    count_tokens, counter_name = make_token_counter()
+    result = collect(root, args.include, args.exclude, args.max_file_kb, count_tokens)
+
+    if not result.files:
+        print("ctxcat: no matching text files found.", file=sys.stderr)
+        return 1
+
+    if args.list:
+        width = max(len(f.rel) for f in result.files)
+        for f in result.files:
+            print(f"{f.rel:<{width}}  ~{human(f.tokens)} tokens")
+        print(f"\n{len(result.files)} files, ~{human(result.total_tokens)} tokens "
+              f"({counter_name})")
+        return 0
+
+    if args.max_tokens:
+        overhead = count_tokens(build_tree([f.rel for f in result.files])) + 200
+        apply_budget(result, args.max_tokens, overhead)
+        if not result.files:
+            print("ctxcat: error: --max-tokens too small to fit anything.", file=sys.stderr)
+            return 1
+
+    output = RENDERERS[args.format](root, result)
+    final_tokens = count_tokens(output)
+
+    if args.output:
+        Path(args.output).write_text(output, encoding="utf-8")
+    elif not args.copy:
+        print(output)
+
+    if args.copy:
+        if copy_to_clipboard(output):
+            if not args.quiet:
+                print("✔ copied to clipboard", file=sys.stderr)
+        else:
+            print("ctxcat: warning: no clipboard tool found "
+                  "(install xclip / wl-clipboard), printing instead.", file=sys.stderr)
+            print(output)
+
+    if not args.quiet:
+        print(f"\n📦 {len(result.files)} files packed  ·  "
+              f"~{human(final_tokens)} tokens ({counter_name})", file=sys.stderr)
+        if result.trimmed:
+            print(f"✂ trimmed {len(result.trimmed)} files to fit --max-tokens:",
+                  file=sys.stderr)
+            for t in result.trimmed[:10]:
+                print(f"    - {t}", file=sys.stderr)
+            if len(result.trimmed) > 10:
+                print(f"    … and {len(result.trimmed) - 10} more", file=sys.stderr)
+        if args.output:
+            print(f"→ written to {args.output}", file=sys.stderr)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ctxcat-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ctxcat"
+version = "0.1.0"
+description = "cat your repo into LLM context — pack any repository into a single, token-aware, LLM-ready document. Zero dependencies."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "ctxcat contributors" }]
+keywords = ["llm", "ai", "context", "prompt", "repository", "cli", "claude", "chatgpt", "gpt", "codebase"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+
+[project.optional-dependencies]
+accurate = ["tiktoken>=0.5"]
+
+[project.urls]
+Homepage = "https://github.com/kamilkubik89/ctxcat"
+Issues = "https://github.com/kamilkubik89/ctxcat/issues"
+Changelog = "https://github.com/kamilkubik89/ctxcat/blob/main/CHANGELOG.md"
+
+[project.scripts]
+ctxcat = "ctxcat.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ctxcat"]

ctxcat-0.1.0/tests/test_ctxcat.py

@@ -0,0 +1,156 @@
+"""Tests for ctxcat. Run with: python -m pytest"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from ctxcat.cli import (  # noqa: E402
+    apply_budget, build_tree, collect, main, make_token_counter,
+    pick_fence, priority_of, PackResult, RepoFile,
+)
+
+
+@pytest.fixture
+def repo(tmp_path: Path) -> Path:
+    (tmp_path / "README.md").write_text("# Demo\nHello.")
+    (tmp_path / "src").mkdir()
+    (tmp_path / "src" / "main.py").write_text("print('hi')\n")
+    (tmp_path / "src" / "util.py").write_text("def f():\n    return 42\n")
+    (tmp_path / "tests").mkdir()
+    (tmp_path / "tests" / "test_main.py").write_text("def test():\n    pass\n")
+    (tmp_path / "node_modules").mkdir()
+    (tmp_path / "node_modules" / "junk.js").write_text("x" * 1000)
+    (tmp_path / "package-lock.json").write_text("{}")
+    (tmp_path / "logo.png").write_bytes(b"\x89PNG\r\n\x1a\n\x00\x00")
+    return tmp_path
+
+
+def _collect(root: Path, include=None, exclude=None, max_kb=256):
+    count, _ = make_token_counter()
+    return collect(root, include or [], exclude or [], max_kb, count)
+
+
+def test_collect_finds_text_files(repo):
+    result = _collect(repo)
+    rels = {f.rel for f in result.files}
+    assert "README.md" in rels
+    assert "src/main.py" in rels
+    assert "tests/test_main.py" in rels
+
+
+def test_collect_skips_junk(repo):
+    result = _collect(repo)
+    rels = {f.rel for f in result.files}
+    assert "node_modules/junk.js" not in rels
+    assert "package-lock.json" not in rels
+    assert "logo.png" not in rels
+
+
+def test_priority_ordering(repo):
+    result = _collect(repo)
+    # README (prio 0) must come before source (prio 2) before tests (prio 3)
+    order = [f.rel for f in result.files]
+    assert order.index("README.md") < order.index("src/main.py")
+    assert order.index("src/main.py") < order.index("tests/test_main.py")
+
+
+def test_include_filter(repo):
+    result = _collect(repo, include=["src/*"])
+    rels = {f.rel for f in result.files}
+    assert rels == {"src/main.py", "src/util.py"}
+
+
+def test_exclude_filter(repo):
+    result = _collect(repo, exclude=["tests/*"])
+    rels = {f.rel for f in result.files}
+    assert "tests/test_main.py" not in rels
+    assert "src/main.py" in rels
+
+
+def test_max_file_kb(repo):
+    (repo / "big.txt").write_text("x" * 500_000)
+    result = _collect(repo, max_kb=100)
+    assert "big.txt" not in {f.rel for f in result.files}
+
+
+def test_budget_trims_lowest_priority_first():
+    files = [
+        RepoFile(Path("a"), "README.md", "r" * 40, tokens=10, priority=0),
+        RepoFile(Path("b"), "src/main.py", "m" * 40, tokens=10, priority=2),
+        RepoFile(Path("c"), "tests/test_x.py", "t" * 40, tokens=10, priority=3),
+    ]
+    result = PackResult(files=list(files), total_tokens=30)
+    apply_budget(result, max_tokens=25, overhead=0)
+    kept = {f.rel for f in result.files}
+    assert "README.md" in kept
+    assert "tests/test_x.py" not in kept
+
+
+def test_tree_rendering():
+    tree = build_tree(["src/main.py", "src/util.py", "README.md"])
+    assert "src/" in tree
+    assert "main.py" in tree
+    assert "README.md" in tree
+
+
+def test_fence_escaping():
+    assert pick_fence("no backticks") == "```"
+    assert pick_fence("``` inside") == "````"
+    assert pick_fence("`````") == "``````"
+
+
+def test_priority_of():
+    assert priority_of("README.md") == 0
+    assert priority_of("pyproject.toml") == 1
+    assert priority_of("src/app.py") == 2
+    assert priority_of("tests/test_app.py") == 3
+
+
+def test_cli_end_to_end(repo, capsys):
+    rc = main([str(repo), "-q"])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "# Repository:" in out
+    assert "src/main.py" in out
+    assert "print('hi')" in out
+
+
+def test_cli_list_mode(repo, capsys):
+    rc = main([str(repo), "--list"])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "tokens" in out
+    assert "README.md" in out
+
+
+def test_cli_xml_format(repo, capsys):
+    rc = main([str(repo), "-f", "xml", "-q"])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "<repository" in out
+    assert '<file path="src/main.py">' in out
+
+
+def test_cli_output_file(repo, tmp_path):
+    dest = tmp_path / "out.md"
+    rc = main([str(repo), "-o", str(dest), "-q"])
+    assert rc == 0
+    assert dest.exists()
+    assert "src/main.py" in dest.read_text()
+
+
+def test_cli_bad_path(capsys):
+    rc = main(["/definitely/not/a/dir/xyz", "-q"])
+    assert rc == 2
+
+
+def test_git_repo_respects_gitignore(repo):
+    subprocess.run(["git", "init", "-q"], cwd=repo, check=True)
+    (repo / ".gitignore").write_text("secret.txt\n")
+    (repo / "secret.txt").write_text("password=hunter2")
+    result = _collect(repo)
+    assert "secret.txt" not in {f.rel for f in result.files}