🌉 PathBridge

🌉 PathBridge

Universal Path Translator - One path to rule them all!

Seamlessly convert paths between Windows, WSL, and Unix formats. Never manually translate D:\BEACON_HQ to /mnt/d/BEACON_HQ again!

📖 Table of Contents

The Problem
The Solution
Features
Quick Start
Installation
Usage
- CLI Usage
- Python API
Real-World Examples
How It Works
Configuration
Integration
Troubleshooting
Contributing
Credits

🚨 The Problem

When working across Windows, WSL, and Unix environments, path format mismatches are a daily frustration:

Pain Points

Scenario	What Happens
Copy path from Windows Explorer	Paste in WSL terminal → Doesn't work!
Config files for cross-platform tools	Need different paths for different agents
Share file paths in team chat	Recipient on different OS can't use them
Manual path conversion	Tedious, error-prone, wastes time

Real Examples

# Windows path - won't work in WSL
D:\BEACON_HQ\MEMORY_CORE_V2\file.txt

# WSL path - won't work in Windows
/mnt/d/BEACON_HQ/MEMORY_CORE_V2/file.txt

# How many times have you manually converted these?

Time wasted: 2-5 minutes per session on manual path conversion
Frequency: Multiple times per day
Affected: ALL team members working cross-platform

💡 The Solution

PathBridge automatically detects path format and converts to the target format with a single command:

# Windows → WSL (auto-detected)
pathbridge "D:\BEACON_HQ\file.txt"
# Output: /mnt/d/BEACON_HQ/file.txt

# WSL → Windows (auto-detected)
pathbridge "/mnt/d/BEACON_HQ/file.txt"
# Output: D:\BEACON_HQ\file.txt

# That's it! No manual conversion needed.

Why PathBridge is Badass

Feature	Benefit
Auto-detection	Just paste the path - PathBridge figures out the format
Zero dependencies	Works with Python stdlib only
Clipboard integration	Convert clipboard contents with `--clipboard`
Batch mode	Pipe multiple paths via stdin
Python API	Integrate into your own tools
Cross-platform	Works on Windows, Linux, macOS

✨ Features

Core Features

🔍 Auto-detect path format (Windows, WSL, Unix)
🔄 Smart conversion (converts to opposite format by default)
🎯 Target format override (--to wsl, --to win, --to unix)
📋 Clipboard integration (read/write with --clipboard)
📊 Path info (show all format variations with --info)
🔢 Batch mode (process multiple paths via stdin)

Technical Features

⚡ Zero dependencies - Pure Python stdlib
🐍 Python API - Import and use in your code
🔧 Custom mappings - Define custom drive letter mappings
🖥️ Cross-platform - Windows, Linux, macOS
📏 Edge case handling - Spaces, special chars, relative paths

Supported Path Formats

Format	Example	Detection Pattern
Windows	`D:\BEACON_HQ\file.txt`	Drive letter followed by `:`
Windows (forward)	`D:/BEACON_HQ/file.txt`	Drive letter with forward slashes
WSL	`/mnt/d/BEACON_HQ/file.txt`	Starts with `/mnt/[a-z]/`
Unix	`/home/user/file.txt`	Starts with `/` (not `/mnt/x/`)
UNC	`\\server\share\file.txt`	Network paths (detected as Windows)

🚀 Quick Start

One-Line Install

# Clone and use immediately
git clone https://github.com/DonkRonk17/PathBridge.git
cd PathBridge
python pathbridge.py "D:\test\path"

First Conversion

# Convert a Windows path to WSL
python pathbridge.py "D:\BEACON_HQ\MEMORY_CORE_V2"
# [OK] windows -> wsl: /mnt/d/BEACON_HQ/MEMORY_CORE_V2

# Convert a WSL path to Windows
python pathbridge.py "/mnt/d/BEACON_HQ/MEMORY_CORE_V2"
# [OK] wsl -> windows: D:\BEACON_HQ\MEMORY_CORE_V2

That's it! PathBridge just works.

📦 Installation

Method 1: Clone Repository (Recommended)

git clone https://github.com/DonkRonk17/PathBridge.git
cd PathBridge

# Run directly
python pathbridge.py --help

# Or create a shell alias
alias pb='python /path/to/PathBridge/pathbridge.py'

Method 2: Copy Single File

PathBridge is a single file with zero dependencies. Just copy pathbridge.py wherever you need it:

# Copy to your scripts directory
cp pathbridge.py ~/scripts/
python ~/scripts/pathbridge.py "D:\test"

Method 3: Add to PATH

# Windows (PowerShell)
Copy-Item pathbridge.py "$env:USERPROFILE\scripts\"
# Add to PATH: $env:USERPROFILE\scripts

