sniptrace 0.1.0

Trim noisy terminal output before it reaches your AI coding agent

sniptrace

Trim noisy terminal output before it reaches your AI coding agent. Save tokens, reduce LLM costs, and keep context windows focused on what matters.

pip install sniptrace

Quick start

Filter a string you already have

from sniptrace import filter_text

raw_output = captured_stderr  # string from your agent's code execution
clean = filter_text(raw_output)
llm.complete(f"Fix this error:\n{clean}")

Run a command and get filtered output

from sniptrace import run

result = run(["pytest", "tests/"])

if not result.ok:
    llm.complete(f"Fix this error:\n{result.output}")
    # result.output has no progress bars, no site-packages frames, no noise

What gets filtered

SnipTrace removes known low-signal output patterns from:

• Python — stdlib/venv traceback frames, pip install chatter
• Node / JS — npm/pnpm/yarn deprecation warnings, progress lines
• Docker — BuildKit step lines, layer pull progress
• pytest / Jest / Vitest — session headers, progress dots, PASSED lines
• Cargo / Gradle / Maven — compile progress, [INFO] lines
• Generic — ANSI escape codes, progress bars, spinner frames, update banners

Lines containing error signals (error, traceback, exception, failed, cannot, etc.) are always preserved, even if they match a strip pattern.

API

filter_text(text: str) -> str

Filter an already-captured string. No CLI required — all filtering is pure Python.

from sniptrace import filter_text

clean = filter_text(raw_stderr)

run(command, *, cwd=None, env=None, timeout=None) -> SnipResult

Run a command and return filtered output. Uses the sniptrace CLI if installed (preserves telemetry), otherwise filters natively in Python.

from sniptrace import run

result = run(["pytest", "-q", "tests/"])
print(result.output)        # filtered output
print(result.ok)            # True if exit code was 0
print(result.reduction_pct) # e.g. 87.3
print(result.bytes_saved)   # original_bytes - filtered_bytes

SnipResult

@dataclass
class SnipResult:
    exit_code: int
    output: str
    original_bytes: int
    filtered_bytes: int
    reduction_pct: float
    filtered: bool      # False if filtering was skipped

    @property
    def ok(self) -> bool: ...         # exit_code == 0
    @property
    def bytes_saved(self) -> int: ... # original_bytes - filtered_bytes

is_available() -> bool

Returns True if the sniptrace CLI is installed on PATH.

Typical agent loop

from sniptrace import run

def agent_loop(task: str, llm, max_rounds: int = 5):
    code = llm.complete(f"Write Python code to: {task}")
    
    for _ in range(max_rounds):
        write_to_disk(code)
        result = run(["python", "solution.py"])
        
        if result.ok:
            return code  # done
        
        code = llm.complete(
            f"The code produced this error:\n{result.output}\n\nFix it."
        )
    
    return code

Zero dependencies

The package uses only the Python standard library. No external packages required.

Install the CLI (optional)

The CLI is optional — filter_text() and run() both work without it. The CLI adds telemetry (token savings counter) and shell wrappers for automatic filtering in your terminal.

curl -fsSL https://sniptrace.com/install.sh | sh

Links

• Website
• Documentation
• Live token savings counter