👻 Ghost Protocol

The silent guardian of your AI-assisted workflow

Stop wasting tokens on garbage files.
Stop committing 50MB SQLite databases.
Stop explaining to AI why your project has 847 PNG files.

Installation • Quick Start • Features • Configuration

---

🤔 The Problem

You're vibe-coding with Claude/Cursor/Copilot. Life is good.

Then you notice:

• 💸 Token costs are through the roof
• 🐌 AI responses are slow because context is bloated
• 😱 You accidentally committed a 200MB video file
• 🔄 AI keeps "seeing" your node_modules or __pycache__

Ghost Protocol fixes all of this. Automatically. In the background.

---

✨ Features

Feature	What it does
🚫 Auto-Ignore	Detects heavy files (images, videos, databases) and adds them to .gitignore + .cursorignore
🧹 Self-Cleaning	Removes stale entries when you delete the original files
🛡️ Commit Guard	Blocks git commit if you try to push oversized source files
📊 Live Monitor	Beautiful TUI dashboard showing token count & estimated API cost
⚡ Zero Config	Works out of the box. Sensible defaults.
🔇 Silent	Runs in background. No notifications. No interruptions.

---

📦 Installation

From PyPI (Recommended)

pip install ghost-protocol

After installation, the ghost command will be available globally.

From Source

# Clone the repo
git clone https://github.com/Adrena1ine-ai/Ghost-Protocol.git
cd Ghost-Protocol

# Install in development mode
pip install -e .

---

🚀 Quick Start

Three commands. That's it.

# 1. Install the git hook (one time only)
ghost --install

# 2. Start the guardian daemon (run in background)
ghost --ghost

# 3. (Optional) Open the monitor in another terminal
ghost --monitor

Now forget about it. Ghost Protocol handles the rest.

---

📊 The Monitor

┌──────────────────────────────────────────────────────────────┐
│  👻 Ghost Protocol v2.0.0 | Status: ACTIVE                  │
├─────────────────────────────┬────────────────────────────────┤
│  📊 Project Stats           │  🧠 The Brain                  │
│                             │                                │
│  Total Tokens    1,247,832  │  • Writer: IgnoreManager (DRY) │
│  Files Tracked        342   │  • Scanner: Auto-updating (30s)│
│  Est. Cost ($3/M)  $3.74    │  • Config: Cached & Valid      │
│                             │                                │
│                             │  Press Ctrl+C to exit.         │
└─────────────────────────────┴────────────────────────────────┘

---

⚙️ Configuration

Create ghost_config.json in your project root:

{
  "limits": {
    "max_asset_size_mb": 1.0,
    "max_code_size_mb": 0.5,
    "debounce_seconds": 0.5
  },
  "skip_dirs": ["my_custom_folder", "secrets"],
  "extensions": {
    "garbage": [".custom", ".mybigfile"],
    "code": [".mycode"]
  }
}

Default Settings

Setting	Default	Description
max_asset_size_mb	1.0	Auto-ignore assets larger than this
max_code_size_mb	0.5	Warn/block code files larger than this
debounce_seconds	0.5	Wait time before processing file changes

Pre-configured Skip Directories

venv, .venv, node_modules, __pycache__, .git, 
.idea, .vscode, dist, build, coverage, target...

Pre-configured Garbage Extensions

.log, .sqlite, .db, .zip, .mp4, .mp3, .pdf, 
.png, .jpg, .gif, .exe, .dll, .bin...

---

🏗️ How It Works

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│  Watchdog   │────▶│   Queue     │────▶│  IgnoreManager  │
│  (Events)   │     │  (Debounce) │     │  (Atomic Write) │
└─────────────┘     └─────────────┘     └─────────────────┘
                                               │
                                               ▼
                                        ┌─────────────┐
                                        │ .gitignore  │
                                        │.cursorignore│
                                        └─────────────┘

Key Design Decisions:

• Singleton Config — Thread-safe, cached sets for O(1) lookups
• File Locking — Cross-platform advisory locks (fcntl/msvcrt)
• Atomic Writes — temp file → os.replace() for data integrity
• Fail-Closed — Git hook blocks commit on any error

---

🧑‍💻 For Developers

# Project structure
ghost-protocol/
├── main.py              # Entry point & CLI
├── requirements.txt     # Dependencies
└── src/
    ├── config.py        # Singleton configuration
    ├── core.py          # Logger & console
    ├── utils.py         # Atomic write, file locking
    ├── watcher.py       # File system events → queue
    ├── scanner.py       # Project stats & git integration
    ├── pruner.py        # Cleanup stale ignore entries
    ├── ignore_manager.py # DRY: single source for ignore logic
    └── monitor.py       # Rich TUI dashboard

---

🤝 Contributing

PRs are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

---

🆘 Troubleshooting

Command ghost not found (Windows)

This is a common issue on Windows when Python Scripts folder is not in PATH.

Quick fix - Use Python module instead:

python -m src --install
python -m src --ghost

Permanent fix - Add Scripts to PATH:

1. Find your Scripts folder:

   python -c "import site; import os; print(os.path.join(site.getuserbase(), 'Scripts'))"

2. Add to PATH temporarily:

   $env:Path += ";C:\Users\YourName\AppData\Roaming\Python\Python314\Scripts"

3. Add to PATH permanently:

   • Press Win + R, type sysdm.cpl, press Enter
   • Go to Advanced → Environment Variables
   • Under User variables, find Path → Edit
   • Click New and add the Scripts path
   • Click OK and restart your terminal

Other Issues

• Not a git repo: Make sure you're in a git repository (git init if needed)
• Import errors: Reinstall with pip install --upgrade ghost-protocol

---

📄 License

MIT © 2024 — Do whatever you want with it.

---

Made for vibe coders, by a vibe coder.

Because life's too short to manually edit .gitignore

⭐ Star this repo if Ghost saved your tokens ⭐