ctxcode 0.2.0__tar.gz

ctxcode-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+*.egg-info/
+dist/
+build/
+__pycache__/
+*.pyc
+.venv/
+venv/

ctxcode-0.2.0/LICENSE

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

ctxcode-0.2.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: ctxcode
+Version: 0.2.0
+Summary: Extract your codebase context for AI assistants
+Project-URL: Homepage, https://github.com/hanu-14/codecontext
+Project-URL: Repository, https://github.com/hanu-14/codecontext
+Project-URL: Issues, https://github.com/hanu-14/codecontext/issues
+Author-email: Mohammed Hanan <hananmtp313@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,cli,code-review,developer-tools,productivity
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# codecontext
+
+<p align="center">
+  <b>Extract your codebase context for AI assistants.</b><br>
+  <a href="https://github.com/hanu-14/codecontext/actions/workflows/ci.yml">
+    <img src="https://github.com/hanu-14/codecontext/actions/workflows/ci.yml/badge.svg" alt="CI">
+  </a>
+  <img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero dependencies">
+  <img src="https://img.shields.io/badge/version-0.2.0-blue" alt="v0.2.0">
+</p>
+
+A zero-dependency CLI tool that packages your project structure, key files, and git history into a formatted prompt for Claude, ChatGPT, and other AI coding assistants.
+
+```bash
+pip install ctxcode
+cd my-project
+codecontext
+```
+
+## Why?
+
+When asking AI assistants about your code, you spend minutes copy-pasting file trees, key files, and git history. `codecontext` does it in one command — giving the AI full project context for better answers.
+
+## Install
+
+```bash
+pip install codecontext
+```
+
+Or run directly:
+
+```bash
+curl -O https://raw.githubusercontent.com/hanu-14/codecontext/main/src/codecontext/cli.py
+python cli.py
+```
+
+## Usage
+
+```bash
+# Full context (tree + files + git history)
+codecontext
+
+# Specific project
+codecontext path/to/project
+
+# Output formats
+codecontext --format markdown    # default - ready for AI chat
+codecontext --format plain       # plain text
+codecontext --format json        # machine-readable
+
+# Copy to clipboard
+codecontext --clipboard
+
+# Save to file
+codecontext -o context.md
+
+# Exclude custom patterns
+codecontext --exclude "*.log" "tmp/" "*.csv"
+
+# Show hidden files
+codecontext --hidden
+
+# Exclude git info
+codecontext --no-git
+
+# Adjust limits
+codecontext --max-files 100 --max-lines 150
+```
+
+### Short alias
+
+```bash
+ctx                # same as codecontext
+ctx ./src          # specific directory
+ctx --clipboard    # copy to clipboard
+```
+
+## Configuration
+
+Place a `.codecontext.toml` in your project root:
+
+```toml
+git = true
+max_files = 300
+max_lines = 250
+format = "markdown"
+exclude = ["*.log", "tmp/"]
+hidden = false
+```
+
+JSON and YAML formats are also supported (`.codecontext.json`, `.codecontext.yml`).
+
+## Output
+
+The tool produces a structured document with:
+
+1. **Project metadata** — path, git remote, branch
+2. **Git history** — recent commits and uncommitted changes
+3. **File tree** — with file sizes for every entry
+4. **Key files** — source files with syntax highlighting
+5. **Stats summary** — total files and size at a glance
+
+Perfect for pasting directly into Claude, ChatGPT, or any AI coding assistant.
+
+## Features
+
+- **Zero dependencies** — pure Python, no pip installs beyond this package
+- **Smart ignore** — automatically skips `.git`, `node_modules`, `__pycache__`, binaries, and more
+- **Git aware** — includes branch, remote, recent commits, and diff stats
+- **File limit safety** — won't overwhelm your context window
+- **Language detection** — syntax-highlighted code blocks for 30+ languages
+- **Clipboard support** — `--clipboard` copies output directly to your clipboard
+- **Multiple formats** — markdown, plain text, or JSON
+- **Config file** — project-specific settings via `.codecontext.toml`
+- **Custom excludes** — ignore additional patterns with `--exclude`
+- **File sizes** — every file in the tree shows its size
+
+## Example
+
+```bash
+$ codecontext --format markdown
+```
+
+Produces:
+
+```
+# Codebase Context
+
+Generated from: /Users/me/my-project
+Remote: git@github.com:user/my-project.git
+Branch: main
+
+Recent commits:
+abc1234 feat: add user authentication
+def5678 fix: resolve payment timeout
+
+## Project Structure
+
+my-project/
+├── src/
+│   ├── main.py (2KB)
+│   └── utils.py (1KB)
+├── tests/
+│   └── test_main.py (3KB)
+├── pyproject.toml (1KB)
+└── README.md (3KB)
+
+## Key Files (6 files, 10KB)
+
+### `src/main.py`
+
+```python
+def greet(name):
+    return f"Hello, {name}!"
+```
+
+...
+```
+
+## Changelog
+
+### v0.2.0
+- Clipboard support (`--clipboard`)
+- Multiple output formats: markdown, plain, JSON
+- Configuration file support (`.codecontext.toml`, `.json`, `.yml`)
+- File sizes in tree output
+- Custom exclude patterns (`--exclude`)
+- Hidden files flag (`--hidden`)
+- Stats summary in output
+
+### v0.1.0
+- Initial release
+- File tree with smart ignore patterns
+- Git history integration
+- Syntax highlighting for 30+ languages
+- CLI alias `ctx`
+
+## License
+
+MIT

