🌁 CTX-Bridge (ctx-bridge / bridge)

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

# 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:

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.

# 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.

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.

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.

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.

# 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.

bridge reset

---

📄 Example Export Snapshot Output

Here is what bridge export copies to your clipboard:

# 🔄 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

# Install development dependencies
pip install -e .[dev]

# Run full test suite
python -m pytest tests/ -v

---

👤 Author & Maintainer

Maaz Korejo

• GitHub: @Maazkorejo
• Repository: CTX-Bridge

---

📜 License

Distributed under the MIT License.