<div align="center">

ctxbleach

Local CLI and MCP server that bleaches secrets from logs, files, and diffs before AI agents see them.

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

🎯 Why?

Trending agent-context projects focus on giving agents more code and memory, while guardrail tools mostly block commands. Developers still need a tiny local middleware that transforms raw logs, env files, and command output into safe, token-budgeted context before it reaches an LLM. Existing secret scanners are CI-oriented and do not provide interactive redaction placeholders, MCP tools, or context budgeting.

Target audience: Developers and platform engineers using Claude Code, Cursor, Codex, or MCP-enabled agents who need to share logs, .env files, stack traces, and CI output without leaking credentials.

✨ Features

• ✨ Regex-based redaction for AWS keys, GitHub/Slack tokens, JWTs, bearer headers, URL passwords, private keys, and generic secret assignments
• ✨ Stable placeholders and masked scan output so no secret values are echoed back
• ✨ Token-budgeted truncation with head or tail preservation for large logs
• ✨ CLI commands for scan, redact, and MCP stdio serving
• ✨ Zero-dependency Python implementation that can be dropped into agent workflows

🚀 Quick Start

# Install
pip install ctxbleach

# Run
ctxbleach --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/ctxbleach.git
cd ctxbleach

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

🎬 Demo

The GIF above was recorded using Charm VHS:

vhs < demo.tape

📖 Usage

# Show help
ctxbleach --help

# Common usage examples
ctxbleach --example

🏗️ Architecture

graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]

🤝 Contributing

Contributions are welcome! Please:

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

📄 License

MIT © 2026 — See LICENSE for details.

---

<div align="center">

If this project helped you, please ⭐ star it!

Made with ❤️ and AI

</div>