ctxcode-0.2.0/README.md

@@ -0,0 +1,182 @@
+# codecontext
+
+<p align="center">
+  <b>Extract your codebase context for AI assistants.</b><br>
+  <a href="https://github.com/hanu-14/codecontext/actions/workflows/ci.yml">
+    <img src="https://github.com/hanu-14/codecontext/actions/workflows/ci.yml/badge.svg" alt="CI">
+  </a>
+  <img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero dependencies">
+  <img src="https://img.shields.io/badge/version-0.2.0-blue" alt="v0.2.0">
+</p>
+
+A zero-dependency CLI tool that packages your project structure, key files, and git history into a formatted prompt for Claude, ChatGPT, and other AI coding assistants.
+
+```bash
+pip install ctxcode
+cd my-project
+codecontext
+```
+
+## Why?
+
+When asking AI assistants about your code, you spend minutes copy-pasting file trees, key files, and git history. `codecontext` does it in one command — giving the AI full project context for better answers.
+
+## Install
+
+```bash
+pip install codecontext
+```
+
+Or run directly:
+
+```bash
+curl -O https://raw.githubusercontent.com/hanu-14/codecontext/main/src/codecontext/cli.py
+python cli.py
+```
+
+## Usage
+
+```bash
+# Full context (tree + files + git history)
+codecontext
+
+# Specific project
+codecontext path/to/project
+
+# Output formats
+codecontext --format markdown    # default - ready for AI chat
+codecontext --format plain       # plain text
+codecontext --format json        # machine-readable
+
+# Copy to clipboard
+codecontext --clipboard
+
+# Save to file
+codecontext -o context.md
+
+# Exclude custom patterns
+codecontext --exclude "*.log" "tmp/" "*.csv"
+
+# Show hidden files
+codecontext --hidden
+
+# Exclude git info
+codecontext --no-git
+
+# Adjust limits
+codecontext --max-files 100 --max-lines 150
+```
+
+### Short alias
+
+```bash
+ctx                # same as codecontext
+ctx ./src          # specific directory
+ctx --clipboard    # copy to clipboard
+```
+
+## Configuration
+
+Place a `.codecontext.toml` in your project root:
+
+```toml
+git = true
+max_files = 300
+max_lines = 250
+format = "markdown"
+exclude = ["*.log", "tmp/"]
+hidden = false
+```
+
+JSON and YAML formats are also supported (`.codecontext.json`, `.codecontext.yml`).
+
+## Output
+
+The tool produces a structured document with:
+
+1. **Project metadata** — path, git remote, branch
+2. **Git history** — recent commits and uncommitted changes
+3. **File tree** — with file sizes for every entry
+4. **Key files** — source files with syntax highlighting
+5. **Stats summary** — total files and size at a glance
+
+Perfect for pasting directly into Claude, ChatGPT, or any AI coding assistant.
+
+## Features
+
+- **Zero dependencies** — pure Python, no pip installs beyond this package
+- **Smart ignore** — automatically skips `.git`, `node_modules`, `__pycache__`, binaries, and more
+- **Git aware** — includes branch, remote, recent commits, and diff stats
+- **File limit safety** — won't overwhelm your context window
+- **Language detection** — syntax-highlighted code blocks for 30+ languages
+- **Clipboard support** — `--clipboard` copies output directly to your clipboard
+- **Multiple formats** — markdown, plain text, or JSON
+- **Config file** — project-specific settings via `.codecontext.toml`
+- **Custom excludes** — ignore additional patterns with `--exclude`
+- **File sizes** — every file in the tree shows its size
+
+## Example
+
+```bash
+$ codecontext --format markdown
+```
+
+Produces:
+
+```
+# Codebase Context
+
+Generated from: /Users/me/my-project
+Remote: git@github.com:user/my-project.git
+Branch: main
+
+Recent commits:
+abc1234 feat: add user authentication
+def5678 fix: resolve payment timeout
+
+## Project Structure
+
+my-project/
+├── src/
+│   ├── main.py (2KB)
+│   └── utils.py (1KB)
+├── tests/
+│   └── test_main.py (3KB)
+├── pyproject.toml (1KB)
+└── README.md (3KB)
+
+## Key Files (6 files, 10KB)
+
+### `src/main.py`
+
+```python
+def greet(name):
+    return f"Hello, {name}!"
+```
+
+...
+```
+
+## Changelog
+
+### v0.2.0
+- Clipboard support (`--clipboard`)
+- Multiple output formats: markdown, plain, JSON
+- Configuration file support (`.codecontext.toml`, `.json`, `.yml`)
+- File sizes in tree output
+- Custom exclude patterns (`--exclude`)
+- Hidden files flag (`--hidden`)
+- Stats summary in output
+
+### v0.1.0
+- Initial release
+- File tree with smart ignore patterns
+- Git history integration
+- Syntax highlighting for 30+ languages
+- CLI alias `ctx`
+
+## License
+
+MIT

