repocxt 0.1.0__py3-none-any.whl

ctx/__init__.py

@@ -0,0 +1,8 @@
+"""ctx — package a repository into a single, LLM-ready context file.
+
+The public surface is the ``ctx`` console command, implemented in
+:mod:`ctx.cli`. Importing the package only exposes metadata.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

ctx/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m ctx``."""
+
+from ctx.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ctx/binary.py

@@ -0,0 +1,37 @@
+"""Heuristic detection of binary files.
+
+No file signature database: a file is treated as binary when its first chunk
+contains a NUL byte, which is reliable for the formats programmers actually
+commit (images, archives, compiled objects, fonts, audio). UTF-16 text and some
+encodings can contain NUL, but they are vanishingly rare in repository trees.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_SNIFF_BYTES = 8192
+_NUL = b"\x00"
+
+
+def is_nul_in_text(text: str) -> bool:
+    """True when decoded ``text`` still contains a NUL character.
+
+    ``is_binary`` sniffs only the first chunk, so a NUL past that window would
+    otherwise slip through; checking the decoded text is the definitive gate.
+    """
+    return _NUL.decode("ascii") in text
+
+
+def is_binary(path: Path) -> bool:
+    """Return True when ``path`` looks like a binary file.
+
+    Reads at most :data:`_SNIFF_BYTES` bytes. Files shorter than that are judged
+    on their whole content. A missing file answers False (the caller handles it).
+    """
+    try:
+        with path.open("rb") as handle:
+            chunk = handle.read(_SNIFF_BYTES)
+    except OSError:
+        return False
+    return _NUL in chunk

ctx/cli.py

@@ -0,0 +1,189 @@
+"""Command-line interface for ctx."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ctx import __version__
+from ctx.binary import is_nul_in_text
+from ctx.render import render_document
+from ctx.tokens import estimate_tokens
+from ctx.walker import discover
+
+# Fixed output we always emit per file section; used to make --max-tokens honest.
+_PER_FILE_OVERHEAD = 8  # "### `rel`", blank, fence ×2, blank — roughly
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ctx",
+        description=(
+            "Package a repository into a single, LLM-ready context file with "
+            "a tree, file contents, and a token estimate."
+        ),
+        epilog="Exit status: 0 on success, 1 when the root is missing or nothing is packed.",
+    )
+    parser.add_argument(
+        "root",
+        nargs="?",
+        default=".",
+        help="directory to pack (default: current directory)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="write to FILE instead of stdout",
+    )
+    parser.add_argument(
+        "--include",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="only include paths matching GLOB (repeatable; pathspec syntax)",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="exclude paths matching GLOB (repeatable; pathspec syntax)",
+    )
+    parser.add_argument(
+        "--max-size",
+        type=int,
+        metavar="BYTES",
+        help="skip files larger than this many bytes",
+    )
+    parser.add_argument(
+        "--max-tokens",
+        type=int,
+        metavar="N",
+        help="pack files until the estimated output reaches N tokens",
+    )
+    parser.add_argument(
+        "--no-tree",
+        action="store_true",
+        help="omit the ASCII tree section",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="print a JSON summary instead of the document",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"ctx {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    root = Path(args.root)
+    if not root.is_dir():
+        print(f"ctx: {args.root}: no such directory", file=sys.stderr)
+        return 1
+
+    exclude = list(args.exclude)
+    output_path: Path | None = None
+    if args.output and args.output != "-":
+        output_path = Path(args.output).resolve()
+        # Don't pack the file we are about to write (or one from a previous run).
+        try:
+            excluded_above = output_path.relative_to(root.resolve())
+            exclude.append(str(excluded_above))
+        except ValueError:
+            pass  # output lives outside the packed tree; nothing to do
+
+    files = discover(
+        root,
+        include=tuple(args.include),
+        exclude=tuple(exclude),
+        max_size=args.max_size,
+    )
+
+    if args.json:
+        picked = _trim_to_tokens(files, args.max_tokens) if args.max_tokens is not None else files
+        sys.stdout.write(_summary_json(root, picked) + "\n")
+        return 0
+
+    if args.max_tokens is not None:
+        files = _trim_to_tokens(files, args.max_tokens)
+    if not files:
+        print("ctx: nothing to pack", file=sys.stderr)
+        return 1
+
+    doc = render_document(root.name or "repo", files, include_tree=not args.no_tree)
+    return _emit(doc, output_path)
+
+
+def _emit(doc: str, output: Path | None) -> int:
+    if output is None:
+        sys.stdout.write(doc + "\n")
+        return 0
+    try:
+        output.write_text(doc, encoding="utf-8")
+    except OSError as exc:
+        print(f"ctx: cannot write {output}: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _trim_to_tokens(files, limit: int) -> list:
+    """Keep files while the estimated output stays under ``limit``.
+
+    The estimate covers the emitted text a file actually produces: its body
+    tokens plus the fixed per-section overhead (heading, blank lines, fences).
+    Binary files cost only the overhead and are always kept, so they stay
+    listed with their omission note. The first file always ships even if it
+    alone exceeds ``limit`` — packing nothing because one file is big helps
+    nobody.
+    """
+    kept: list = []
+    body_tokens = 0
+    for info in files:
+        cost = _PER_FILE_OVERHEAD
+        if not info.binary:
+            text = _read(info)
+            if not text:
+                continue
+            cost += estimate_tokens(text)
+        if body_tokens + cost > limit:
+            # Even the next file alone exceeds the remaining budget, so no
+            # further file can fit; what fits so far is kept (possibly nothing,
+            # when a single big file alone exceeds the whole limit).
+            break
+        kept.append(info)
+        body_tokens += cost
+    return kept
+
+
+def _summary_json(root: Path, files) -> str:
+    total_bytes = sum(f.size for f in files)
+    tokens = sum(_PER_FILE_OVERHEAD + estimate_tokens(_read(f)) for f in files if not f.binary)
+    payload = {
+        "root": str(root),
+        "files": [{"path": f.rel, "bytes": f.size, "binary": f.binary} for f in files],
+        "count": len(files),
+        "bytes": total_bytes,
+        "tokens": tokens,
+    }
+    return json.dumps(payload, indent=2)
+
+
+def _read(info) -> str:
+    try:
+        text = info.path.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, OSError):
+        return ""
+    return "" if is_nul_in_text(text) else text
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ctx/ignore.py

@@ -0,0 +1,74 @@
+"""Gitignore-aware path filtering built on ``pathspec``.
+
+A :class:`IgnoreMatcher` loads ``.gitignore`` (and optionally a private
+``.ctxignore``) files from the tree it is asked about, keyed by their directory,
+so nested files follow git's semantics: patterns are relative to the file that
+carries them, and a deeper file's decision wins over a shallower one's.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pathspec import PathSpec
+from pathspec.patterns.gitwildmatch import GitIgnoreSpecPattern
+
+
+class IgnoreMatcher:
+    """Matches repository paths against accumulated ignore rules."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = Path(root)
+        self._dirs: dict[str, PathSpec] = {}  # os-relpath -> lazily built spec
+
+    def _spec_for(self, rel_dir: str) -> PathSpec:
+        spec = self._dirs.get(rel_dir)
+        if spec is not None:
+            return spec
+        lines: list[str] = []
+        base = self.root if not rel_dir else self.root / rel_dir
+        for name in (".gitignore", ".ctxignore"):
+            candidate = base / name
+            if candidate.is_file():
+                _append_lines(candidate, lines)
+        spec = PathSpec.from_lines(GitIgnoreSpecPattern, lines)
+        self._dirs[rel_dir] = spec
+        return spec
+
+    def check(self, rel_path: str, is_dir: bool = False) -> bool:
+        """True when ``rel_path`` should be excluded from the context file.
+
+        Evaluates the rule files deepest-first: the decision of a ``.gitignore``
+        in the path's own directory (or its nearest ancestor) wins over a higher
+        one, mirroring git. Later lines within one file override earlier ones
+        (handled by pathspec).
+        """
+        dir_chain: list[str] = []
+        parent = rel_path.rsplit("/", 1)[0] if "/" in rel_path else ""
+        while True:
+            dir_chain.append(parent)
+            if not parent:
+                break
+            parent = parent.rsplit("/", 1)[0] if "/" in parent else ""
+
+        for rule_dir in dir_chain:  # deepest -> root
+            spec = self._spec_for(rule_dir)
+            candidate = rel_path[len(rule_dir) + 1 :] if rule_dir else rel_path
+            if is_dir and not candidate.endswith("/"):
+                candidate += "/"
+            result = spec.check_file(candidate)
+            if result.include is not None:
+                return result.include
+        return False
+
+
+def _append_lines(file: Path, lines: list[str]) -> None:
+    try:
+        text = file.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        lines.append(line)

ctx/language.py

@@ -0,0 +1,80 @@
+"""Map file extensions to fenced-code-block language hints.
+
+Everything falls back to ``None``, which produces an unlabelled fence. Only the
+extensions people hit often are listed; adding more is trivially safe.
+"""
+
+from __future__ import annotations
+
+_MAP = {
+    ".py": "python",
+    ".pyi": "python",
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".jsx": "jsx",
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".rs": "rust",
+    ".go": "go",
+    ".java": "java",
+    ".c": "c",
+    ".h": "c",
+    ".cpp": "cpp",
+    ".cc": "cpp",
+    ".hpp": "cpp",
+    ".cs": "csharp",
+    ".rb": "ruby",
+    ".php": "php",
+    ".swift": "swift",
+    ".kt": "kotlin",
+    ".scala": "scala",
+    ".sh": "bash",
+    ".bash": "bash",
+    ".zsh": "bash",
+    ".fish": "fish",
+    ".ps1": "powershell",
+    ".sql": "sql",
+    ".html": "html",
+    ".htm": "html",
+    ".css": "css",
+    ".scss": "scss",
+    ".less": "less",
+    ".json": "json",
+    ".jsonc": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".toml": "toml",
+    ".xml": "xml",
+    ".md": "markdown",
+    ".markdown": "markdown",
+    ".rst": "rst",
+    ".tex": "latex",
+    ".lua": "lua",
+    ".pl": "perl",
+    ".ex": "elixir",
+    ".erl": "erlang",
+    ".hs": "haskell",
+    ".ml": "ocaml",
+    ".clj": "clojure",
+    ".zig": "zig",
+    ".dart": "dart",
+    ".sol": "solidity",
+    ".dockerfile": "dockerfile",
+    ".docker": "dockerfile",
+    ".tf": "hcl",
+    ".hcl": "hcl",
+}
+
+
+def language_for(relative_path: str) -> str | None:
+    """Return a language hint for ``relative_path``, or None."""
+    for suffix, hint in _MAP.items():
+        if relative_path.lower().endswith(suffix):
+            return hint
+    lower = relative_path.lower()
+    if lower in {"makefile", "dockerfile"}:
+        return lower
+    if lower in {"gemfile", "rakefile"}:
+        return "ruby"
+    return None

ctx/render.py

@@ -0,0 +1,110 @@
+"""Render the tailored context file: an ASCII tree plus per-file sections."""
+
+from __future__ import annotations
+
+from ctx.binary import is_nul_in_text
+from ctx.language import language_for
+from ctx.tokens import estimate_tokens
+from ctx.walker import FileInfo
+
+_BOX = {"pipe": "│   ", "mid": "├── ", "last": "└── ", "pad": "    "}
+
+
+def build_tree(rels: list[str]) -> str:
+    """Return an ASCII directory tree for the given POSIX relative paths."""
+    root: dict = {}
+    for rel in rels:
+        node = root
+        for part in rel.split("/"):
+            node = node.setdefault(part, {})
+    lines: list[str] = []
+
+    def walk(node: dict, prefix: str) -> None:
+        # Directories (non-empty children dicts) first, then files, each
+        # case-insensitively.
+        items = sorted(node.items(), key=lambda kv: (not bool(kv[1]), kv[0].lower()))
+        for i, (name, child) in enumerate(items):
+            is_last = i == len(items) - 1
+            stem = prefix + (_BOX["last"] if is_last else _BOX["mid"]) + name
+            if child:
+                lines.append(stem + "/")
+                extension = _BOX["pad"] if is_last else _BOX["pipe"]
+                walk(child, prefix + extension)
+            else:
+                lines.append(stem)
+
+    walk(root, "")
+    return "\n".join(lines) or "."
+
+
+def _fence_for(body: str) -> str:
+    """A code fence delimiter that ``body``'s backtick runs cannot break.
+
+    Uses one backtick more than the longest run in the body (min 3, max 8 — a
+    run that long is beyond any reasonable source file, and capping avoids
+    pathological fence sizes). ``body`` may instead be omitted with a note.
+    """
+    longest = 0
+    run = 0
+    for char in body:
+        if char == "`":
+            run += 1
+            longest = max(longest, run)
+        else:
+            run = 0
+    return "`" * min(max(longest + 1, 3), 8)
+
+
+def render_document(
+    root_name: str,
+    files: list[FileInfo],
+    *,
+    include_tree: bool = True,
+) -> str:
+    """Build the whole markdown document as a string."""
+    total_bytes = sum(f.size for f in files)
+
+    # Read file bodies once, so binary/undecodable files are handled in a single
+    # pass and the token estimate matches exactly what gets emitted.
+    bodies: dict[str, str] = {}
+    skipped: dict[str, str] = {}
+    text_parts: list[str] = []
+    for info in files:
+        if info.binary:
+            skipped[info.rel] = "binary — content omitted"
+            continue
+        try:
+            text = info.path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            skipped[info.rel] = "binary — content omitted"
+            continue
+        if is_nul_in_text(text):
+            skipped[info.rel] = "binary — content omitted"
+            continue
+        bodies[info.rel] = text
+        text_parts.append(text)
+    token_estimate = estimate_tokens("\n".join(text_parts))
+
+    out: list[str] = [
+        f"# {root_name} — context",
+        "",
+        f"- files: **{len(files)}** · **{total_bytes} bytes** · ~**{token_estimate} tokens**",
+        "",
+    ]
+    if include_tree:
+        out += ["## Tree", "", "```text", build_tree([f.rel for f in files]), "```", ""]
+
+    out += ["## Files", ""]
+    for info in files:
+        out.append(f"### `{info.rel}`")
+        out.append("")
+        if info.rel in skipped:
+            out.append(f"> {skipped[info.rel]}")
+            out.append("")
+            continue
+        fence = _fence_for(bodies[info.rel])
+        out.append(f"{fence}{language_for(info.rel) or ''}")
+        out.append(bodies[info.rel].rstrip("\n"))
+        out.append(fence)
+        out.append("")
+    return "\n".join(out)

ctx/tokens.py

@@ -0,0 +1,29 @@
+"""Rough token estimation without any tokenizer dependency.
+
+``ctx`` aims to be dependency-light and offline. A real BPE tokenizer (tiktoken)
+is an extra dependency most users will not want, so this module approximates
+tokens from a mix of characters and whitespace-delimited words. It is calibrated
+toward English prose and code and overestimates by ~10-20% rather than
+underestimating, which is the safe direction for context budgeting.
+"""
+
+from __future__ import annotations
+
+import math
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate the number of tokens ``text`` contains.
+
+    Uses a blended heuristic: about one token per 4.0 characters, nudged upward
+    by whitespace-delimited words. The result is an integer >= 1.
+    """
+    if not text:
+        return 0
+    chars = len(text)
+    words = len(text.split())
+    # Code mixes in long identifiers and symbols; prose is denser per word. The
+    # 4.0 chars/token base handles long tokens, and 1.1 words/token proxy keeps
+    # short-word prose honest.
+    estimate = chars / 4.0 + words * 0.4
+    return max(1, math.ceil(estimate))

ctx/walker.py

@@ -0,0 +1,128 @@
+"""Repository file discovery: walk, filter, and produce FileInfo records."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from pathspec import PathSpec
+from pathspec.patterns.gitwildmatch import GitIgnoreSpecPattern
+
+from ctx.binary import is_binary
+from ctx.ignore import IgnoreMatcher
+
+# Always skipped, even with --no-ignore.
+_EXCLUDED_DIRS = {
+    ".git",
+    ".svn",
+    ".hg",
+    ".ctx",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    "__pycache__",
+}
+
+
+@dataclass(frozen=True)
+class FileInfo:
+    """One file that made it into the context file."""
+
+    rel: str  # POSIX-ish path relative to the repo root
+    path: Path  # absolute path on disk
+    size: int  # bytes
+    binary: bool  # detected as binary (content excluded from output)
+
+
+def discover(
+    root: Path,
+    *,
+    include: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+    max_size: int | None = None,
+    skip_binary: bool = True,
+) -> list[FileInfo]:
+    """Walk ``root`` and return the files that belong in the context file.
+
+    Honors ``.gitignore`` everywhere in the tree. ``include`` and ``exclude``
+    are pathspec-style patterns applied to POSIX relative paths after ignore
+    filtering; ``exclude`` wins over ``include``. Files larger than ``max_size``
+    bytes are dropped. ``skip_binary`` keeps binary files in the list (so the
+    reader knows they were omitted); when false, binary content is read anyway.
+    """
+    root = Path(root).resolve()
+    ignore = IgnoreMatcher(root)
+    include_spec = PathSpec.from_lines(GitIgnoreSpecPattern, include) if include else None
+    exclude_spec = PathSpec.from_lines(GitIgnoreSpecPattern, exclude) if exclude else None
+
+    files: list[FileInfo] = []
+    for dirpath, dirnames, filenames in _walk(root, ignore):
+        # Prune ignored directories in place so we never descend into them.
+        kept: list[str] = []
+        for name in dirnames:
+            rel = _rel(root, dirpath, name)
+            if name in _EXCLUDED_DIRS or ignore.check(rel, is_dir=True):
+                continue
+            kept.append(name)
+        dirnames[:] = kept
+
+        for name in filenames:
+            abs_path = Path(dirpath) / name
+            rel = _rel(root, dirpath, name)
+            if _blocked(rel, include_spec, exclude_spec):
+                continue
+            if ignore.check(rel, is_dir=False):
+                continue
+            try:
+                size = abs_path.stat().st_size
+            except OSError:
+                continue
+            if max_size is not None and size > max_size:
+                continue
+            binary = is_binary(abs_path) if skip_binary else False
+            files.append(FileInfo(rel=rel, path=abs_path, size=size, binary=binary))
+
+    files.sort(key=lambda f: (f.rel.lower(), f.rel))
+    return files
+
+
+def _walk(root: Path, ignore: IgnoreMatcher):
+    """os.walk-compatible generator; ``ignore`` is consulted by ``discover``."""
+    stack = [str(root)]
+    while stack:
+        dirpath = stack.pop()
+        try:
+            with os.scandir(dirpath) as it:
+                names = sorted((e.name for e in it), key=str.lower)
+        except OSError:
+            continue
+        dirnames: list[str] = []
+        filenames: list[str] = []
+        for name in names:
+            child = os.path.join(dirpath, name)
+            try:
+                if os.path.isdir(child) and not os.path.islink(child):
+                    dirnames.append(name)
+                elif os.path.isfile(child):
+                    filenames.append(name)
+            except OSError:
+                continue
+        yield dirpath, dirnames, filenames
+        for name in reversed(dirnames):
+            stack.append(os.path.join(dirpath, name))
+
+
+def _rel(root: Path, dirpath: str, name: str) -> str:
+    if dirpath == str(root):
+        return name
+    relative = str(Path(dirpath).relative_to(root))
+    if os.sep == "\\":  # Windows paths are backslash-separated; normalise to /
+        relative = relative.replace("\\", "/")
+    return relative + "/" + name
+
+
+def _blocked(rel: str, include: PathSpec | None, exclude: PathSpec | None) -> bool:
+    if exclude is not None and exclude.match_file(rel):
+        return True
+    return include is not None and not include.match_file(rel)

repocxt-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: repocxt
+Version: 0.1.0
+Summary: Package a repository into a single, LLM-ready context file with a tree, file contents, and a token estimate.
+Author: Kamran
+License-Expression: MIT
+Keywords: llm,context,cli,code,ai,prompt
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pathspec>=1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build>=1.0; extra == "build"
+Requires-Dist: twine>=4.0; extra == "build"
+Dynamic: license-file
+
+# ctx
+
+Package a repository into a single, LLM-ready context file.
+
+`ctx` walks a directory and emits one markdown file containing an ASCII tree of
+the repo, the contents of every source file (fenced with language hints), and a
+token estimate — so you can paste a whole repository into an LLM prompt, or
+point an agent at it, and the model sees structure and code together.
+
+## What it looks like
+
+Running `ctx` on this repo (tree trimmed for the README; the header counts are real):
+
+````text
+# repo — context
+
+- files: **26** · **67763 bytes** · ~**19876 tokens**
+
+## Tree
+
+```text
+├── .github/
+│   ├── workflows/
+│   │   ├── ci.yml
+│   │   └── release.yml
+│   └── FUNDING.yml
+├── src/
+│   └── ctx/
+│       ├── __init__.py
+│       ├── __main__.py
+│       ├── ...
+│       └── walker.py
+├── tests/
+│   ├── conftest.py
+│   ├── test_cli.py
+│   ├── test_ignore.py
+│   ├── test_render.py
+│   ├── test_tokens.py
+│   └── test_walker.py
+├── .gitignore
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── MANIFEST.in
+├── pyproject.toml
+└── README.md
+```
+````
+
+## Features
+
+- **One file out.** Directory tree, file contents, and a token estimate in a
+  single markdown document — ready to paste into a prompt.
+- **Gitignore-aware.** Follows `.gitignore` (and `.ctxignore`) at every level
+  of the tree, with git's semantics: deeper rule files win.
+- **Binary-safe.** Binary files are detected and listed, but their content is
+  omitted instead of corrupting the document.
+- **Token-aware.** `--max-tokens` stops early once the running estimate crosses
+  the limit, so the output fits your context window.
+- **Filterable.** `--include` / `--exclude` with repeatable pathspec globs, and
+  `--max-size` to skip files that are too big.
+- **Offline and light.** The only runtime dependency is `pathspec`.
+
+## Install
+
+Requires Python 3.10+. The package is published on PyPI as `repocxt`; the
+command you run is `ctx`.
+
+```bash
+pipx install repocxt
+```
+
+Or install from a checkout directly:
+
+```bash
+pipx install .
+```
+
+Or with plain pip:
+
+```bash
+pip install repocxt
+```
+
+However you install it, you get a `ctx` command (it also runs as
+`python -m ctx`).
+
+## Usage
+
+```text
+usage: ctx [-h] [-o FILE] [--include GLOB] [--exclude GLOB] [--max-size BYTES]
+           [--max-tokens N] [--no-tree] [--json] [--version]
+           [root]
+```
+
+- `root` — directory to pack. Defaults to the current directory. The header
+  uses the directory's name (or `repo` when the name is empty, e.g. `.`).
+- `-o FILE, --output FILE` — write to a file instead of stdout. `-o -` means
+  stdout explicitly.
+- `--include GLOB` / `--exclude GLOB` — keep or drop paths matching a glob
+  (repeatable; pathspec syntax). Both are applied after ignore filtering, and
+  `--exclude` wins over `--include`.
+- `--max-size BYTES` — skip files larger than this many bytes.
+- `--max-tokens N` — stop once the emitted text reaches N tokens.
+- `--no-tree` — omit the ASCII tree section; just the files.
+- `--json` — print a machine-readable summary (file list, counts, bytes,
+  tokens) instead of the document.
+
+### With LLMs
+
+The output is self-contained, so driving an LLM is two steps:
+
+```bash
+# write it to a file for an agent that can read files
+ctx -o ctx.md
+
+# or just paste stdout straight into the prompt
+ctx | head -c 20000
+```
+
+Point the model at `ctx.md` ("this is my whole repo, read it") or paste it
+directly — the tree tells it the layout, the fenced blocks give it the code,
+and the token estimate tells you whether it fits.
+
+## How it decides what to include
+
+- **Gitignore semantics.** `.gitignore` files are read at every directory and
+  applied to relative paths; a deeper `.gitignore`'s decision wins over a
+  shallower one's, and later lines override earlier ones. A private
+  `.ctxignore` file is honored the same way, for rules you do not want to
+  commit to git.
+- **Always-skipped directories.** `.git`, `.svn`, `.hg`, `.ctx`,
+  `__pycache__`, and `.mypy_cache` are always skipped.
+- **Binary omission.** A file is treated as binary when its first 8 KB contain
+  a NUL byte — images, archives, compiled objects. It is still listed in the
+  document, but with a note instead of content.
+- **Files, not directories.** Only regular files are packed; empty directories
+  and directory symlinks do not appear in the tree.
+
+## Philosophy
+
+Offline-first. There is no telemetry, no network call, and no tokenizer — token
+counts come from a small local heuristic that errs high, which is the safe
+direction for context budgeting. The dependency list stays minimal
+(`pathspec` is the only runtime dependency) and the output is plain markdown
+you can read, diff, and paste anywhere.
+
+## Development
+
+```bash
+git clone <your fork>/ctx
+cd ctx
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+- Run tests: `python -m pytest`
+- Lint: `python -m ruff check .` (config and dev extras live in `pyproject.toml`)
+
+No need to install to poke at the CLI:
+
+```bash
+export PYTHONPATH="$PWD/src"
+python3 -m ctx --help
+```
+
+## Testing & compatibility
+
+Honest status of what is and isn't verified:
+
+- **Tested on:** Linux, Python 3.12 — 106 automated tests pass (`pytest`),
+  `ruff` clean, wheel + sdist build clean, `twine check` passes. Edge cases
+  covered by tests: nested/overriding `.gitignore`, negation, directory-only
+  patterns, filenames with spaces, undecodable and binary files, oversized
+  files, symlinks (not followed for dirs), backtick-fences inside file bodies,
+  and `--max-tokens` / `--json` behavior.
+- **Expected but not yet verified:** macOS and Windows, and Python 3.10–3.11.
+  The code is pure Python + `pathspec` with no OS-specific calls, so it
+  *should* run anywhere, but only Linux/3.12 has been exercised. The GitHub
+  Actions matrix (`ci.yml`) runs 3.10–3.12 on Linux for every push; wider
+  platform testing is welcome via PRs / CI runs.
+- **Not verified at all:** any real PyPI publication (needs a maintainer token).
+
+If you hit a platform you use that isn't green, open an issue with your OS,
+Python version, and the error — that's the fastest way this list gets shorter.
+
+## License
+
+[MIT](LICENSE) © 2026 Kamran

repocxt-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ctx/__init__.py,sha256=SMu8zJGEznfocmgMKukOqgwp-zMl4rvvPxyDmLQB_sw,252
+ctx/__main__.py,sha256=PiakOg9Rd2nCV9Dk4hZolSr2kIpVPytnBSp58wo8y1M,114
+ctx/binary.py,sha256=Ndn0X6notMTJqgqsOsCevXnIy6JxOB9pBAktSLp8FS0,1196
+ctx/cli.py,sha256=C2LmGUQB4eXpFvxXXMx9G-gqxeHpKOEmMx4-Qp17ut8,5739
+ctx/ignore.py,sha256=RHR9tAiqBbkIPHRjYC7kvu_SNCA3iiW41WhM4AAZMwI,2766
+ctx/language.py,sha256=kIbS2u6HuhanNDCL7fMCIm2ZbOZS8fvGCU4fgiDQ30Q,1879
+ctx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ctx/render.py,sha256=HFZGuXW5EmIi5dQ5E8M3JisrVG9bl8jgCnf8yhCruII,3700
+ctx/tokens.py,sha256=TdaU8vUy25jlBgS0IKsGclycpkEjZcOsI_fP_c5jO3k,1101
+ctx/walker.py,sha256=ISJ7p-iug3LwTfD22-bzHjUrO0X0bL4LIoTZHOfq9OA,4329
+repocxt-0.1.0.dist-info/licenses/LICENSE,sha256=oLP7UmahGD7LTGOVoAYeTTCayBzf3h9LVQZdWwfGF8g,1063
+repocxt-0.1.0.dist-info/METADATA,sha256=uvaIgOOa90vo6iPUP5rL60t_mEtIN-aFsCNlfaDrKyQ,7439
+repocxt-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+repocxt-0.1.0.dist-info/entry_points.txt,sha256=qw347dSB47D2ytO2k5c-BWRiHWoT7kUvoOIWUnwAMOQ,37
+repocxt-0.1.0.dist-info/top_level.txt,sha256=4GAlu6d1lfmUOY-dagUnOBgM1aKhmsrctDhmv-jn-TY,4
+repocxt-0.1.0.dist-info/RECORD,,

repocxt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

repocxt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ctx = ctx.cli:main

repocxt-0.1.0.dist-info/licenses/LICENSE

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

repocxt-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ctx