ctx-bridge 0.1.0__py3-none-any.whl

ctx_bridge-0.1.0.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: ctx-bridge
+Version: 0.1.0
+Summary: CLI tool to snapshot project context, git state, diffs, and progress logs for AI assistant session handoffs.
+Author: Maaz Korejo
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Maazkorejo/CTX-Bridge
+Keywords: ai,cli,context,prompt,git,developer-tools,handoff,bridge
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: pyperclip>=1.8.0
+Requires-Dist: pathspec>=0.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# 🌁 CTX-Bridge (`ctx-bridge` / `bridge`)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
+[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+> **Bridge the context gap between AI coding assistants.**  
+> Snapshot your git state, code diffs, directory structure, project metadata, and running progress logs into a clean, paste-ready handoff summary — so your next AI session picks up **exactly where the last one left off.**
+
+---
+
+## ⚡ The Problem
+
+When coding with AI assistants (**Cursor, GitHub Copilot, Windsurf, Claude Code, ChatGPT**), you inevitably hit context window limits or session resets mid-task. Switching tools or starting a fresh chat forces you to re-explain everything from scratch — wasting **time, tokens, and focus**.
+
+## 🚀 The Solution: `CTX-Bridge`
+
+`CTX-Bridge` acts as persistent cognitive memory for your developer workspace. With simple terminal commands, it captures what was done, what files were touched, uncommitted git diffs, project dependencies, and an ASCII tree structure — framing it instantly into your clipboard and a saved snapshot document.
+
+```
+       [ AI Assistant Session 1 ]
+                   │
+                   ▼  (Run: bridge export)
+       ┌───────────────────────┐
+       │   CTX-Bridge Engine   │ ──► Saved .ctx/exports/handoff.md
+       └───────────────────────┘ ──► Copied to Clipboard
+                   │
+                   ▼  (Paste into New Chat)
+       [ AI Assistant Session 2 ]
+```
+
+---
+
+## ✨ Features
+
+- 🌐 **Web Chat Session Handoff (`bridge chat`)**: Purpose-built for web browser AI chats. Wrap copied code/notes into a formatted prompt instantly.
+- 🌿 **Git State Integration**: Extracts active branch, recent commit logs, staged, unstaged, and untracked files.
+- 📝 **Code Diff Capture**: Captures working tree `git diff` output with configurable line limit truncation.
+- 🌲 **Smart Directory Tree**: Generates ASCII project structure respecting `.gitignore` patterns with directory symlink loop protection.
+- 🔍 **Multi-Language Auto-Detection**: Automatically identifies project language and framework:
+  - **Python** (FastAPI, Django, Flask, `pyproject.toml`, `requirements.txt`)
+  - **JavaScript / TypeScript** (Next.js, React, Vue, Express, NestJS)
+  - **Rust** (`Cargo.toml`) | **Go** (`go.mod`) | **Java/Kotlin** (Maven, Gradle)
+  - **C# / .NET** (`*.csproj`, `*.sln`) | **Ruby** (`Gemfile`) | **PHP** (`composer.json`)
+- 📋 **Running Session Logs**: Add timestamped progress notes while coding (`bridge log "..."`).
+- 🤖 **AI Assistant Presets**: Tailored prompt framing preambles for **Cursor**, **GitHub Copilot**, **Claude**, **ChatGPT**, and **Generic AI**.
+- 🛡️ **Security Safeguards**:
+  - Automatically appends `.ctx/` to `.gitignore` on initialization.
+  - Automatically redacts sensitive files (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `credentials.json`) from diffs and status reports.
+
+---
+
+## 📦 Installation
+
+```bash
+# Clone repository
+git clone https://github.com/Maazkorejo/CTX-Bridge.git
+cd CTX-Bridge
+
+# Install locally in editable mode
+pip install -e .
+```
+
+After installation, both `ctx-bridge` and the shortcut `bridge` are available in your terminal:
+```bash
+bridge --version
+# Output: ctx-bridge, version 0.1.0
+```
+
+---
+
+## 🛠️ Detailed Command Reference
+
+You can invoke commands using either `bridge` or `ctx-bridge`.
+
+### 1. `bridge chat`
+Purpose-built for web browser AI chat sessions (no repository required). Formats copied code and task goals into a paste-ready handoff prompt and copies it to your clipboard.
+
+```bash
+# Interactive mode (prompts for goal, code/clipboard, and next task)
+bridge chat
+
+# Auto-grab whatever you just copied from your browser chat:
+bridge chat --from-clipboard
+
+# Command-line flags mode:
+bridge chat --goal "FastAPI Auth Service" --task "Add password hashing" --template claude
+```
+
+### 2. `bridge init`
+Initializes `.ctx/` configuration directory and `progress.md` in your project root. Automatically appends `.ctx/` to `.gitignore`.
+
+```bash
+bridge init
+# Custom project name:
+bridge init --name "my-awesome-service"
+```
+
+### 2. `bridge log <message>`
+Appends a timestamped progress note to `.ctx/progress.md` so the AI knows what has already been accomplished.
+
+```bash
+bridge log "Created user authentication endpoints in /api/auth"
+bridge log "Fixed JWT token verification bug in middleware"
+```
+
+### 3. `bridge status`
+Displays a rich terminal table showing project metadata, active git branch, modified files count, and logged entries.
+
+```bash
+bridge status
+```
+
+### 4. `bridge export`
+Generates the complete context snapshot markdown report, copies it to your **system clipboard**, and saves a snapshot copy to `.ctx/exports/handoff_<timestamp>.md`.
+
+```bash
+# Export with default generic AI framing
+bridge export
+
+# Export framed specifically for Cursor IDE or Claude
+bridge export --template cursor
+bridge export --template claude
+
+# Export Flags:
+bridge export --no-clipboard  # Do not copy to system clipboard
+bridge export --no-file       # Do not save .md file to disk
+bridge export --stdout        # Output markdown directly to stdout
+```
+
+### 5. `bridge reset`
+Clears current progress entries in `.ctx/progress.md` for a fresh session.
+
+```bash
+bridge reset
+```
+
+---
+
+## 📄 Example Export Snapshot Output
+
+Here is what `bridge export` copies to your clipboard:
+
+```markdown
+# 🔄 Context Handoff — my-fastapi-app
+
+> **Generated at**: 2026-08-13 05:15:00
+> [CURSOR HANDOFF SESSION] You are Cursor AI assistant. Resume the active coding task using the project context below.
+
+## 📋 Session Progress Log
+- **[2026-08-13 04:30:12]** Created database schema for users and auth tokens
+- **[2026-08-13 05:10:45]** Implemented JWT token verification middleware
+
+## 🌿 Git State
+- **Branch**: `feature/auth`
+- **Staged Files**: `app/auth.py`, `app/main.py`
+- **Unstaged Files**: `tests/test_auth.py`
+
+**Recent Commits**:
+- `a1b2c3d` — Initial project structure
+- `e5f6g7h` — Add database config
+
+## 📝 Code Changes (git diff)
+```diff
+--- a/app/auth.py
++++ b/app/auth.py
+@@ -12,4 +12,4 @@ def verify_token(token: str):
+-    return jwt.decode(token, SECRET)
++    return jwt.decode(token, SECRET, algorithms=["HS256"])
+```
+
+## 📁 Project Structure (`*` = modified)
+```
+my-fastapi-app/
+├── app/
+│   ├── __init__.py
+│   ├── auth.py *
+│   └── main.py *
+├── tests/
+│   └── test_auth.py *
+├── pyproject.toml
+└── requirements.txt
+```
+
+## 🔧 Project Info
+- **Type**: Python
+- **Framework**: FastAPI
+- **Key Dependencies**: fastapi, uvicorn, pyjwt, pydantic
+```
+
+---
+
+## ⚙️ Configuration (`.ctx/config.json`)
+
+When you run `bridge init`, `.ctx/config.json` is created:
+
+```json
+{
+  "project_name": "my-project",
+  "project_type": "Python",
+  "template": "generic",
+  "export_format": "markdown",
+  "max_diff_lines": 300,
+  "max_tree_depth": 4,
+  "ignore_patterns": [
+    "node_modules",
+    ".git",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+    ".ctx"
+  ]
+}
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+# Install development dependencies
+pip install -e .[dev]
+
+# Run full test suite
+python -m pytest tests/ -v
+```
+
+---
+
+## 👤 Author & Maintainer
+
+**Maaz Korejo**
+- GitHub: [@Maazkorejo](https://github.com/Maazkorejo)
+- Repository: [CTX-Bridge](https://github.com/Maazkorejo/CTX-Bridge)
+
+---
+
+## 📜 License
+
+Distributed under the [MIT License](LICENSE).

ctx_bridge-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ctx_bridge-0.1.0.dist-info/licenses/LICENSE,sha256=_k1R-l6uFzyI_xwFxcz4dW0qxJD4jAiHlB7fQY75oFo,1089
+ctx_tool/__init__.py,sha256=0O8cTmdJkj5IlWZHH6kcn5GdId30NKLrFBUC5M5qRi0,52
+ctx_tool/__main__.py,sha256=0-Jiq5KVjR3UiGFOJ16da-iJTRH9jOd2gw3BQ1dWJIA,71
+ctx_tool/cli.py,sha256=iL5Aiiid2_ksioCNMkX9ZmHEZxC8iDM05FrZxqlPQVo,10177
+ctx_tool/config.py,sha256=YwU0N5pFd9fVMAw0cVB7ghfZumlVvpAupHrVJyzJkBA,3653
+ctx_tool/detector.py,sha256=ZgZZLmvcsvGJTihMAFkoM2NqZuZAUv_7I2Vw863M7tw,4109
+ctx_tool/exporter.py,sha256=pg12T8NGs4IgF9gMsW2xf3UKE46g-ieBj8FBat2KeI4,5890
+ctx_tool/git_utils.py,sha256=ENHalsZBJTWoE55RMyKbcmB3seT9-D3kfcAyxpZmx_o,4471
+ctx_tool/session.py,sha256=NwNeIvqrrHhDvjfp2nNn6oceKKO8McXpFTDIp57GQ6M,1867
+ctx_tool/templates.py,sha256=an8KdUBVSsIclZwCj45zszA1EcT7G2YPyVF26Y4IZdo,1448
+ctx_tool/tree.py,sha256=LvGhhBB4DNAhg1kRun7Qa_H8GQtz_PPSB9pDxRK2NyA,2591
+ctx_bridge-0.1.0.dist-info/METADATA,sha256=ptgERFiC2G6W2qThtUG2z5DCt0MpBk3c6WvA1ovWm4g,8722
+ctx_bridge-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ctx_bridge-0.1.0.dist-info/entry_points.txt,sha256=1sDPmd4zOQs1jwxFJiv4iMnG61606z9ntwwd3RcPqQU,74
+ctx_bridge-0.1.0.dist-info/top_level.txt,sha256=KbDA_67Z_yoRPLAjS7lmaNF6nOEXzQAqV5RS4KU5SAw,9
+ctx_bridge-0.1.0.dist-info/RECORD,,

ctx_bridge-0.1.0.dist-info/WHEEL

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

ctx_bridge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+bridge = ctx_tool.cli:cli
+ctx-bridge = ctx_tool.cli:cli

ctx_bridge-0.1.0.dist-info/licenses/LICENSE

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

ctx_bridge-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ctx_tool

ctx_tool/__init__.py

@@ -0,0 +1,2 @@
+"""promtext-ctx package."""
+__version__ = "0.1.0"

ctx_tool/__main__.py

@@ -0,0 +1,4 @@
+from ctx_tool.cli import cli
+
+if __name__ == "__main__":
+    cli()

ctx_tool/cli.py

@@ -0,0 +1,235 @@
+from pathlib import Path
+from typing import Optional
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from ctx_tool import __version__
+from ctx_tool.config import find_ctx_root, init_ctx_dir, is_initialized, load_config, save_config
+from ctx_tool.detector import detect_project_type
+from ctx_tool.exporter import export_chat_context, export_context
+from ctx_tool.git_utils import get_branch, get_git_status, get_recent_commits, get_repo
+from ctx_tool.session import get_entries, log_entry, reset_session
+import pyperclip
+
+console = Console()
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(version=__version__, prog_name="ctx-bridge")
+@click.pass_context
+def cli(ctx):
+    """ctx-bridge (`bridge`): AI Context Handoff CLI Tool for AI coding assistants."""
+    if ctx.invoked_subcommand is None:
+        console.print(
+            Panel.fit(
+                "[bold cyan]ctx-bridge[/bold cyan] — AI Coding Context Handoff Tool\n\n"
+                "Commands:\n"
+                "  [green]ctx-bridge chat[/green]   (or [green]bridge chat[/green])     Format web chat code & notes into handoff prompt\n"
+                "  [green]ctx-bridge init[/green]   (or [green]bridge init[/green])     Initialize context tracking\n"
+                "  [green]ctx-bridge log[/green]    (or [green]bridge log[/green])      Add progress note to session log\n"
+                "  [green]ctx-bridge status[/green] (or [green]bridge status[/green])   Show project tracking overview\n"
+                "  [green]ctx-bridge export[/green] (or [green]bridge export[/green])   Export repo handoff to clipboard & markdown\n"
+                "  [green]ctx-bridge reset[/green]  (or [green]bridge reset[/green])    Clear progress log for a fresh session\n\n"
+                "Run [bold yellow]ctx-bridge --help[/bold yellow] for detailed usage options.",
+                title="ctx-bridge CLI",
+            )
+        )
+
+
+@cli.command("init")
+@click.option("--name", "-n", help="Project name override")
+def init_cmd(name: Optional[str]):
+    """Initialize context tracking (.ctx directory and default config)."""
+    root = Path.cwd().resolve()
+    proj_name = name or root.name
+    proj_type, _ = detect_project_type(root)
+
+    ctx_dir, config = init_ctx_dir(project_name=proj_name, project_type=proj_type, root=root)
+    console.print(f"[bold green]✓[/bold green] Context tracking initialized in [bold]{root}[/bold]")
+    console.print(f"  Project: [cyan]{proj_name}[/cyan] ({proj_type})")
+    console.print(f"  Config: [dim]{ctx_dir / 'config.json'}[/dim]")
+    console.print(f"  Log:    [dim]{ctx_dir / 'progress.md'}[/dim]")
+
+
+@cli.command("log")
+@click.argument("message", required=True)
+def log_cmd(message: str):
+    """Add a progress note to the current session log."""
+    root = find_ctx_root()
+    if not root:
+        console.print("[bold red]Error:[/bold red] .ctx repository not initialized. Run [yellow]ctx init[/yellow] first.")
+        return
+
+    success = log_entry(message, root=root)
+    if success:
+        console.print(f"[bold green]📝 Logged:[/bold green] {message}")
+    else:
+        console.print("[bold red]Failed to write log entry.[/bold red]")
+
+
+@cli.command("status")
+def status_cmd():
+    """Display project context status, git state, and session log summary."""
+    root = find_ctx_root()
+    if not root:
+        console.print("[bold yellow]Notice:[/bold yellow] .ctx repository not initialized in this directory.")
+        return
+
+    config = load_config(root)
+    repo = get_repo(root)
+    branch = get_branch(repo)
+    status = get_git_status(repo)
+    entries = get_entries(root)
+
+    table = Table(title=f"📊 Context Status — {config.get('project_name', root.name)}")
+    table.add_column("Property", style="cyan")
+    table.add_column("Value", style="bold white")
+
+    table.add_row("Root Directory", str(root))
+    table.add_row("Project Type", config.get("project_type", "Unknown"))
+    table.add_row("Git Branch", branch)
+    table.add_row("Staged Files", str(len(status["staged"])))
+    table.add_row("Unstaged Files", str(len(status["unstaged"])))
+    table.add_row("Untracked Files", str(len(status["untracked"])))
+    table.add_row("Logged Entries", str(len(entries)))
+    table.add_row("Template", config.get("template", "generic"))
+
+    console.print(table)
+
+    if entries:
+        console.print("\n[bold]Recent Session Logs:[/bold]")
+        for entry in entries[-5:]:
+            console.print(f"  {entry}")
+
+
+@cli.command("export")
+@click.option("--template", "-t", type=click.Choice(["generic", "cursor", "copilot", "claude", "chatgpt"]), help="AI assistant template preset")
+@click.option("--no-clipboard", is_flag=True, help="Do not copy export to clipboard")
+@click.option("--no-file", is_flag=True, help="Do not save export markdown file")
+@click.option("--stdout", is_flag=True, help="Print exported markdown to stdout")
+def export_cmd(template: Optional[str], no_clipboard: bool, no_file: bool, stdout: bool):
+    """Generate handoff markdown, copy to clipboard, and save snapshot file."""
+    root = find_ctx_root()
+    if not root:
+        # Auto-init if not initialized
+        init_ctx_dir(project_name=Path.cwd().name, project_type=detect_project_type()[0])
+        root = Path.cwd()
+
+    markdown_text, out_file, clipboard_ok = export_context(
+        template_name=template or "generic",
+        root_path=root,
+        save_to_file=not no_file,
+        copy_to_clipboard=not no_clipboard,
+    )
+
+    if stdout:
+        console.print(markdown_text)
+        return
+
+    console.print("\n[bold green]🚀 Context Export Complete![/bold green]\n")
+
+    if not no_clipboard:
+        if clipboard_ok:
+            console.print("  [bold green]📋 Copied to Clipboard![/bold green] Ready to paste into your AI assistant.")
+        else:
+            console.print("  [yellow]⚠️ Could not access system clipboard. Export was generated below.[/yellow]")
+
+    if out_file and not no_file:
+        console.print(f"  [bold blue]💾 Snapshot Saved:[/bold blue] [dim]{out_file}[/dim]")
+
+    console.print("\n[dim]Tip: Open your new AI chat window and press Ctrl+V / Cmd+V to paste handoff context.[/dim]")
+
+
+@cli.command("reset")
+@click.confirmation_option(prompt="Are you sure you want to clear current session logs?")
+def reset_cmd():
+    """Reset session progress log."""
+    root = find_ctx_root()
+    if not root:
+        console.print("[bold red]Error:[/bold red] .ctx repository not initialized.")
+        return
+
+    if reset_session(root):
+        console.print("[bold green]✓ Session progress log reset successfully.[/bold green]")
+    else:
+        console.print("[bold red]Failed to reset session log.[/bold red]")
+
+
+@cli.command("chat")
+@click.option("--goal", "-g", help="Project or task description goal")
+@click.option("--code", "-c", help="Code snippet or context notes")
+@click.option("--task", "-k", help="Next task / where you left off")
+@click.option("--from-clipboard", "-i", is_flag=True, help="Automatically grab raw copied text/code from clipboard")
+@click.option("--template", "-t", type=click.Choice(["generic", "cursor", "copilot", "claude", "chatgpt"]), help="AI assistant template preset")
+@click.option("--stdout", is_flag=True, help="Print handoff directly to stdout without panel")
+def chat_cmd(
+    goal: Optional[str],
+    code: Optional[str],
+    task: Optional[str],
+    from_clipboard: bool,
+    template: Optional[str],
+    stdout: bool,
+):
+    """Format web chat code & notes into a paste-ready AI handoff prompt."""
+    target_template = template or "claude"
+
+    goal_val = goal or ""
+    code_val = code or ""
+    task_val = task or ""
+
+    if from_clipboard:
+        try:
+            cb_content = pyperclip.paste()
+            if cb_content and cb_content.strip():
+                code_val = cb_content.strip()
+                console.print("[bold green]✓ Imported code/text from system clipboard.[/bold green]")
+        except Exception:
+            console.print("[yellow]⚠️ Could not access system clipboard.[/yellow]")
+
+    # Interactive prompt if no inputs given
+    if not goal_val and not code_val and not task_val and not from_clipboard and not stdout:
+        console.print(
+            Panel.fit(
+                "[bold cyan]🌐 Web Chat AI Handoff Builder[/bold cyan]\n"
+                "Build a paste-ready handoff prompt from your web browser chat session.",
+                title="bridge chat",
+            )
+        )
+        goal_val = click.prompt("🎯 What is your project goal / topic?", default="", show_default=False)
+
+        use_cb = click.confirm("📋 Copy code/text from system clipboard?", default=True)
+        if use_cb:
+            try:
+                code_val = pyperclip.paste()
+                if code_val:
+                    console.print("[dim]Imported clipboard text successfully.[/dim]")
+            except Exception:
+                pass
+
+        if not code_val:
+            code_val = click.prompt("💻 Paste latest code snippet or context notes", default="", show_default=False)
+
+        task_val = click.prompt("📍 Next task / Where did you leave off?", default="", show_default=False)
+
+    markdown_text, clipboard_ok = export_chat_context(
+        goal=goal_val,
+        code_or_context=code_val,
+        next_task=task_val,
+        template_name=target_template,
+        copy_to_clipboard=True,
+    )
+
+    if stdout:
+        console.print(markdown_text)
+        return
+
+    console.print("\n[bold green]🚀 Web Chat Handoff Ready![/bold green]\n")
+    if clipboard_ok:
+        console.print("  [bold green]📋 Copied to Clipboard![/bold green] Paste (`Ctrl+V`) into your new AI chat window.")
+    else:
+        console.print("  [yellow]⚠️ Clipboard copy unavailable. Copy the markdown below manually:[/yellow]")
+
+    console.print("\n" + Panel(markdown_text, title="Handoff Prompt Preview", border_style="cyan"))
+

ctx_tool/config.py

@@ -0,0 +1,102 @@
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+CTX_DIR_NAME = ".ctx"
+CONFIG_FILE_NAME = "config.json"
+EXPORTS_DIR_NAME = "exports"
+
+
+def find_ctx_root(start_path: Optional[Path] = None) -> Optional[Path]:
+    """Find the root directory containing .ctx by searching upward."""
+    curr = (start_path or Path.cwd()).resolve()
+    for parent in [curr] + list(curr.parents):
+        if (parent / CTX_DIR_NAME).is_dir():
+            return parent
+    return None
+
+
+def get_ctx_dir(root: Optional[Path] = None) -> Path:
+    """Return .ctx directory path for given root or current working dir."""
+    base = root or find_ctx_root() or Path.cwd()
+    return base / CTX_DIR_NAME
+
+
+def is_initialized(root: Optional[Path] = None) -> bool:
+    """Check if .ctx directory exists in current project."""
+    return get_ctx_dir(root).exists()
+
+
+def init_ctx_dir(project_name: str, project_type: str, root: Optional[Path] = None) -> Tuple[Path, Dict[str, Any]]:
+    """Initialize .ctx directory and default config."""
+    base = root or Path.cwd()
+    ctx_dir = base / CTX_DIR_NAME
+    ctx_dir.mkdir(exist_ok=True)
+
+    exports_dir = ctx_dir / EXPORTS_DIR_NAME
+    exports_dir.mkdir(exist_ok=True)
+
+    config_path = ctx_dir / CONFIG_FILE_NAME
+    default_config: Dict[str, Any] = {
+        "project_name": project_name,
+        "project_type": project_type,
+        "template": "generic",
+        "export_format": "markdown",
+        "max_diff_lines": 300,
+        "max_tree_depth": 4,
+        "ignore_patterns": ["node_modules", ".git", "__pycache__", ".venv", "venv", "dist", "build", ".ctx"],
+    }
+
+    if not config_path.exists():
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(default_config, f, indent=2)
+
+    progress_path = ctx_dir / "progress.md"
+    if not progress_path.exists():
+        with open(progress_path, "w", encoding="utf-8") as f:
+            f.write("# Session Progress Log\n\n")
+
+    # Auto-add .ctx/ to .gitignore to prevent accidental commit of sensitive snapshots
+    gitignore_path = base / ".gitignore"
+    try:
+        if gitignore_path.exists():
+            content = gitignore_path.read_text(encoding="utf-8")
+            if ".ctx" not in content and ".ctx/" not in content:
+                with open(gitignore_path, "a", encoding="utf-8") as f:
+                    if not content.endswith("\n"):
+                        f.write("\n")
+                    f.write("\n# AI Context Handoff snapshot directory\n.ctx/\n")
+        else:
+            with open(gitignore_path, "w", encoding="utf-8") as f:
+                f.write("# AI Context Handoff snapshot directory\n.ctx/\n")
+    except Exception:
+        pass
+
+    return ctx_dir, default_config
+
+
+def load_config(root: Optional[Path] = None) -> Dict[str, Any]:
+    """Load config from .ctx/config.json."""
+    ctx_dir = get_ctx_dir(root)
+    config_path = ctx_dir / CONFIG_FILE_NAME
+    if not config_path.exists():
+        return {}
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def save_config(config: Dict[str, Any], root: Optional[Path] = None) -> bool:
+    """Save config dictionary to .ctx/config.json."""
+    ctx_dir = get_ctx_dir(root)
+    if not ctx_dir.exists():
+        return False
+    config_path = ctx_dir / CONFIG_FILE_NAME
+    try:
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2)
+        return True
+    except Exception:
+        return False

ctx_tool/detector.py

@@ -0,0 +1,113 @@
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def detect_project_type(root_path: Optional[Path] = None) -> Tuple[str, Dict[str, Any]]:
+    """Detect project language, framework, and metadata from root directory."""
+    root = (root_path or Path.cwd()).resolve()
+
+    metadata: Dict[str, Any] = {
+        "language": "Unknown",
+        "framework": "Generic",
+        "key_dependencies": [],
+        "version": "0.1.0",
+    }
+
+    # Python
+    if (root / "pyproject.toml").exists() or (root / "setup.py").exists() or (root / "requirements.txt").exists():
+        metadata["language"] = "Python"
+        deps = []
+        if (root / "requirements.txt").exists():
+            try:
+                content = (root / "requirements.txt").read_text(encoding="utf-8")
+                for line in content.splitlines():
+                    line = line.strip()
+                    if line and not line.startswith("#") and not line.startswith("-"):
+                        pkg = re.split(r"[<>=!~;#]", line)[0].strip()
+                        if pkg:
+                            deps.append(pkg)
+            except Exception:
+                pass
+
+        if (root / "pyproject.toml").exists():
+            try:
+                content = (root / "pyproject.toml").read_text(encoding="utf-8")
+                if "fastapi" in content.lower():
+                    metadata["framework"] = "FastAPI"
+                elif "django" in content.lower():
+                    metadata["framework"] = "Django"
+                elif "flask" in content.lower():
+                    metadata["framework"] = "Flask"
+            except Exception:
+                pass
+
+        metadata["key_dependencies"] = deps[:10]
+        return "Python", metadata
+
+    # Node.js / JavaScript / TypeScript
+    if (root / "package.json").exists():
+        try:
+            pkg_data = json.loads((root / "package.json").read_text(encoding="utf-8"))
+            is_ts = (root / "tsconfig.json").exists()
+            metadata["language"] = "TypeScript" if is_ts else "JavaScript"
+
+            all_deps = {
+                **pkg_data.get("dependencies", {}),
+                **pkg_data.get("devDependencies", {}),
+            }
+
+            if "next" in all_deps:
+                metadata["framework"] = "Next.js"
+            elif "react" in all_deps:
+                metadata["framework"] = "React"
+            elif "vue" in all_deps:
+                metadata["framework"] = "Vue"
+            elif "express" in all_deps:
+                metadata["framework"] = "Express"
+            elif "@nestjs/core" in all_deps:
+                metadata["framework"] = "NestJS"
+
+            metadata["key_dependencies"] = list(all_deps.keys())[:10]
+            metadata["version"] = pkg_data.get("version", "0.1.0")
+        except Exception:
+            metadata["language"] = "JavaScript/TypeScript"
+
+        return metadata["language"], metadata
+
+    # Rust
+    if (root / "Cargo.toml").exists():
+        metadata["language"] = "Rust"
+        metadata["framework"] = "Cargo Project"
+        return "Rust", metadata
+
+    # Go
+    if (root / "go.mod").exists():
+        metadata["language"] = "Go"
+        metadata["framework"] = "Go Module"
+        return "Go", metadata
+
+    # Java / Kotlin
+    if (root / "pom.xml").exists() or (root / "build.gradle").exists() or (root / "build.gradle.kts").exists():
+        metadata["language"] = "Java/Kotlin"
+        metadata["framework"] = "Maven/Gradle"
+        return "Java/Kotlin", metadata
+
+    # C# / .NET
+    if list(root.glob("*.csproj")) or list(root.glob("*.sln")):
+        metadata["language"] = "C#"
+        metadata["framework"] = ".NET Project"
+        return "C#", metadata
+
+    # Ruby
+    if (root / "Gemfile").exists():
+        metadata["language"] = "Ruby"
+        return "Ruby", metadata
+
+    # PHP
+    if (root / "composer.json").exists():
+        metadata["language"] = "PHP"
+        return "PHP", metadata
+
+    return "Generic", metadata

ctx_tool/exporter.py

@@ -0,0 +1,176 @@
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+import pyperclip
+
+from ctx_tool.config import find_ctx_root, get_ctx_dir, load_config
+from ctx_tool.detector import detect_project_type
+from ctx_tool.git_utils import get_branch, get_git_diff, get_git_status, get_recent_commits, get_repo
+from ctx_tool.session import get_entries
+from ctx_tool.templates import get_template_preamble
+from ctx_tool.tree import generate_tree
+
+
+def export_context(
+    template_name: str = "generic",
+    root_path: Optional[Path] = None,
+    save_to_file: bool = True,
+    copy_to_clipboard: bool = True,
+) -> Tuple[str, Optional[Path], bool]:
+    """Generate handoff markdown snapshot, optionally save file and copy to clipboard.
+
+    Returns:
+        (markdown_text, output_file_path, clipboard_success_boolean)
+    """
+    root = find_ctx_root(root_path) or Path.cwd()
+    config = load_config(root)
+
+    proj_name = config.get("project_name", root.name)
+    proj_type, meta = detect_project_type(root)
+    template_key = template_name or config.get("template", "generic")
+
+    repo = get_repo(root)
+    branch = get_branch(repo)
+    commits = get_recent_commits(repo, limit=5)
+    git_status = get_git_status(repo)
+    diff_text = get_git_diff(repo, max_lines=config.get("max_diff_lines", 300))
+
+    modified_files = set(git_status["staged"] + git_status["unstaged"])
+    tree_text = generate_tree(
+        root_path=root,
+        max_depth=config.get("max_tree_depth", 4),
+        ignore_patterns=config.get("ignore_patterns", None),
+        modified_files=modified_files,
+    )
+
+    log_entries = get_entries(root)
+    preamble = get_template_preamble(template_key)
+
+    now_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    # Build Markdown
+    parts = []
+    parts.append(f"# 🔄 Context Handoff — {proj_name}\n")
+    parts.append(f"> **Generated at**: {now_str}\n")
+    parts.append(f"> {preamble}\n")
+
+    # Session Progress
+    parts.append("## 📋 Session Progress Log")
+    if log_entries:
+        for entry in log_entries:
+            parts.append(entry)
+    else:
+        parts.append("*No progress entries recorded for this session yet. (Use `ctx log \"...\"` to add notes)*")
+    parts.append("")
+
+    # Git State
+    parts.append("## 🌿 Git State")
+    parts.append(f"- **Branch**: `{branch}`")
+    if git_status["staged"]:
+        parts.append(f"- **Staged Files**: {', '.join(f'`{f}`' for f in git_status['staged'][:5])}")
+    if git_status["unstaged"]:
+        parts.append(f"- **Unstaged Files**: {', '.join(f'`{f}`' for f in git_status['unstaged'][:5])}")
+    if git_status["untracked"]:
+        parts.append(f"- **Untracked Files**: {', '.join(f'`{f}`' for f in git_status['untracked'][:5])}")
+
+    if commits:
+        parts.append("\n**Recent Commits**:")
+        for c in commits:
+            parts.append(f"- `{c['hexsha']}` — {c['message']}")
+    parts.append("")
+
+    # Git Diff
+    parts.append("## 📝 Code Changes (git diff)")
+    parts.append("```diff")
+    parts.append(diff_text)
+    parts.append("```\n")
+
+    # File Tree
+    parts.append("## 📁 Project Structure (`*` = modified)")
+    parts.append("```")
+    parts.append(tree_text)
+    parts.append("```\n")
+
+    # Metadata
+    parts.append("## 🔧 Project Info")
+    parts.append(f"- **Type**: {proj_type}")
+    if meta.get("framework") != "Generic":
+        parts.append(f"- **Framework**: {meta.get('framework')}")
+    if meta.get("key_dependencies"):
+        parts.append(f"- **Key Dependencies**: {', '.join(meta['key_dependencies'][:8])}")
+
+    markdown_content = "\n".join(parts)
+
+    # Save to file
+    out_file = None
+    if save_to_file:
+        ctx_dir = get_ctx_dir(root)
+        exports_dir = ctx_dir / "exports"
+        exports_dir.mkdir(exist_ok=True)
+        filename = f"handoff_{datetime.now().strftime('%Y%m%d_%H%M%S')}.md"
+        out_file = exports_dir / filename
+        try:
+            out_file.write_text(markdown_content, encoding="utf-8")
+        except Exception:
+            out_file = None
+
+    # Copy to clipboard
+    clipboard_ok = False
+    if copy_to_clipboard:
+        try:
+            pyperclip.copy(markdown_content)
+            clipboard_ok = True
+        except Exception:
+            clipboard_ok = False
+
+    return markdown_content, out_file, clipboard_ok
+
+
+def export_chat_context(
+    goal: str = "",
+    code_or_context: str = "",
+    next_task: str = "",
+    template_name: str = "generic",
+    copy_to_clipboard: bool = True,
+) -> Tuple[str, bool]:
+    """Generate web chat handoff prompt, formatted for AI assistants.
+
+    Returns:
+        (markdown_text, clipboard_success_boolean)
+    """
+    preamble = get_template_preamble(template_name)
+    now_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    parts = []
+    parts.append("# 🌐 Web Chat Session Handoff\n")
+    parts.append(f"> **Generated at**: {now_str}\n")
+    parts.append(f"> {preamble}\n")
+
+    if goal.strip():
+        parts.append("## 🎯 Project / Task Goal")
+        parts.append(goal.strip())
+        parts.append("")
+
+    if code_or_context.strip():
+        parts.append("## 💻 Context & Code Snapshot")
+        parts.append("```")
+        parts.append(code_or_context.strip())
+        parts.append("```\n")
+
+    if next_task.strip():
+        parts.append("## 📍 Next Task / Where We Left Off")
+        parts.append(next_task.strip())
+        parts.append("")
+
+    markdown_content = "\n".join(parts)
+
+    clipboard_ok = False
+    if copy_to_clipboard:
+        try:
+            pyperclip.copy(markdown_content)
+            clipboard_ok = True
+        except Exception:
+            clipboard_ok = False
+
+    return markdown_content, clipboard_ok
+

ctx_tool/git_utils.py

@@ -0,0 +1,140 @@
+import fnmatch
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import git
+
+SENSITIVE_PATTERNS = [
+    "*.env*",
+    "*.pem",
+    "*.key",
+    "id_rsa*",
+    "id_ed25519*",
+    "*credentials*.json",
+    "*secret*",
+]
+
+
+def is_sensitive_file(filename: str) -> bool:
+    """Check if file matches sensitive pattern list."""
+    name = Path(filename).name.lower()
+    return any(fnmatch.fnmatch(name, pat.lower()) for pat in SENSITIVE_PATTERNS)
+
+
+def get_repo(path: Optional[Path] = None) -> Optional[git.Repo]:
+    """Get GitPython Repo object or None if not a git repo."""
+    try:
+        start_path = path or Path.cwd()
+        return git.Repo(start_path, search_parent_directories=True)
+    except (git.InvalidGitRepositoryError, git.NoSuchPathError):
+        return None
+
+
+def is_git_repo(path: Optional[Path] = None) -> bool:
+    """Check if given path is inside a git repository."""
+    return get_repo(path) is not None
+
+
+def get_branch(repo: Optional[git.Repo]) -> str:
+    """Get active branch name or 'HEAD detached'."""
+    if not repo:
+        return "N/A (Not a git repository)"
+    try:
+        return repo.active_branch.name
+    except TypeError:
+        return "HEAD (detached)"
+    except Exception:
+        return "unknown"
+
+
+def get_git_status(repo: Optional[git.Repo]) -> Dict[str, List[str]]:
+    """Return dictionary of staged, unstaged, untracked, and deleted files."""
+    if not repo:
+        return {"staged": [], "unstaged": [], "untracked": [], "deleted": []}
+
+    staged = []
+    unstaged = []
+    deleted = []
+
+    try:
+        # Diff between HEAD and index (staged)
+        if repo.head.is_valid():
+            staged_diffs = repo.index.diff(repo.head.commit)
+            staged = [d.a_path for d in staged_diffs if d.a_path]
+        else:
+            staged_diffs = repo.index.diff(git.NULL_TREE)
+            staged = [d.a_path for d in staged_diffs if d.a_path]
+
+        # Diff between index and working tree (unstaged)
+        unstaged_diffs = repo.index.diff(None)
+        for d in unstaged_diffs:
+            if d.deleted_file and d.a_path:
+                deleted.append(d.a_path)
+            elif d.a_path:
+                unstaged.append(d.a_path)
+        untracked = list(repo.untracked_files or [])
+    except Exception:
+        pass
+
+    return {
+        "staged": [f for f in set(staged) if not is_sensitive_file(f)],
+        "unstaged": [f for f in set(unstaged) if not is_sensitive_file(f)],
+        "untracked": [f for f in untracked if not is_sensitive_file(f)],
+        "deleted": [f for f in set(deleted) if not is_sensitive_file(f)],
+    }
+
+
+def get_git_diff(repo: Optional[git.Repo], max_lines: int = 300) -> str:
+    """Get working tree git diff (staged + unstaged), truncated if larger than max_lines."""
+    if not repo:
+        return ""
+
+    diff_text = ""
+    try:
+        # Unstaged diff
+        diff_text += repo.git.diff()
+        # Staged diff
+        if repo.head.is_valid():
+            staged_diff = repo.git.diff("--cached")
+            if staged_diff:
+                if diff_text:
+                    diff_text += "\n\n# --- Staged Changes ---\n\n"
+                diff_text += staged_diff
+    except Exception:
+        return ""
+
+    if not diff_text.strip():
+        return "No uncommitted code changes detected."
+
+    lines = diff_text.splitlines()
+    if len(lines) > max_lines:
+        truncated_lines = lines[:max_lines]
+        truncated_lines.append(
+            f"\n... [Diff truncated: {len(lines) - max_lines} more lines omitted for length. Use `git diff` for full diff]"
+        )
+        return "\n".join(truncated_lines)
+
+    return diff_text
+
+
+def get_recent_commits(repo: Optional[git.Repo], limit: int = 5) -> List[Dict[str, str]]:
+    """Return list of recent commit dictionaries."""
+    if not repo:
+        return []
+
+    commits = []
+    try:
+        if not repo.head.is_valid():
+            return []
+        for commit in repo.iter_commits(max_count=limit):
+            commits.append(
+                {
+                    "hexsha": commit.hexsha[:7],
+                    "message": commit.message.split("\n")[0],
+                    "author": str(commit.author),
+                    "committed_date": str(commit.committed_datetime),
+                }
+            )
+    except Exception:
+        pass
+
+    return commits

ctx_tool/session.py

@@ -0,0 +1,59 @@
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+from ctx_tool.config import find_ctx_root, get_ctx_dir
+
+
+def get_progress_file(root: Optional[Path] = None) -> Path:
+    """Get path to .ctx/progress.md."""
+    ctx_dir = get_ctx_dir(root)
+    return ctx_dir / "progress.md"
+
+
+def log_entry(message: str, root: Optional[Path] = None) -> bool:
+    """Append a timestamped log entry to progress.md."""
+    progress_file = get_progress_file(root)
+    if not progress_file.parent.exists():
+        return False
+
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    entry = f"- **[{timestamp}]** {message}\n"
+
+    try:
+        if not progress_file.exists():
+            with open(progress_file, "w", encoding="utf-8") as f:
+                f.write("# Session Progress Log\n\n")
+
+        with open(progress_file, "a", encoding="utf-8") as f:
+            f.write(entry)
+        return True
+    except Exception:
+        return False
+
+
+def get_entries(root: Optional[Path] = None) -> List[str]:
+    """Read all log entries from progress.md."""
+    progress_file = get_progress_file(root)
+    if not progress_file.exists():
+        return []
+
+    try:
+        lines = progress_file.read_text(encoding="utf-8").splitlines()
+        entries = [line.strip() for line in lines if line.strip().startswith("- **[")]
+        return entries
+    except Exception:
+        return []
+
+
+def reset_session(root: Optional[Path] = None) -> bool:
+    """Reset progress.md to clean state."""
+    progress_file = get_progress_file(root)
+    if not progress_file.parent.exists():
+        return False
+
+    try:
+        with open(progress_file, "w", encoding="utf-8") as f:
+            f.write("# Session Progress Log\n\n")
+        return True
+    except Exception:
+        return False

ctx_tool/templates.py

@@ -0,0 +1,20 @@
+from typing import Dict
+
+TEMPLATES: Dict[str, str] = {
+    "generic": """You are picking up work on this project session. Below is a structured snapshot of the workspace, including progress log, git state, code diffs, and project structure. Read carefully and continue the implementation seamlessly.""",
+    "cursor": """[CURSOR HANDOFF SESSION]
+You are Cursor AI assistant. Resume the active coding task using the project context below. Follow project conventions and build upon the recent uncommitted changes and progress logs.""",
+    "copilot": """[GITHUB COPILOT HANDOFF]
+System Prompt / Context Handoff:
+Use the provided session progress log, git diff, and project tree to continue answering requests and modifying code.""",
+    "claude": """[CLAUDE CODE / CLAUDE SESSION HANDOFF]
+You are Claude assisting in a software development task.
+Below is the current workspace state. Use this information to understand where the task currently stands, what changes were made, and what to work on next.""",
+    "chatgpt": """[CHATGPT CODE SESSION HANDOFF]
+Below is the full development context snapshot (git branch, diffs, progress logs, and directory tree). Please acknowledge receipt and continue assisting with the next step.""",
+}
+
+
+def get_template_preamble(template_name: str) -> str:
+    """Return template preamble string by name or generic default."""
+    return TEMPLATES.get(template_name.lower(), TEMPLATES["generic"])

ctx_tool/tree.py

@@ -0,0 +1,71 @@
+from pathlib import Path
+from typing import List, Optional, Set
+import pathspec
+
+
+def load_gitignore(root: Path) -> Optional[pathspec.PathSpec]:
+    """Load .gitignore file as pathspec matcher."""
+    gitignore_file = root / ".gitignore"
+    if gitignore_file.exists():
+        try:
+            patterns = gitignore_file.read_text(encoding="utf-8").splitlines()
+            return pathspec.PathSpec.from_lines("gitignore", patterns)
+        except Exception:
+            pass
+    return None
+
+
+def generate_tree(
+    root_path: Optional[Path] = None,
+    max_depth: int = 4,
+    ignore_patterns: Optional[List[str]] = None,
+    modified_files: Optional[Set[str]] = None,
+) -> str:
+    """Generate ASCII directory tree representation."""
+    root = (root_path or Path.cwd()).resolve()
+    spec = load_gitignore(root)
+    custom_ignores = set(ignore_patterns or [".git", "__pycache__", ".venv", "venv", "node_modules", ".ctx"])
+    modified = modified_files or set()
+
+    lines = [f"{root.name}/"]
+
+    def _walk(directory: Path, prefix: str = "", depth: int = 1):
+        if depth > max_depth:
+            return
+
+        try:
+            entries = sorted(list(directory.iterdir()), key=lambda x: (not x.is_dir(), x.name.lower()))
+        except PermissionError:
+            return
+
+        filtered_entries = []
+        for entry in entries:
+            name = entry.name
+            if name in custom_ignores:
+                continue
+
+            rel_path_str = str(entry.relative_to(root)).replace("\\", "/")
+            if spec and spec.match_file(rel_path_str):
+                continue
+
+            filtered_entries.append(entry)
+
+        count = len(filtered_entries)
+        for i, entry in enumerate(filtered_entries):
+            is_last = i == (count - 1)
+            connector = "└── " if is_last else "├── "
+            rel_path_str = str(entry.relative_to(root)).replace("\\", "/")
+
+            mod_marker = " *" if rel_path_str in modified else ""
+
+            if entry.is_dir() and not entry.is_symlink():
+                lines.append(f"{prefix}{connector}{entry.name}/{mod_marker}")
+                new_prefix = prefix + ("    " if is_last else "│   ")
+                _walk(entry, new_prefix, depth + 1)
+            elif entry.is_dir() and entry.is_symlink():
+                lines.append(f"{prefix}{connector}{entry.name}/ (symlink){mod_marker}")
+            else:
+                lines.append(f"{prefix}{connector}{entry.name}{mod_marker}")
+
+    _walk(root)
+    return "\n".join(lines)