Metadata-Version: 2.4
Name: ctx-bridge
Version: 0.1.1
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`)

[![PyPI Version](https://img.shields.io/pypi/v/ctx-bridge.svg)](https://pypi.org/project/ctx-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

### From PyPI (Recommended)

```bash
pip install ctx-bridge
```

### From GitHub Source

```bash
git clone https://github.com/Maazkorejo/CTX-Bridge.git
cd CTX-Bridge
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).
