/ 
MCP-Run-0.100
/ mcp-run-compress

NAME

mcp-run-compress - Wrap a shell command through MCP::Run::Compress for LLM-friendly output

VERSION

version 0.100

SYNOPSIS

# One-shot install (Docker, no Perl needed)
docker run --rm -v "$HOME:$HOME" -e HOME="$HOME" \
    raudssus/mcp-run-compress --install-claude

# One-shot install (native Perl)
cpanm MCP::Run
mcp-run-compress --install-claude

# Bypass compression for a single Bash call
no-compress ls -l

DESCRIPTION

Registers a PreToolUse hook on Claude Code's Bash tool that rewrites every command so its output is passed through MCP::Run::Compress. 30+ command-specific filters strip noise (make "Entering directory"), reduce columns (ls -l to type+name), drop progress lines (cpanm, cargo, npm), and cap long output with head+tail. Prefix a command with no-compress to bypass the filter for a single invocation.

NAME

mcp-run-compress - Claude Code PreToolUse hook that compresses Bash output

MODES

Two install modes, selected by the MCP_RUN_COMPRESS_INSTALL_MODE env var:

native (default)

The hook is mcp-run-compress --hook and rewrites commands to mcp-run-compress --b64 <...>. Everything runs in one Perl process.

docker

The hook is docker run --rm -i raudssus/mcp-run-compress --hook and rewrites commands to a host-side shell snippet that runs the original command on the host, captures its output into temp files, and mounts those into a Docker container for compression. The host needs only bash, mktemp, base64, and docker — no Perl.

The shipped Docker image bakes MCP_RUN_COMPRESS_INSTALL_MODE=docker into its runtime ENV, so --install-claude run inside the container produces the Docker-mode hook automatically. Native cpanm installs leave the var unset.

OPTIONS

--install-claude

Patch ~/.claude/settings.json to register the hook (idempotent), and drop a minimal skill under ~/.claude/skills/bash-output-is-compressed-prefix-no-compress-to-bypass/ that tells Claude about the no-compress bypass prefix. The hook command written into settings.json matches the current install mode.

--hook

Claude Code PreToolUse hook entry point. Reads the hook invocation JSON on stdin, emits a response JSON on stdout with an updatedInput that rewrites the Bash command according to the install mode. Background jobs (run_in_background: true) and already-wrapped commands pass through unchanged.

--b64 BASE64

Native-mode executor. Decode the base64 command, run it via MCP::Run::Bash, compress stdout and stderr, emit them with the original exit code.

--filter-files --cmd-b64 BASE64 STDOUT_PATH STDERR_PATH

Docker-mode filter. Read captured stdout and stderr from two files, compress them using the decoded command as context, emit compressed stdout to fd 1 and compressed stderr to fd 2. Invoked by the pipe-through-docker rewrite.

--help

Print a more detailed help message.

ENVIRONMENT

MCP_RUN_COMPRESS_INSTALL_MODE

native (default) or docker. Controls both the hook command written by --install-claude and the rewrite produced by --hook.

MCP_RUN_COMPRESS_IMAGE

Image reference used by the docker-mode hook. Defaults to raudssus/mcp-run-compress:latest. The shipped Docker image pins this to the exact version that built it, so --install-claude from inside the container writes a versioned hook.

SEE ALSO

MCP::Run::Compress, MCP::Run::Bash, mcp-run-bash

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-mcp-run/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.