# Linux/macOS
cp pathbridge.py ~/.local/bin/pathbridge
chmod +x ~/.local/bin/pathbridge

Method 4: pip install (editable)

cd PathBridge
pip install -e .
pathbridge --help

📖 Usage

CLI Usage

Basic Conversion (Auto-detect)

# Windows → WSL
pathbridge "D:\BEACON_HQ\file.txt"
# [OK] windows -> wsl: /mnt/d/BEACON_HQ/file.txt

# WSL → Windows
pathbridge "/mnt/d/BEACON_HQ/file.txt"
# [OK] wsl -> windows: D:\BEACON_HQ\file.txt

Force Target Format

# Force WSL output
pathbridge --to wsl "D:\BEACON_HQ"
pathbridge -t wsl "D:\BEACON_HQ"

# Force Windows output
pathbridge --to win "/mnt/d/BEACON_HQ"
pathbridge -t windows "/mnt/d/BEACON_HQ"

Clipboard Mode

# Read path from clipboard, convert, copy result back
pathbridge --clipboard

# Shorthand
pathbridge -c

Quiet Mode (Output Only)

# Only output the converted path (for scripting)
pathbridge -q "D:\BEACON_HQ"
# /mnt/d/BEACON_HQ

Path Information

# Show detailed path information
pathbridge --info "D:\BEACON_HQ\file.txt"

# Output:
# [INFO] Path Information
#   Original: D:\BEACON_HQ\file.txt
#   Format:   windows
#   Windows:  D:\BEACON_HQ\file.txt
#   WSL:      /mnt/d/BEACON_HQ/file.txt
#   Status:   [X] Not found

Batch Mode (Pipe)

# Convert multiple paths via stdin
echo -e "D:\\path1\nD:\\path2\nD:\\path3" | pathbridge

# From a file
cat paths.txt | pathbridge -q > converted_paths.txt

Python API

Basic Usage

from pathbridge import PathBridge

pb = PathBridge()

# Auto-convert (Windows → WSL)
result = pb.convert("D:\\BEACON_HQ\\file.txt")
print(result)  # /mnt/d/BEACON_HQ/file.txt

# Auto-convert (WSL → Windows)
result = pb.convert("/mnt/d/BEACON_HQ/file.txt")
print(result)  # D:\BEACON_HQ\file.txt

Specify Target Format

from pathbridge import PathBridge

pb = PathBridge()

# Force WSL output
result = pb.convert("D:\\BEACON_HQ", target="wsl")
print(result)  # /mnt/d/BEACON_HQ

# Force Windows output
result = pb.convert("/mnt/d/BEACON_HQ", target="windows")
print(result)  # D:\BEACON_HQ

Detect Format

from pathbridge import PathBridge

pb = PathBridge()

print(pb.detect_format("D:\\BEACON_HQ"))       # windows
print(pb.detect_format("/mnt/d/BEACON_HQ"))    # wsl
print(pb.detect_format("/home/user"))          # unix

Get Path Info

from pathbridge import PathBridge

pb = PathBridge()

info = pb.get_info("D:\\BEACON_HQ\\file.txt")
print(info)
# {
#     'original': 'D:\\BEACON_HQ\\file.txt',
#     'format': 'windows',
#     'windows': 'D:\\BEACON_HQ\\file.txt',
#     'wsl': '/mnt/d/BEACON_HQ/file.txt',
#     'unix': None,
#     'exists': False
# }

Batch Conversion

from pathbridge import PathBridge

pb = PathBridge()

paths = ["D:\\folder1", "D:\\folder2", "C:\\Users"]
results = pb.convert_batch(paths)
print(results)
# ['/mnt/d/folder1', '/mnt/d/folder2', '/mnt/c/Users']

Custom Mappings

from pathbridge import PathBridge

# Map X: drive to custom mount point
custom = {"X": "/custom/mount"}
pb = PathBridge(custom_mappings=custom)

result = pb.convert("X:\\data\\file.txt")
print(result)  # /custom/mount/data/file.txt

🎯 Real-World Examples

Example 1: TimeSync Configuration Fix

Problem: TimeSync has hardcoded WSL paths that break on Windows.

Solution:

from pathbridge import PathBridge

pb = PathBridge()
config_path = pb.convert("/mnt/d/BEACON_HQ/config.json")
# Returns Windows path on Windows, WSL path on WSL

Example 2: Agent Handoff

Problem: CLIO (WSL) shares a file path with FORGE (Windows) - won't work!

Solution:

# CLIO creates path
clio$ echo "/mnt/d/project/src/main.py" > handoff.txt

# FORGE converts and uses it
forge> pathbridge -q $(cat handoff.txt)
D:\project\src\main.py

Example 3: Quick Clipboard Convert

Problem: Copy path from Windows Explorer, need to use in WSL terminal.

Solution:

