ctxl-cli 0.1.0__tar.gz

ctxl_cli-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,136 @@
+# 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/ctxl/__init__.py

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

ctxl_cli-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")