ctxl-cli 0.1.0__py3-none-any.whl

ctxl/__init__.py

@@ -0,0 +1,3 @@
+"""ctxl — Context Engineering CLI for AI agents."""
+
+__version__ = "0.1.0"

ctxl/checkpoint.py

@@ -0,0 +1,130 @@
+"""
+ctx checkpoint — Session state manager.
+
+Tracks what the AI agent has learned during a session (files edited,
+schemas discovered, errors resolved) and saves a compressed checkpoint.
+This allows you to safely run /clear in Copilot Chat without losing context.
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+CHECKPOINT_DIR = ".ctx_checkpoints"
+
+
+def _ensure_dir(project_root: str) -> Path:
+    """Ensure the checkpoint directory exists."""
+    path = Path(project_root).resolve() / CHECKPOINT_DIR
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def create_checkpoint(
+    project_root: str,
+    task: str,
+    completed_steps: List[str],
+    current_state: str,
+    next_steps: List[str],
+    files_modified: Optional[List[str]] = None,
+    key_discoveries: Optional[List[str]] = None,
+    errors_resolved: Optional[List[str]] = None,
+) -> str:
+    """
+    Create a checkpoint file capturing the current session state.
+
+    Args:
+        project_root: Path to the project root directory.
+        task: The high-level task description.
+        completed_steps: List of steps already completed.
+        current_state: Brief description of where things stand right now.
+        next_steps: List of planned next steps.
+        files_modified: List of files that were modified.
+        key_discoveries: Key things learned (schemas, configs, etc.).
+        errors_resolved: Errors that were encountered and resolved.
+
+    Returns:
+        Path to the created checkpoint file.
+    """
+    checkpoint_dir = _ensure_dir(project_root)
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"checkpoint_{timestamp}.md"
+    filepath = checkpoint_dir / filename
+
+    lines = []
+    lines.append(f"# Session Checkpoint")
+    lines.append(f"_Saved at {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}_\n")
+
+    lines.append(f"## Task")
+    lines.append(f"{task}\n")
+
+    lines.append(f"## Current State")
+    lines.append(f"{current_state}\n")
+
+    if completed_steps:
+        lines.append("## Completed Steps")
+        for step in completed_steps:
+            lines.append(f"- [x] {step}")
+        lines.append("")
+
+    if next_steps:
+        lines.append("## Next Steps")
+        for step in next_steps:
+            lines.append(f"- [ ] {step}")
+        lines.append("")
+
+    if files_modified:
+        lines.append("## Files Modified")
+        for f in files_modified:
+            lines.append(f"- `{f}`")
+        lines.append("")
+
+    if key_discoveries:
+        lines.append("## Key Discoveries")
+        for d in key_discoveries:
+            lines.append(f"- {d}")
+        lines.append("")
+
+    if errors_resolved:
+        lines.append("## Errors Resolved")
+        for e in errors_resolved:
+            lines.append(f"- {e}")
+        lines.append("")
+
+    lines.append("---")
+    lines.append("_Paste this into your active file or Copilot Chat after running `/clear`._")
+
+    content = "\n".join(lines)
+    filepath.write_text(content, encoding="utf-8")
+
+    return str(filepath)
+
+
+def list_checkpoints(project_root: str) -> List[Dict]:
+    """List all checkpoints in the project, newest first."""
+    checkpoint_dir = Path(project_root).resolve() / CHECKPOINT_DIR
+    if not checkpoint_dir.exists():
+        return []
+
+    checkpoints = []
+    for f in sorted(checkpoint_dir.glob("checkpoint_*.md"), reverse=True):
+        stat = f.stat()
+        checkpoints.append({
+            "filename": f.name,
+            "path": str(f),
+            "created": datetime.fromtimestamp(stat.st_mtime).strftime("%Y-%m-%d %H:%M:%S"),
+            "size_bytes": stat.st_size,
+        })
+
+    return checkpoints
+
+
+def get_latest_checkpoint(project_root: str) -> Optional[str]:
+    """Read the content of the most recent checkpoint."""
+    checkpoints = list_checkpoints(project_root)
+    if not checkpoints:
+        return None
+    latest_path = checkpoints[0]["path"]
+    return Path(latest_path).read_text(encoding="utf-8")

ctxl/cli.py

@@ -0,0 +1,272 @@
+"""
+ctxl — Context Engineering CLI for AI agents.
+
+Commands:
+    ctxl map     — Generate a compressed codebase skeleton (zero AI, pure parsing)
+    ctxl init    — Generate .github/copilot-instructions.md for focused AI context
+    ctxl checkpoint — Save/view session state for safe /clear workflows
+"""
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich import print as rprint
+
+from ctxl import __version__
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="ctxl")
+def main():
+    """ctxl — Context Engineering CLI for AI agents.
+
+    Reduce token waste and prevent hallucination by giving AI agents
+    precisely the context they need. Zero AI models used — pure parsing.
+    """
+    pass
+
+
+# ─── ctxl map ──────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("path", default=".", type=click.Path(exists=True))
+@click.option("-o", "--output", default=None, help="Write output to a file instead of stdout.")
+@click.option("-e", "--ext", multiple=True, help="Filter by file extension (e.g., -e .py -e .js). Defaults to all supported.")
+@click.option("--clipboard", is_flag=True, help="Copy the output to clipboard.")
+def map(path, output, ext, clipboard):
+    """Generate a compressed codebase skeleton.
+
+    Parses source files using Tree-sitter and extracts only structural
+    information — function signatures, class definitions, and imports.
+    No AI models, no API calls, no tokens burned.
+
+    \b
+    Examples:
+        ctxl map                    # Map current directory
+        ctxl map ./src              # Map a specific directory
+        ctxl map -e .py -e .java   # Only Python and Java files
+        ctxl map -o codebase.md    # Save to file
+        ctxl map --clipboard       # Copy to clipboard for pasting into AI chat
+    """
+    from ctxl.mapper import map_directory, map_file, format_map_output
+    from pathlib import Path as P
+
+    target = P(path).resolve()
+
+    with console.status("[bold cyan]Parsing codebase with Tree-sitter...", spinner="dots"):
+        if target.is_file():
+            skeleton = map_file(str(target))
+            if skeleton is None:
+                console.print(f"[red]✗[/red] Unsupported file type: {target.suffix}")
+                raise SystemExit(1)
+            result = f"## {target.name}\n```\n{skeleton}\n```"
+            file_count = 1
+        else:
+            extensions = list(ext) if ext else None
+            skeletons = map_directory(str(target), extensions)
+            if not skeletons:
+                console.print("[yellow]⚠[/yellow] No supported source files found.")
+                raise SystemExit(0)
+            result = format_map_output(skeletons)
+            file_count = len(skeletons)
+
+    if output:
+        out_path = P(output)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(result, encoding="utf-8")
+        console.print(f"[green]✓[/green] Codebase map written to [bold]{output}[/bold] ({file_count} files)")
+    elif clipboard:
+        try:
+            import pyperclip
+            pyperclip.copy(result)
+            console.print(f"[green]✓[/green] Codebase map copied to clipboard ({file_count} files)")
+        except ImportError:
+            console.print("[yellow]⚠[/yellow] Install `pyperclip` for clipboard support. Printing to stdout instead.\n")
+            console.print(result)
+    else:
+        console.print(result)
+
+    # Show token savings estimate
+    _show_savings(path, result, file_count)
+
+
+def _show_savings(path: str, result: str, file_count: int):
+    """Show estimated token savings."""
+    from pathlib import Path as P
+    import os
+
+    target = P(path).resolve()
+    raw_chars = 0
+
+    if target.is_file():
+        try:
+            raw_chars = target.stat().st_size
+        except OSError:
+            pass
+    else:
+        from ctxl.mapper import LANGUAGE_MAP, IGNORE_PATTERNS, IGNORE_EXTENSIONS
+        for dirpath, dirnames, filenames in os.walk(target):
+            dirnames[:] = [d for d in dirnames if d not in IGNORE_PATTERNS and not d.startswith(".")]
+            for fname in filenames:
+                fpath = P(dirpath) / fname
+                if fpath.suffix.lower() in LANGUAGE_MAP and fpath.suffix.lower() not in IGNORE_EXTENSIONS:
+                    try:
+                        raw_chars += fpath.stat().st_size
+                    except OSError:
+                        pass
+
+    if raw_chars > 0:
+        compressed_chars = len(result)
+        # Rough token estimate: ~4 chars per token
+        raw_tokens = raw_chars // 4
+        compressed_tokens = compressed_chars // 4
+        ratio = round((1 - compressed_tokens / raw_tokens) * 100) if raw_tokens > 0 else 0
+        console.print(
+            Panel(
+                f"[dim]Raw source:[/dim] ~{raw_tokens:,} tokens\n"
+                f"[dim]Skeleton:[/dim]   ~{compressed_tokens:,} tokens\n"
+                f"[bold green]Savings:[/bold green]    ~{ratio}% token reduction",
+                title="[bold]Token Savings Estimate[/bold]",
+                border_style="green",
+                width=45,
+            )
+        )
+
+
+# ─── ctxl init ─────────────────────────────────────────────────────────────────
+
+@main.command()
+@click.argument("task", type=str)
+@click.option("-d", "--directory", default=".", type=click.Path(exists=True), help="Project root directory.")
+@click.option("-f", "--focus", multiple=True, help="Files to focus on (can specify multiple: -f file1.py -f file2.py).")
+@click.option("--no-map", is_flag=True, help="Skip codebase map generation.")
+@click.option("-o", "--output", default=None, help="Custom output path (default: .github/copilot-instructions.md).")
+def init(task, directory, focus, no_map, output):
+    """Generate a task-focused .github/copilot-instructions.md
+
+    GitHub Copilot natively reads this file for workspace-level instructions.
+    This command generates an optimized version tailored to your current task,
+    optionally embedding the codebase skeleton so Copilot understands your
+    project structure without reading every file.
+
+    \b
+    Examples:
+        ctxl init "Fix the data pipeline ETL bug"
+        ctxl init "Add user authentication" -f auth.py -f models.py
+        ctxl init "Refactor tests" --no-map
+    """
+    from ctxl.init import generate_instructions
+
+    focus_files = list(focus) if focus else None
+
+    with console.status("[bold cyan]Generating Copilot instructions...", spinner="dots"):
+        result_path = generate_instructions(
+            project_root=directory,
+            task=task,
+            focus_files=focus_files,
+            include_map=not no_map,
+            output_path=output,
+        )
+
+    console.print(f"[green]✓[/green] Instructions written to [bold]{result_path}[/bold]")
+    console.print("[dim]Copilot will automatically read this file for context.[/dim]")
+
+
+# ─── ctxl checkpoint ───────────────────────────────────────────────────────────
+
+@main.group(name="checkpoint")
+def checkpoint_group():
+    """Save and restore session state for safe /clear workflows."""
+    pass
+
+
+@checkpoint_group.command(name="save")
+@click.option("-d", "--directory", default=".", type=click.Path(exists=True), help="Project root directory.")
+@click.option("-t", "--task", required=True, help="High-level task description.")
+@click.option("--done", multiple=True, help="Completed step (can specify multiple).")
+@click.option("--state", required=True, help="Brief description of current state.")
+@click.option("--next", "next_steps", multiple=True, help="Planned next step (can specify multiple).")
+@click.option("--file", "files", multiple=True, help="File that was modified.")
+@click.option("--learned", multiple=True, help="Key discovery or insight.")
+@click.option("--error", "errors", multiple=True, help="Error that was resolved.")
+def checkpoint_save(directory, task, done, state, next_steps, files, learned, errors):
+    """Save a session checkpoint.
+
+    Captures what you've done, what you know, and what's next — in a compressed
+    format. After saving, you can safely run /clear in Copilot Chat and paste
+    the checkpoint content to restore context.
+
+    \b
+    Example:
+        ctxl checkpoint save \\
+            -t "Fix ETL pipeline" \\
+            --done "Found the bug in clean_data()" \\
+            --done "Updated the schema validation" \\
+            --state "Pipeline runs but output has wrong column order" \\
+            --next "Fix column ordering in transform()" \\
+            --file "data_pipeline.py" \\
+            --learned "The users table has columns: id, name, email, created_at"
+    """
+    from ctxl.checkpoint import create_checkpoint
+
+    result_path = create_checkpoint(
+        project_root=directory,
+        task=task,
+        completed_steps=list(done),
+        current_state=state,
+        next_steps=list(next_steps),
+        files_modified=list(files) if files else None,
+        key_discoveries=list(learned) if learned else None,
+        errors_resolved=list(errors) if errors else None,
+    )
+
+    console.print(f"[green]✓[/green] Checkpoint saved to [bold]{result_path}[/bold]")
+    console.print("[dim]You can now safely run /clear in Copilot Chat.[/dim]")
+    console.print("[dim]Paste the checkpoint content into your next message to restore context.[/dim]")
+
+
+@checkpoint_group.command(name="list")
+@click.option("-d", "--directory", default=".", type=click.Path(exists=True), help="Project root directory.")
+def checkpoint_list(directory):
+    """List all saved checkpoints."""
+    from ctxl.checkpoint import list_checkpoints
+    from rich.table import Table
+
+    checkpoints = list_checkpoints(directory)
+
+    if not checkpoints:
+        console.print("[yellow]⚠[/yellow] No checkpoints found.")
+        return
+
+    table = Table(title="Session Checkpoints", border_style="cyan")
+    table.add_column("#", style="dim", width=4)
+    table.add_column("Created", style="green")
+    table.add_column("Filename")
+    table.add_column("Size", justify="right")
+
+    for i, cp in enumerate(checkpoints, 1):
+        size_str = f"{cp['size_bytes']:,} B"
+        table.add_row(str(i), cp["created"], cp["filename"], size_str)
+
+    console.print(table)
+
+
+@checkpoint_group.command(name="show")
+@click.option("-d", "--directory", default=".", type=click.Path(exists=True), help="Project root directory.")
+def checkpoint_show(directory):
+    """Show the latest checkpoint content."""
+    from ctxl.checkpoint import get_latest_checkpoint
+
+    content = get_latest_checkpoint(directory)
+    if content is None:
+        console.print("[yellow]⚠[/yellow] No checkpoints found. Run `ctxl checkpoint save` first.")
+        return
+
+    console.print(Panel(content, title="[bold]Latest Checkpoint[/bold]", border_style="cyan"))
+
+
+if __name__ == "__main__":
+    main()

ctxl/init.py

@@ -0,0 +1,92 @@
+"""
+ctxl init — Generate optimized .github/copilot-instructions.md
+
+Creates a task-focused instruction file that GitHub Copilot reads natively.
+Optionally integrates the codebase map to give Copilot structural awareness.
+"""
+
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from ctxl.mapper import map_directory, format_map_output
+
+
+DEFAULT_INSTRUCTIONS_TEMPLATE = """# Copilot Context Instructions
+_Auto-generated by `ctxl init` on {timestamp}_
+
+## Current Task
+{task_description}
+
+## Focus Files
+{focus_files}
+
+## Codebase Structure
+{codebase_map}
+
+## Guidelines
+- Focus ONLY on the files and task described above.
+- Do NOT read or modify files outside the focus list unless explicitly asked.
+- Keep responses concise to preserve context window space.
+- If you need to understand a function's implementation, ask — don't guess.
+"""
+
+
+def generate_instructions(
+    project_root: str,
+    task: str,
+    focus_files: Optional[list] = None,
+    include_map: bool = True,
+    output_path: Optional[str] = None,
+) -> str:
+    """
+    Generate a .github/copilot-instructions.md file.
+
+    Args:
+        project_root: Path to the project root directory.
+        task: Description of the current task.
+        focus_files: List of file paths to focus on (relative to project root).
+        include_map: Whether to include the codebase skeleton map.
+        output_path: Custom output path. Defaults to .github/copilot-instructions.md.
+
+    Returns:
+        The path to the generated instructions file.
+    """
+    root = Path(project_root).resolve()
+
+    # Build focus files section
+    if focus_files:
+        focus_section = "\n".join(f"- `{f}`" for f in focus_files)
+    else:
+        focus_section = "_No specific focus files set. Copilot will use its default context._"
+
+    # Build codebase map section
+    if include_map:
+        skeletons = map_directory(str(root))
+        if skeletons:
+            codebase_map = format_map_output(skeletons)
+        else:
+            codebase_map = "_No supported source files found for mapping._"
+    else:
+        codebase_map = "_Codebase map not included. Run `ctxl map` to generate one._"
+
+    # Fill the template
+    content = DEFAULT_INSTRUCTIONS_TEMPLATE.format(
+        timestamp=datetime.now().strftime("%Y-%m-%d %H:%M"),
+        task_description=task,
+        focus_files=focus_section,
+        codebase_map=codebase_map,
+    )
+
+    # Determine output path
+    if output_path is None:
+        out_dir = root / ".github"
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out_file = out_dir / "copilot-instructions.md"
+    else:
+        out_file = Path(output_path)
+        out_file.parent.mkdir(parents=True, exist_ok=True)
+
+    out_file.write_text(content, encoding="utf-8")
+    return str(out_file)

ctxl/mapper.py

@@ -0,0 +1,439 @@
+"""
+ctx map — Codebase skeleton generator using Tree-sitter.
+
+Parses source code files using Tree-sitter ASTs and extracts only
+structural information (function signatures, class definitions, imports)
+to produce a compressed codebase map. Zero AI, zero tokens, pure parsing.
+"""
+
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import tree_sitter_python as tspython
+import tree_sitter_javascript as tsjavascript
+import tree_sitter_java as tsjava
+import tree_sitter_typescript as tstypescript
+from tree_sitter import Language, Parser, Node
+
+
+# ─── Language Registry ─────────────────────────────────────────────────────────
+
+LANGUAGE_MAP: Dict[str, Tuple] = {
+    ".py": ("python", tspython),
+    ".js": ("javascript", tsjavascript),
+    ".jsx": ("javascript", tsjavascript),
+    ".java": ("java", tsjava),
+    ".ts": ("typescript", tstypescript),
+    ".tsx": ("typescript", tstypescript),
+}
+
+# File patterns to always ignore
+IGNORE_PATTERNS = {
+    "__pycache__", ".git", ".venv", "venv", "node_modules", ".mypy_cache",
+    ".pytest_cache", "dist", "build", ".egg-info", ".tox", ".nox",
+    "__pypackages__", ".ctx_output",
+}
+
+IGNORE_EXTENSIONS = {
+    ".pyc", ".pyo", ".class", ".o", ".so", ".dll", ".exe",
+    ".png", ".jpg", ".jpeg", ".gif", ".svg", ".ico",
+    ".zip", ".tar", ".gz", ".bz2",
+    ".lock", ".log",
+}
+
+
+def _get_parser(extension: str) -> Optional[Parser]:
+    """Create a Tree-sitter parser for the given file extension."""
+    if extension not in LANGUAGE_MAP:
+        return None
+    lang_name, lang_module = LANGUAGE_MAP[extension]
+    language = Language(lang_module.language())
+    parser = Parser(language)
+    return parser
+
+
+def _get_node_text(node: Node, source: bytes) -> str:
+    """Extract the text of a node from source bytes."""
+    return source[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+
+
+# ─── Python Extractor ──────────────────────────────────────────────────────────
+
+def _line_num(node: Node) -> int:
+    """Get 1-indexed line number from a Tree-sitter node."""
+    return node.start_point[0] + 1
+
+
+def _extract_python(tree, source: bytes) -> List[str]:
+    """Extract structural skeleton from a Python AST."""
+    lines = []
+    root = tree.root_node
+
+    # Pass 1: Collect imports
+    imports = []
+    for child in root.children:
+        if child.type in ("import_statement", "import_from_statement"):
+            imports.append(_get_node_text(child, source).strip())
+
+    if imports:
+        # Compress imports into a single summary line
+        lines.append("imports: " + "; ".join(imports))
+        lines.append("")
+
+    # Pass 2: Collect top-level assignments (constants/configs)
+    for child in root.children:
+        if child.type == "expression_statement":
+            expr = child.children[0] if child.children else None
+            if expr and expr.type == "assignment":
+                target = _get_node_text(expr.children[0], source).strip()
+                ln = _line_num(child)
+                lines.append(f"L{ln}: {target} = ...")
+
+    # Pass 3: Collect top-level functions and classes
+    for child in root.children:
+        if child.type == "function_definition":
+            lines.append("")
+            lines.append(_extract_python_function(child, source, indent=0))
+        elif child.type == "decorated_definition":
+            # Handle decorated functions/classes
+            for sub in child.children:
+                if sub.type == "function_definition":
+                    decorator_text = []
+                    for d in child.children:
+                        if d.type == "decorator":
+                            decorator_text.append(f"L{_line_num(d)}: {_get_node_text(d, source).strip()}")
+                    lines.append("")
+                    for dt in decorator_text:
+                        lines.append(dt)
+                    lines.append(_extract_python_function(sub, source, indent=0))
+                elif sub.type == "class_definition":
+                    decorator_text = []
+                    for d in child.children:
+                        if d.type == "decorator":
+                            decorator_text.append(f"L{_line_num(d)}: {_get_node_text(d, source).strip()}")
+                    lines.append("")
+                    for dt in decorator_text:
+                        lines.append(dt)
+                    lines.extend(_extract_python_class(sub, source))
+        elif child.type == "class_definition":
+            lines.append("")
+            lines.extend(_extract_python_class(child, source))
+
+    return lines
+
+
+def _extract_python_function(node: Node, source: bytes, indent: int = 0) -> str:
+    """Extract a function signature (no body) with line number."""
+    prefix = "    " * indent
+    name = ""
+    params = ""
+    return_type = ""
+    ln = _line_num(node)
+
+    for child in node.children:
+        if child.type == "identifier":
+            name = _get_node_text(child, source)
+        elif child.type == "parameters":
+            params = _get_node_text(child, source)
+        elif child.type == "type":
+            return_type = f" -> {_get_node_text(child, source)}"
+
+    return f"{prefix}L{ln}: def {name}{params}{return_type}"
+
+
+def _extract_python_class(node: Node, source: bytes) -> List[str]:
+    """Extract a class definition with its method signatures."""
+    lines = []
+    class_name = ""
+    superclasses = ""
+    docstring = ""
+    ln = _line_num(node)
+
+    for child in node.children:
+        if child.type == "identifier":
+            class_name = _get_node_text(child, source)
+        elif child.type == "argument_list":
+            superclasses = _get_node_text(child, source)
+
+    class_line = f"L{ln}: class {class_name}"
+    if superclasses:
+        class_line += superclasses
+    class_line += ":"
+    lines.append(class_line)
+
+    # Walk class body for methods and class-level docstring
+    body = None
+    for child in node.children:
+        if child.type == "block":
+            body = child
+            break
+
+    if body:
+        for i, child in enumerate(body.children):
+            # Get class docstring (first expression statement with a string)
+            if i == 0 and child.type == "expression_statement":
+                expr = child.children[0] if child.children else None
+                if expr and expr.type == "string":
+                    docstring = _get_node_text(expr, source).strip()
+                    lines.append(f"    {docstring}")
+
+            if child.type == "function_definition":
+                lines.append(_extract_python_function(child, source, indent=1))
+            elif child.type == "decorated_definition":
+                for sub in child.children:
+                    if sub.type == "decorator":
+                        lines.append(f"    {_get_node_text(sub, source).strip()}")
+                    elif sub.type == "function_definition":
+                        lines.append(_extract_python_function(sub, source, indent=1))
+
+    return lines
+
+
+# ─── JavaScript/TypeScript Extractor ───────────────────────────────────────────
+
+def _extract_js(tree, source: bytes) -> List[str]:
+    """Extract structural skeleton from JavaScript/TypeScript AST."""
+    lines = []
+    root = tree.root_node
+
+    for child in root.children:
+        if child.type in ("import_statement",):
+            lines.append(f"L{_line_num(child)}: {_get_node_text(child, source).strip()}")
+        elif child.type == "function_declaration":
+            lines.append(_extract_js_function(child, source))
+        elif child.type == "class_declaration":
+            lines.extend(_extract_js_class(child, source))
+        elif child.type in ("export_statement",):
+            for sub in child.children:
+                if sub.type == "function_declaration":
+                    lines.append("export " + _extract_js_function(sub, source))
+                elif sub.type == "class_declaration":
+                    cls_lines = _extract_js_class(sub, source)
+                    if cls_lines:
+                        cls_lines[0] = "export " + cls_lines[0]
+                    lines.extend(cls_lines)
+                elif sub.type == "lexical_declaration":
+                    lines.append("export " + _extract_js_variable(sub, source))
+        elif child.type == "lexical_declaration":
+            lines.append(_extract_js_variable(child, source))
+
+    return lines
+
+
+def _extract_js_function(node: Node, source: bytes) -> str:
+    """Extract a JS function signature with line number."""
+    name = ""
+    params = ""
+    ln = _line_num(node)
+    for child in node.children:
+        if child.type == "identifier":
+            name = _get_node_text(child, source)
+        elif child.type == "formal_parameters":
+            params = _get_node_text(child, source)
+    return f"L{ln}: function {name}{params}"
+
+
+def _extract_js_class(node: Node, source: bytes) -> List[str]:
+    """Extract a JS class with method signatures and line numbers."""
+    lines = []
+    class_name = ""
+    ln = _line_num(node)
+    for child in node.children:
+        if child.type == "identifier":
+            class_name = _get_node_text(child, source)
+    lines.append(f"L{ln}: class {class_name}:")
+
+    body = None
+    for child in node.children:
+        if child.type == "class_body":
+            body = child
+            break
+
+    if body:
+        for child in body.children:
+            if child.type == "method_definition":
+                name = ""
+                params = ""
+                mln = _line_num(child)
+                for sub in child.children:
+                    if sub.type == "property_identifier":
+                        name = _get_node_text(sub, source)
+                    elif sub.type == "formal_parameters":
+                        params = _get_node_text(sub, source)
+                lines.append(f"    L{mln}: {name}{params}")
+
+    return lines
+
+
+def _extract_js_variable(node: Node, source: bytes) -> str:
+    """Extract a top-level variable/const declaration with line number."""
+    ln = _line_num(node)
+    text = _get_node_text(node, source).strip()
+    # Truncate the value — just show the declaration name
+    if "=" in text:
+        left = text.split("=")[0].strip()
+        return f"L{ln}: {left} = ..."
+    return f"L{ln}: {text}"
+
+
+# ─── Java Extractor ────────────────────────────────────────────────────────────
+
+def _extract_java(tree, source: bytes) -> List[str]:
+    """Extract structural skeleton from Java AST."""
+    lines = []
+    root = tree.root_node
+
+    for child in root.children:
+        if child.type == "package_declaration":
+            lines.append(_get_node_text(child, source).strip())
+        elif child.type == "import_declaration":
+            lines.append(_get_node_text(child, source).strip())
+        elif child.type == "class_declaration":
+            lines.extend(_extract_java_class(child, source))
+
+    return lines
+
+
+def _extract_java_class(node: Node, source: bytes) -> List[str]:
+    """Extract a Java class with method signatures."""
+    lines = []
+    class_header_parts = []
+
+    for child in node.children:
+        if child.type in ("modifiers",):
+            class_header_parts.append(_get_node_text(child, source))
+        elif child.type == "identifier":
+            class_header_parts.append(f"class {_get_node_text(child, source)}")
+        elif child.type == "superclass":
+            class_header_parts.append(_get_node_text(child, source))
+
+    lines.append(f"L{_line_num(node)}: " + " ".join(class_header_parts) + ":")
+
+    body = None
+    for child in node.children:
+        if child.type == "class_body":
+            body = child
+            break
+
+    if body:
+        for child in body.children:
+            if child.type == "method_declaration":
+                sig_parts = []
+                for sub in child.children:
+                    if sub.type in ("modifiers",):
+                        sig_parts.append(_get_node_text(sub, source))
+                    elif sub.type in ("void_type", "type_identifier", "integral_type",
+                                      "boolean_type", "floating_point_type", "generic_type",
+                                      "array_type"):
+                        sig_parts.append(_get_node_text(sub, source))
+                    elif sub.type == "identifier":
+                        sig_parts.append(_get_node_text(sub, source))
+                    elif sub.type == "formal_parameters":
+                        sig_parts.append(_get_node_text(sub, source))
+                lines.append(f"    L{_line_num(child)}: " + " ".join(sig_parts))
+            elif child.type == "constructor_declaration":
+                sig_parts = []
+                for sub in child.children:
+                    if sub.type in ("modifiers",):
+                        sig_parts.append(_get_node_text(sub, source))
+                    elif sub.type == "identifier":
+                        sig_parts.append(_get_node_text(sub, source))
+                    elif sub.type == "formal_parameters":
+                        sig_parts.append(_get_node_text(sub, source))
+                lines.append("    " + " ".join(sig_parts))
+
+    return lines
+
+
+# ─── Dispatcher ────────────────────────────────────────────────────────────────
+
+EXTRACTORS = {
+    "python": _extract_python,
+    "javascript": _extract_js,
+    "typescript": _extract_js,  # TS shares structural similarities with JS
+    "java": _extract_java,
+}
+
+
+def map_file(filepath: str) -> Optional[str]:
+    """
+    Generate a compressed skeleton for a single file.
+    Returns None if the file type is unsupported.
+    """
+    path = Path(filepath)
+    ext = path.suffix.lower()
+
+    parser = _get_parser(ext)
+    if parser is None:
+        return None
+
+    lang_name = LANGUAGE_MAP[ext][0]
+    extractor = EXTRACTORS.get(lang_name)
+    if extractor is None:
+        return None
+
+    try:
+        source = path.read_bytes()
+    except (OSError, IOError):
+        return None
+
+    tree = parser.parse(source)
+    lines = extractor(tree, source)
+
+    if not lines:
+        return None
+
+    return "\n".join(lines)
+
+
+def map_directory(directory: str, extensions: Optional[List[str]] = None) -> Dict[str, str]:
+    """
+    Walk a directory and generate skeletons for all supported files.
+    Returns a dict of {relative_path: skeleton_text}.
+    """
+    root = Path(directory).resolve()
+    results: Dict[str, str] = {}
+
+    if extensions is None:
+        extensions = list(LANGUAGE_MAP.keys())
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Prune ignored directories
+        dirnames[:] = [d for d in dirnames if d not in IGNORE_PATTERNS
+                       and not d.startswith(".")]
+
+        for fname in sorted(filenames):
+            fpath = Path(dirpath) / fname
+            ext = fpath.suffix.lower()
+
+            if ext in IGNORE_EXTENSIONS:
+                continue
+            if ext not in extensions:
+                continue
+
+            skeleton = map_file(str(fpath))
+            if skeleton:
+                rel_path = str(fpath.relative_to(root)).replace("\\", "/")
+                results[rel_path] = skeleton
+
+    return results
+
+
+def format_map_output(skeletons: Dict[str, str]) -> str:
+    """Format all skeletons into a single markdown document."""
+    if not skeletons:
+        return "# Codebase Map\n\n_No supported source files found._\n"
+
+    sections = []
+    sections.append("# Codebase Map")
+    sections.append(f"_Generated by `ctx map` — {len(skeletons)} file(s) indexed._\n")
+
+    for filepath, skeleton in skeletons.items():
+        sections.append(f"## {filepath}")
+        sections.append("```")
+        sections.append(skeleton)
+        sections.append("```")
+        sections.append("")
+
+    return "\n".join(sections)

ctxl_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: ctxl-cli
+Version: 0.1.0
+Summary: Context Engineering CLI — Reduce AI agent token waste with compressed codebase skeletons, task-focused instructions, and session checkpoints. Zero AI, pure parsing.
+Author: Prashanth Reddy
+License: MIT
+Project-URL: Homepage, https://github.com/prashanthreddy/ctxl
+Project-URL: Repository, https://github.com/prashanthreddy/ctxl
+Project-URL: Issues, https://github.com/prashanthreddy/ctxl/issues
+Keywords: context-engineering,llm,ai-agents,token-optimization,copilot,tree-sitter,codebase-map,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: tree-sitter>=0.24
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-java>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Requires-Dist: rich>=13.0
+Provides-Extra: clipboard
+Requires-Dist: pyperclip>=1.8; extra == "clipboard"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# ctxl — Context Engineering CLI for AI Agents
+
+**Reduce token waste. Prevent hallucination. Zero AI used.**
+
+`ctxl` (pronounced "contextual") is a developer CLI tool that helps you manage the context window of AI coding agents (GitHub Copilot, Cursor, Claude, etc.) by generating compressed codebase skeletons, task-focused instructions, and session checkpoints — all using deterministic parsing, not AI.
+
+## The Problem
+
+AI coding agents (Copilot, Cursor, etc.) read your entire codebase to build context. A 3,000-line PySpark file burns ~750 tokens every time the agent references it. Over a session, your context window fills with noise, leading to:
+
+- 🔴 **Hallucination** — the model starts making things up
+- 🔴 **Token waste** — you pay for irrelevant context
+- 🔴 **Lost focus** — the agent forgets your actual task
+
+## The Solution
+
+`ctxl` gives you three commands that prepare your environment *before* the AI agent reads it:
+
+```bash
+ctxl map          # Generate a compressed codebase skeleton (~95% token reduction)
+ctxl init         # Generate task-focused Copilot instructions
+ctxl checkpoint   # Save session state for safe /clear workflows
+```
+
+**Zero AI models. Zero API calls. Zero tokens burned by this tool.**
+
+## Installation
+
+```bash
+pip install ctxl-cli
+```
+
+## Quick Start
+
+### `ctxl map` — Codebase Skeleton
+
+Generate a compressed structural map of your codebase with line numbers:
+
+```bash
+ctxl map                      # Map current directory
+ctxl map ./src                # Map a specific directory
+ctxl map -e .py               # Only Python files
+ctxl map -o codebase.md       # Save to file
+ctxl map --clipboard          # Copy to clipboard for pasting into AI chat
+```
+
+**Before (raw file, ~750 tokens):**
+```python
+class DataPipeline:
+    def __init__(self, spark, config):
+        self.spark = spark
+        self.config = config
+        self.source_path = config.get("source_path", "/data/raw")
+        # ... 60 more lines of implementation
+    
+    def clean_data(self, df, drop_nulls=True):
+        string_cols = [f.name for f in df.schema.fields ...]
+        # ... 20 more lines
+```
+
+**After (`ctxl map` output, ~50 tokens):**
+```
+L22: class DataPipeline:
+    L25: def __init__(self, spark: SparkSession, config: Dict)
+    L33: def load_data(self, table_name: str, filters: Optional[Dict] = None) -> DataFrame
+    L42: def clean_data(self, df: DataFrame, drop_nulls: bool = True) -> DataFrame
+    L52: def transform(self, df: DataFrame, rules: List[Dict]) -> DataFrame
+    L66: def validate(self, df: DataFrame) -> bool
+    L75: def save(self, df: DataFrame, partition_cols: List[str] = None) -> str
+```
+
+Line numbers (`L22:`, `L42:`) let the AI agent navigate directly to the right location.
+
+### `ctxl init` — Copilot Instructions
+
+Generate a `.github/copilot-instructions.md` file that GitHub Copilot reads natively:
+
+```bash
+ctxl init "Fix the data pipeline ETL bug"
+ctxl init "Add authentication" -f auth.py -f models.py
+ctxl init "Refactor tests" --no-map
+```
+
+### `ctxl checkpoint` — Session State
+
+Save your progress before running `/clear` in Copilot Chat:
+
+```bash
+ctxl checkpoint save \
+    -t "Fix ETL pipeline" \
+    --done "Found the bug in clean_data()" \
+    --state "Pipeline runs but output has wrong column order" \
+    --next "Fix column ordering in transform()" \
+    --file "data_pipeline.py"
+
+ctxl checkpoint list          # List all checkpoints
+ctxl checkpoint show          # Show latest checkpoint
+```
+
+## Supported Languages
+
+`ctxl map` uses [Tree-sitter](https://tree-sitter.github.io/) for parsing and supports:
+
+| Language | Extensions |
+|----------|-----------|
+| Python | `.py` |
+| JavaScript | `.js`, `.jsx` |
+| TypeScript | `.ts`, `.tsx` |
+| Java | `.java` |
+
+More languages can be added easily via Tree-sitter grammars.
+
+## How It Works
+
+```
+Your Codebase (10,000+ tokens)
+        │
+        ▼
+   Tree-sitter Parser (deterministic, local, free)
+        │
+        ▼
+   AST → Extract signatures + line numbers
+        │
+        ▼
+   Compressed Skeleton (~500 tokens)
+        │
+        ▼
+   AI Agent reads skeleton instead of raw code
+        │
+        ▼
+   90-95% fewer tokens burned 🎉
+```
+
+## License
+
+MIT

ctxl_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ctxl/__init__.py,sha256=UpoJyjx2hepXR8KF3H6OenKfBk-IvUk3nkMJ98PGzfA,77
+ctxl/checkpoint.py,sha256=GPkKDXRAGXlZvi5g_9TYtLd326xT5GXK7Pa3UXucNdc,4002
+ctxl/cli.py,sha256=mFFjlMBFoqFBoUXJ4vEtPbTYmVX8P2bEadHCFscOrHE,11300
+ctxl/init.py,sha256=_ihi6HACeKWoQHr7RkvqOp8L_LX7s52TTgDaIYSdxqo,2809
+ctxl/mapper.py,sha256=X2Pydd890vdXx9GuqlTg9FDTTef_EY7yphHTfUpioTI,16315
+ctxl_cli-0.1.0.dist-info/licenses/LICENSE,sha256=eA0xRKuj6ea-BZ9y3v1fbypmbxCUGR0yqwYjQpGUpdE,1072
+ctxl_cli-0.1.0.dist-info/METADATA,sha256=0gne2cohmBs3tyF8H32PZi3KqI9yvA14Wnm8LMH6FMk,6120
+ctxl_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ctxl_cli-0.1.0.dist-info/entry_points.txt,sha256=qD7gAhtk7VXHnpW37TUR7D2dyb7jyVJGKINRtxqJUa4,39
+ctxl_cli-0.1.0.dist-info/top_level.txt,sha256=t3CHnQUVd8wlny-CPnhlsl2KMHowoik24WLCEMBvxQA,5
+ctxl_cli-0.1.0.dist-info/RECORD,,

ctxl_cli-0.1.0.dist-info/WHEEL

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

ctxl_cli-0.1.0.dist-info/entry_points.txt

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

ctxl_cli-0.1.0.dist-info/licenses/LICENSE

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

ctxl_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ctxl