ctxcode-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ctxcode"
+version = "0.2.0"
+description = "Extract your codebase context for AI assistants"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Mohammed Hanan", email = "hananmtp313@gmail.com"},
+]
+keywords = ["cli", "ai", "code-review", "productivity", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Code Generators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/hanu-14/codecontext"
+Repository = "https://github.com/hanu-14/codecontext"
+Issues = "https://github.com/hanu-14/codecontext/issues"
+
+[project.scripts]
+codecontext = "codecontext.cli:main"
+ctx = "codecontext.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codecontext"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src"]

ctxcode-0.2.0/src/codecontext/cli.py

@@ -0,0 +1,249 @@
+import json
+import os
+import shutil
+import sys
+import textwrap
+
+from . import scanner
+from . import git_utils
+
+
+LANG_MAP = {
+    ".py": "python", ".js": "javascript", ".ts": "typescript",
+    ".tsx": "tsx", ".jsx": "jsx", ".rs": "rust", ".go": "go",
+    ".java": "java", ".c": "c", ".cpp": "cpp", ".h": "c",
+    ".hpp": "cpp", ".rb": "ruby", ".php": "php", ".swift": "swift",
+    ".kt": "kotlin", ".scala": "scala", ".r": "r",
+    ".yaml": "yaml", ".yml": "yaml", ".json": "json",
+    ".toml": "toml", ".xml": "xml", ".md": "markdown",
+    ".html": "html", ".css": "css", ".scss": "scss",
+    ".sql": "sql", ".sh": "bash", ".bash": "bash",
+    ".zsh": "bash", ".dockerfile": "dockerfile",
+    ".txt": "text", ".cfg": "ini", ".ini": "ini",
+}
+
+
+def build_stats(root, key_files):
+    total_files = len(key_files)
+    total_size = 0
+    for _, abs_path in key_files:
+        try:
+            total_size += os.path.getsize(abs_path)
+        except OSError:
+            pass
+    return {"files": total_files, "size": total_size, "dir": root}
+
+
+def format_markdown(root, include_git, max_files, max_lines, extra_ignore, show_hidden):
+    blocks = []
+
+    blocks.append("# Codebase Context\n")
+    blocks.append(f"Generated from: `{os.path.abspath(root)}`\n")
+
+    if include_git:
+        info = git_utils.get_git_info(root)
+        if info.get("remote"):
+            blocks.append(f"Remote: `{info['remote']}`")
+        if info.get("branch"):
+            blocks.append(f"Branch: `{info['branch']}`")
+        if info.get("uncommitted"):
+            blocks.append(f"\nUncommitted changes:\n```\n{info['uncommitted']}\n```")
+        if info.get("recent_commits"):
+            blocks.append(f"\nRecent commits:\n```\n{info['recent_commits']}\n```")
+
+    tree = scanner.get_tree(root, max_files=max_files, extra_ignore=extra_ignore, show_hidden=show_hidden)
+    blocks.append(f"\n## Project Structure\n\n```\n{tree}\n```\n")
+
+    key_files = scanner.find_key_files(root, extra_ignore=extra_ignore)
+    stats = build_stats(root, key_files)
+
+    blocks.append(f"\n## Key Files ({stats['files']} files, {stats['size'] / 1024:.0f}KB)\n")
+
+    for rel_path, abs_path in key_files:
+        ext = os.path.splitext(rel_path)[1].lower()
+        lang = LANG_MAP.get(ext, "")
+        content = scanner.read_file(abs_path, max_lines=max_lines)
+        blocks.append(f"\n### `{rel_path}`\n\n```{lang}\n{content}```")
+
+    blocks.append("\n---\n*Generated by [codecontext](https://github.com/hanu-14/codecontext)*")
+    return "\n".join(blocks)
+
+
+def format_plain(root, include_git, max_files, max_lines, extra_ignore, show_hidden):
+    lines = []
+
+    lines.append(f"Project: {os.path.abspath(root)}\n")
+
+    if include_git:
+        info = git_utils.get_git_info(root)
+        if info.get("remote"):
+            lines.append(f"Remote: {info['remote']}")
+        if info.get("branch"):
+            lines.append(f"Branch: {info['branch']}")
+        if info.get("uncommitted"):
+            lines.append(f"\nUncommitted:\n{info['uncommitted']}")
+
+    lines.append(f"\nProject Structure:\n{scanner.get_tree(root, max_files=max_files, extra_ignore=extra_ignore, show_hidden=show_hidden)}\n")
+
+    key_files = scanner.find_key_files(root, extra_ignore=extra_ignore)
+    for rel_path, abs_path in key_files:
+        content = scanner.read_file(abs_path, max_lines=max_lines)
+        sep = "=" * 60
+        lines.append(f"\n{sep}\nFile: {rel_path}\n{sep}\n{content}")
+
+    return "\n".join(lines)
+
+
+def format_json(root, include_git, max_files, max_lines, extra_ignore, show_hidden):
+    info = {}
+    info["root"] = os.path.abspath(root)
+
+    if include_git:
+        info["git"] = git_utils.get_git_info(root)
+
+    info["tree"] = scanner.get_tree(root, max_files=max_files, extra_ignore=extra_ignore, show_hidden=show_hidden)
+
+    key_files = scanner.find_key_files(root, extra_ignore=extra_ignore)
+    info["files"] = []
+    for rel_path, abs_path in key_files:
+        info["files"].append({
+            "path": rel_path,
+            "content": scanner.read_file(abs_path, max_lines=max_lines),
+        })
+
+    info["stats"] = build_stats(root, key_files)
+    return json.dumps(info, indent=2)
+
+
+FORMATTERS = {
+    "markdown": format_markdown,
+    "plain": format_plain,
+    "json": format_json,
+}
+
+
+def merge_config_with_args(config, args):
+    if args.no_git is None and "git" in config:
+        args.no_git = not config["git"]
+    if args.max_files is None and "max_files" in config:
+        args.max_files = config["max_files"]
+    if args.max_lines is None and "max_lines" in config:
+        args.max_lines = config["max_lines"]
+    if args.format is None and "format" in config:
+        args.format = config["format"]
+    if args.exclude is None and "exclude" in config:
+        args.exclude = config["exclude"]
+    if args.output is None and "output" in config:
+        args.output = config["output"]
+    if args.hidden is None and "hidden" in config:
+        args.hidden = config["hidden"]
+    return args
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(
+        description="Extract codebase context for AI assistants.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent("""
+            Examples:
+              codecontext                          # full context (markdown)
+              codecontext --format json             # JSON output
+              codecontext --clipboard               # copy to clipboard
+              codecontext --exclude "*.log" "tmp/"  # custom excludes
+              codecontext --hidden                  # include dotfiles
+              codecontext -o context.txt --format plain  # plain text file
+        """),
+    )
+    parser.add_argument(
+        "path", nargs="?", default=None,
+        help="Project path (default: current directory)"
+    )
+    parser.add_argument(
+        "--no-git", action="store_true", default=None,
+        help="Skip git information"
+    )
+    parser.add_argument(
+        "--max-files", type=int, default=None,
+        help="Maximum files to show in tree (default: 200)"
+    )
+    parser.add_argument(
+        "--max-lines", type=int, default=None,
+        help="Maximum lines per file (default: 200)"
+    )
+    parser.add_argument(
+        "--format", "-f", default=None, choices=["markdown", "plain", "json"],
+        help="Output format (default: markdown)"
+    )
+    parser.add_argument(
+        "--clipboard", "-c", action="store_true",
+        help="Copy output to clipboard"
+    )
+    parser.add_argument(
+        "--output", "-o", default=None,
+        help="Write output to file"
+    )
+    parser.add_argument(
+        "--exclude", nargs="*", default=None,
+        help="Additional exclude patterns (glob)"
+    )
+    parser.add_argument(
+        "--hidden", action="store_true", default=None,
+        help="Show hidden files"
+    )
+    parser.add_argument(
+        "--quiet", "-q", action="store_true",
+        help="Suppress stderr messages"
+    )
+
+    args = parser.parse_args()
+
+    search_root = os.path.abspath(args.path or ".")
+    config = scanner.load_config(search_root)
+    args = merge_config_with_args(config, args)
+
+    if args.path is None:
+        args.path = "."
+
+    root = os.path.abspath(args.path)
+    if not os.path.isdir(root):
+        print(f"error: {root} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    fmt = args.format or "markdown"
+    formatter = FORMATTERS.get(fmt, FORMATTERS["markdown"])
+
+    extra_ignore = args.exclude or []
+    context = formatter(
+        root,
+        include_git=not args.no_git if args.no_git is not None else True,
+        max_files=args.max_files or 200,
+        max_lines=args.max_lines or 200,
+        extra_ignore=extra_ignore,
+        show_hidden=args.hidden or False,
+    )
+
+    if args.clipboard:
+        try:
+            shutil.copy(context, None)
+        except Exception:
+            import subprocess
+            try:
+                proc = subprocess.Popen(["clip"], stdin=subprocess.PIPE, shell=True)
+                proc.communicate(input=context.encode("utf-8"))
+                if not args.quiet:
+                    print("Copied to clipboard!", file=sys.stderr)
+            except Exception as e:
+                print(f"Clipboard error: {e}", file=sys.stderr)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(context)
+        if not args.quiet:
+            print(f"Written to {args.output}", file=sys.stderr)
+    else:
+        print(context)
+
+
+if __name__ == "__main__":
+    main()

ctxcode-0.2.0/src/codecontext/git_utils.py

@@ -0,0 +1,47 @@
+import subprocess
+import os
+
+
+def get_git_info(root):
+    info = {}
+    try:
+        result = subprocess.run(
+            ["git", "log", "--oneline", "-20"],
+            capture_output=True, text=True, cwd=root, timeout=10
+        )
+        if result.returncode == 0:
+            info["recent_commits"] = result.stdout.strip()
+    except Exception:
+        info["recent_commits"] = ""
+
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True, text=True, cwd=root, timeout=5
+        )
+        if result.returncode == 0:
+            info["remote"] = result.stdout.strip()
+    except Exception:
+        info["remote"] = ""
+
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            capture_output=True, text=True, cwd=root, timeout=5
+        )
+        if result.returncode == 0:
+            info["branch"] = result.stdout.strip()
+    except Exception:
+        info["branch"] = ""
+
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--stat"],
+            capture_output=True, text=True, cwd=root, timeout=5
+        )
+        if result.returncode == 0:
+            info["uncommitted"] = result.stdout.strip()
+    except Exception:
+        info["uncommitted"] = ""
+
+    return info

ctxcode-0.2.0/src/codecontext/scanner.py

@@ -0,0 +1,156 @@
+import os
+import fnmatch
+
+
+IGNORE_PATTERNS = {
+    ".git", "__pycache__", "node_modules", ".venv", "venv", "env",
+    ".tox", ".eggs", "*.egg-info", "dist", "build", ".next",
+    ".nuxt", "target", "bin", "obj", ".idea", ".vscode",
+    "*.pyc", "*.pyo", "*.so", "*.dll", "*.dylib",
+    "*.png", "*.jpg", "*.jpeg", "*.gif", "*.svg", "*.ico",
+    "*.ttf", "*.woff", "*.woff2", "*.eot",
+    "*.zip", "*.tar", "*.gz", "*.7z", "*.rar",
+    ".DS_Store", "Thumbs.db", "*.lock", "package-lock.json",
+    "*.min.js", "*.min.css", "*.map",
+    ".coverage", ".pytest_cache", ".mypy_cache", ".ruff_cache",
+}
+
+BINARY_EXTENSIONS = {
+    ".png", ".jpg", ".jpeg", ".gif", ".ico", ".svg",
+    ".ttf", ".woff", ".woff2", ".eot",
+    ".zip", ".tar", ".gz", ".7z", ".rar",
+    ".so", ".dll", ".dylib", ".exe", ".bin",
+    ".pyc", ".pyo",
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx",
+    ".mp3", ".mp4", ".avi", ".mov",
+    ".woff2", ".woff", ".eot",
+    ".map", ".min.js", ".min.css",
+}
+
+CONFIG_FILENAMES = [".codecontext.toml", ".codecontext.json", ".codecontext.yml", ".codecontext.yaml"]
+
+
+def should_ignore(name, extra_patterns=None):
+    if any(fnmatch.fnmatch(name, p) for p in IGNORE_PATTERNS):
+        return True
+    if extra_patterns:
+        for p in extra_patterns:
+            if fnmatch.fnmatch(name, p):
+                return True
+    return False
+
+
+def _format_size(size):
+    if size < 1024:
+        return f"{size}B"
+    elif size < 1024 ** 2:
+        return f"{size / 1024:.0f}KB"
+    elif size < 1024 ** 3:
+        return f"{size / 1024 ** 2:.1f}MB"
+    return f"{size / 1024 ** 3:.1f}GB"
+
+
+def scan_tree(root, prefix="", max_files=200, _count=None, extra_ignore=None, show_hidden=False):
+    if _count is None:
+        _count = [0]
+    if _count[0] >= max_files:
+        return []
+    lines = []
+    try:
+        entries = sorted(os.listdir(root))
+    except PermissionError:
+        return lines
+
+    entries = [e for e in entries if not should_ignore(e, extra_ignore)]
+    if not show_hidden:
+        entries = [e for e in entries if not e.startswith(".") or e in (".gitignore", ".env.example")]
+
+    for i, name in enumerate(entries):
+        if _count[0] >= max_files:
+            break
+        path = os.path.join(root, name)
+        is_last = i == len(entries) - 1
+        connector = "└── " if is_last else "├── "
+
+        if os.path.isdir(path):
+            lines.append(f"{prefix}{connector}{name}/")
+            _count[0] += 1
+            extension = "    " if is_last else "│   "
+            lines.extend(scan_tree(path, prefix + extension, max_files, _count, extra_ignore, show_hidden))
+        elif os.path.isfile(path):
+            try:
+                size = os.path.getsize(path)
+                size_str = _format_size(size)
+            except OSError:
+                size_str = "?"
+            lines.append(f"{prefix}{connector}{name} ({size_str})")
+            _count[0] += 1
+    return lines
+
+
+def get_tree(root, max_files=200, extra_ignore=None, show_hidden=False):
+    name = os.path.basename(os.path.abspath(root))
+    lines = [f"{name}/"]
+    lines.extend(scan_tree(root, max_files=max_files, extra_ignore=extra_ignore, show_hidden=show_hidden))
+    return "\n".join(lines)
+
+
+def find_key_files(root, max_size=50_000, extra_ignore=None):
+    key_files = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if not should_ignore(d, extra_ignore)]
+        for f in filenames:
+            if should_ignore(f, extra_ignore):
+                continue
+            path = os.path.join(dirpath, f)
+            ext = os.path.splitext(f)[1].lower()
+            if ext in BINARY_EXTENSIONS:
+                continue
+            try:
+                size = os.path.getsize(path)
+            except OSError:
+                continue
+            if size > max_size:
+                continue
+            rel = os.path.relpath(path, root)
+            key_files.append((rel, path))
+    key_files.sort()
+    return key_files
+
+
+def read_file(path, max_lines=200):
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            lines = f.readlines()
+        if len(lines) > max_lines:
+            lines = lines[:max_lines]
+            lines.append(f"... ({len(lines)} lines shown, truncated)\n")
+        return "".join(lines)
+    except Exception as e:
+        return f"// Error reading file: {e}\n"
+
+
+def load_config(root):
+    for filename in CONFIG_FILENAMES:
+        path = os.path.join(root, filename)
+        if not os.path.isfile(path):
+            continue
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                raw = f.read()
+            if filename.endswith(".toml"):
+                try:
+                    import tomllib
+                    return tomllib.loads(raw)
+                except ImportError:
+                    import tomli as tomllib
+                    return tomllib.loads(raw)
+            elif filename.endswith(".json"):
+                import json
+                return json.loads(raw)
+            elif filename.endswith((".yml", ".yaml")):
+                import yaml
+                return yaml.safe_load(raw)
+        except Exception:
+            pass
+    return {}