# One command!
pathbridge -c
# Reads from clipboard, converts, copies result back

Example 4: Config File Generation

Problem: Generate config that works on both Windows and WSL.

Solution:

from pathbridge import PathBridge
import json

pb = PathBridge()
data_path = "D:\\BEACON_HQ\\data"

config = {
    "windows_path": pb.convert(data_path, target="windows"),
    "wsl_path": pb.convert(data_path, target="wsl"),
}

print(json.dumps(config, indent=2))
# {
#   "windows_path": "D:\\BEACON_HQ\\data",
#   "wsl_path": "/mnt/d/BEACON_HQ/data"
# }

Example 5: Batch File Processing

Problem: Process a list of paths from a log file.

Solution:

# Extract and convert paths from log
grep "ERROR:" server.log | awk '{print $3}' | pathbridge -q > fixed_paths.txt

🔧 How It Works

Path Detection Algorithm

Check for UNC paths (\\server\share) → Windows
Check for drive letter (C:, D:) → Windows
Check for WSL mount (/mnt/[a-z]/) → WSL
Check for Unix root (/...) → Unix
Check for backslashes → Assume Windows
Check for forward slashes → Assume Unix
Otherwise → Unknown

Conversion Logic

Source	Target	Action
Windows	WSL	Replace `X:\` with `/mnt/x/`, convert `\` to `/`
WSL	Windows	Replace `/mnt/x/` with `X:\`, convert `/` to `\`
Windows	Windows	No change
WSL	WSL	No change
Unix	*	Typically no change (pure Unix paths don't map to Windows)

⚙️ Configuration

Custom Drive Mappings

By default, PathBridge maps X: to /mnt/x/. You can customize this:

from pathbridge import PathBridge

# Map network drives or special cases
custom = {
    "N": "/network/share",
    "Z": "/custom/data",
}

pb = PathBridge(custom_mappings=custom)

Shell Alias

Add to your .bashrc, .zshrc, or PowerShell profile:

# Bash/Zsh
alias pb='python /path/to/pathbridge.py'
alias pbc='python /path/to/pathbridge.py --clipboard'

# PowerShell
function pb { python C:\path\to\pathbridge.py $args }
function pbc { python C:\path\to\pathbridge.py --clipboard }

🔗 Integration

With Team Brain Tools

PathBridge integrates seamlessly with the Team Brain ecosystem:

# TimeSync - Fix cross-platform paths
from pathbridge import PathBridge
from timesync import TimeSync

pb = PathBridge()
config_path = pb.convert("/mnt/d/BEACON_HQ/timesync_config.json")
ts = TimeSync(config_path)

# SynapseLink - Share paths in messages
from pathbridge import PathBridge
from synapselink import quick_send

pb = PathBridge()
file_path = pb.convert("D:\\project\\report.pdf", target="wsl")

quick_send(
    "CLIO",
    "Report Ready",
    f"File is at: {file_path}",
    priority="NORMAL"
)

Integration Documentation

For complete integration guides:

INTEGRATION_PLAN.md - Full integration architecture
QUICK_START_GUIDES.md - Agent-specific guides
INTEGRATION_EXAMPLES.md - Copy-paste examples

🔍 Troubleshooting

Common Issues

Path Not Converting

Problem: Path returns unchanged.

Solution: Check the format:

pathbridge --info "your/path/here"
# If format is "unknown", the path doesn't match any known pattern

Clipboard Not Working

Problem: --clipboard fails.

Solution: Depends on platform:

Windows: Requires PowerShell
macOS: Requires pbcopy/pbpaste
Linux: Requires xclip or xsel

# Linux: Install xclip
sudo apt install xclip

Special Characters

Problem: Paths with spaces or special characters fail.

Solution: Quote the path:

pathbridge "D:\My Documents\My File (1).txt"

UNC Paths

Problem: Network paths (\\server\share) don't convert.

Solution: UNC paths are Windows-specific and don't have a direct WSL equivalent. PathBridge detects them as Windows format but cannot convert them to WSL.

🛠️ CLI Reference

usage: pathbridge [-h] [--to {windows,win,wsl,unix}] [--clipboard] [--info]
                  [--quiet] [--version]
                  [path]

PathBridge - Universal Path Translator. One path to rule them all!

positional arguments:
  path                  Path to convert (or use --clipboard, or pipe via stdin)

options:
  -h, --help            show this help message and exit
  --to {windows,win,wsl,unix}, -t {windows,win,wsl,unix}
                        Target format (windows/win, wsl, unix). Default: auto-detect
  --clipboard, -c       Read path from clipboard and copy result back
  --info, -i            Show detailed information about the path
  --quiet, -q           Only output the converted path (no labels)
  --version, -v         show program's version number and exit

📝 API Reference

PathBridge Class

Method	Description
`__init__(custom_mappings=None)`	Initialize with optional custom drive mappings
`detect_format(path)`	Detect path format: "windows", "wsl", "unix", or "unknown"
`convert(path, target=None)`	Convert path to target format (auto-detects if target is None)
`convert_batch(paths, target=None)`	Convert multiple paths
`get_info(path)`	Get detailed information about a path
`windows_to_wsl(path)`	Convert Windows path to WSL format
`wsl_to_windows(path)`	Convert WSL path to Windows format

Utility Functions

Function	Description
`get_clipboard_content()`	Read content from system clipboard
`set_clipboard_content(content)`	Write content to system clipboard
`normalize_target(target)`	Normalize target format string

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Development Setup

git clone https://github.com/DonkRonk17/PathBridge.git
cd PathBridge
python test_pathbridge.py  # Run tests

Testing Requirements

All tests must pass (53/53 currently)
Add tests for new features
No external dependencies

Code Style

Follow existing code patterns
Add docstrings for public methods
Use type hints
ASCII-only in Python code (no emojis)

Pull Request Process

Fork the repository
Create a feature branch
Write tests for new features
Ensure all tests pass
Submit a pull request

📜 License

MIT License - see LICENSE for details.

📝 Credits

Built by: ATLAS (Team Brain)
For: Logan Smith / Metaphy LLC
Requested by: FORGE (Cursor Orchestrator)
Part of: Beacon HQ / Team Brain Ecosystem
Date: January 23, 2026

Why This Tool Exists

FORGE identified path format mismatches as a daily pain point affecting ALL Team Brain agents:

CLIO (WSL) shares paths with FORGE (Windows) → Won't work
TimeSync has hardcoded paths → Breaks cross-platform
Manual conversion is tedious → Wastes time

PathBridge solves this with a dead-simple approach:

Auto-detect input format
Convert to opposite format
Zero configuration needed

Special Thanks

FORGE for identifying the need and writing the tool request
CLIO for testing on Linux/WSL
Team Brain for the collaborative development model
Logan Smith for the vision of seamless cross-platform tooling

🔗 Resources

GitHub: https://github.com/DonkRonk17/PathBridge
Issues: https://github.com/DonkRonk17/PathBridge/issues
Examples: EXAMPLES.md
Cheat Sheet: CHEAT_SHEET.txt
Integration: INTEGRATION_PLAN.md

PathBridge: One path to rule them all! 🌉

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
branding		branding
.gitignore		.gitignore
CHEAT_SHEET.txt		CHEAT_SHEET.txt
EXAMPLES.md		EXAMPLES.md
INTEGRATION_EXAMPLES.md		INTEGRATION_EXAMPLES.md
INTEGRATION_PLAN.md		INTEGRATION_PLAN.md
LICENSE		LICENSE
QUICK_START_GUIDES.md		QUICK_START_GUIDES.md
README.md		README.md
pathbridge.py		pathbridge.py
requirements.txt		requirements.txt
setup.py		setup.py
test_pathbridge.py		test_pathbridge.py

License

DonkRonk17/PathBridge

Folders and files

Latest commit

History

Repository files navigation

🌉 PathBridge

📖 Table of Contents

🚨 The Problem

Pain Points

Real Examples

💡 The Solution

Why PathBridge is Badass

✨ Features

Core Features

Technical Features

Supported Path Formats

🚀 Quick Start

One-Line Install

First Conversion

📦 Installation

Method 1: Clone Repository (Recommended)

Method 2: Copy Single File

Method 3: Add to PATH

Method 4: pip install (editable)

📖 Usage

CLI Usage

Basic Conversion (Auto-detect)

Force Target Format

Clipboard Mode

Quiet Mode (Output Only)

Path Information

Batch Mode (Pipe)

Python API

Basic Usage

Specify Target Format

Detect Format

Get Path Info

Batch Conversion

Custom Mappings

🎯 Real-World Examples

Example 1: TimeSync Configuration Fix

Example 2: Agent Handoff

Example 3: Quick Clipboard Convert

Example 4: Config File Generation

Example 5: Batch File Processing

🔧 How It Works

Path Detection Algorithm

Conversion Logic

⚙️ Configuration

Custom Drive Mappings

Shell Alias

🔗 Integration

With Team Brain Tools

Integration Documentation

🔍 Troubleshooting

Common Issues

Path Not Converting

Clipboard Not Working

Special Characters

UNC Paths

🛠️ CLI Reference

📝 API Reference

PathBridge Class

Utility Functions

🤝 Contributing

Development Setup

Testing Requirements

Code Style

Pull Request Process

📜 License

📝 Credits

Why This Tool Exists

Special Thanks

🔗 Resources

About

Topics

Resources

License

Uh oh!

Packages