Squelchy

Keep noisy commands readable while saving every output byte.

5,000 records become 10 report lines, a 99.8% reduction.
_{Method: npm run bench writes 4,999 stdout records and one stderr error, verifies all 98,901 saved bytes, and checks exit 7. This measures the final report, excluding live redraws.}

I prefer a quiet terminal and a complete record.

Install

npm install --global github:Arthur031221/squelchy

Or try it once without a global install:

npm exec --yes --package=github:Arthur031221/squelchy -- squelchy demo

Requires Node.js 20 or newer. This is a GitHub install. The demo deliberately returns status 7. Squelchy is not published to npm.

npm install --global github:Arthur031221/squelchy
squelchy -- node -e "console.log('hello')"

npm install --global github:Arthur031221/squelchy
squelchy -- node -e "console.log('hello')"

Try it

squelchy --lines 8 -- \
  node -e '
for (let i = 0; i < 5000; i++) console.log(i === 4999 ? "error: final check" : "working " + i)
process.exitCode = 7
'

The process runs normally. Squelchy shows a bounded report and returns its exit status. It also prints a private log directory and a command to replay the raw output. Use squelchy raw LOGDIR --stream stdout to recover one stream.

How it works

Squelchy starts the command directly with its argument list. It does not ask a shell to interpret those arguments. Input stays attached to the current terminal. Output is copied byte for byte to separate stdout and stderr files and to a combined file in observed chunk arrival order. The combined file cannot promise the exact chronology between two concurrently written streams.

Choose --lines 6 through --lines 100 for the final report budget. Use --width 40 through --width 240 to clip previews, --plain to disable live redraws, and --log-dir PATH to choose the parent log directory.

On an interactive terminal, a small status view updates every 150 ms. In a pipe or CI job, stdout contains only the final report. Previews discard terminal control sequences, clip long lines, retain a small tail and error ring, and never change the saved log bytes. Line records count LF, CRLF, and standalone CR as one record each. A final unterminated fragment counts as one record and appears in the tail.

Log folders are unique, created with restrictive permissions on POSIX systems, and never overwrite files. Metadata begins as incomplete and is replaced after all output is flushed. A capture error returns status 74 and does not claim the logs are complete. If the destination closes before the final report can be written, Squelchy also returns 74, while completed log files remain recoverable.

Numbers

Run npm run bench to reproduce the local fixture. It emits exactly 5,000 LF records, ends with an error record, exits 7, checks the bounded final report, and compares the recovered stdout and stderr bytes. The measured result is in benchmarks/result.json. These numbers describe the final report only. Live redraw traffic is separate and is not included in the report line count.

Where it fits

Shell

Put squelchy -- before a command when its progress is noisy. The example above uses the same invocation shape and leaves node arguments intact.

CI

Wrap a test or build step with Squelchy and save the printed log directory as a job artifact when later inspection matters. The process exit status still fails the step when the wrapped command fails.

Coding agents

A runner can read the final report first and use the printed squelchy raw command when the error details matter. This is a normal CLI integration. There is no agent-specific protocol or model dependency.

RTK applies command-specific filters for agent workflows. Context-mode manages context and tool results in coding-agent sessions. chronic hides output unless a command fails. squeez compresses terminal streams. Squelchy wraps an arbitrary process, keeps live bounded status, and saves raw streams for replay.

Limits

Squelchy is not a terminal multiplexer. Interactive full-screen programs and programs that require a PTY are unsupported. On Windows, process-group signaling and POSIX file permissions are not available. Interruption targets the direct child and the platform applies its normal file permissions. There is no timeout option. If a child exits while descendants retain its output pipes, Squelchy ends capture after two seconds and marks the logs incomplete. The report has a logical line cap. Very long log paths may wrap in a narrow terminal.

Development

npm test
npm run bench
npm pack --dry-run

See CONTRIBUTING.md for local contribution notes. Squelchy is licensed under MIT.