shell-sieve

An MCP server and CLI wrapper that executes shell commands and intelligently compresses, filters, and extracts errors from verbose output to save AI agent context windows.

PyPI version License: MIT MCP Server

🎯 Why?

AI coding agents frequently exhaust their context windows when running verbose commands like npm install or pytest, leading to hallucinations or dropped errors. Existing tools either blindly truncate output (losing the stack trace) or dump everything; Shell Sieve intelligently strips ANSI, collapses repetitive progress lines, and guarantees error extraction.

Target audience: AI agent developers, users of Claude Code/Cursor/Cline, and CLI power users who want clean, actionable command output without the noise.

✨ Features

• ✨ ANSI stripping and smart line collapsing (e.g., progress bars)
• ✨ Error-aware truncation (always keeps the last N lines and any detected stack traces/errors)
• ✨ Native MCP Server implementation for seamless integration with Cursor, Claude Desktop, and Cline

🚀 Quick Start

# Install
pip install shell-sieve

# Run
shell-sieve --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/shell-sieve.git
cd shell-sieve

# 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
shell-sieve --help

# Common usage examples
shell-sieve --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.