Home

ContextClean Wiki

ContextClean is a local-first context cleaner for AI agents. It turns noisy HTML, CI logs, stack traces, terminal output, and project folders into compact, redacted, token-budgeted context before that context reaches a model.

Use this wiki for operational detail. Use the README when you need the short path to install and try the CLI.

Core Promise

ContextClean should help a developer do three things:

1. Remove obvious context noise without losing the failure or useful content.
2. Fit cleaned output into a known model budget.
3. Keep sensitive project data out of model prompts by default.

The tool is designed to run locally. The CLI does not require an API key, telemetry service, hosted preprocessor, or remote model call.

Primary Commands

Command	Purpose
ctxclean <input>	Clean a file, stdin, or directory using the default pipeline.
ctxclean gha <log>	Clean GitHub Actions and CI-style logs using aggressive log defaults.
ctxclean repo <dir>	Pack repository context while respecting ignore rules and sensitive-path defaults.
ctxclean report <input>	Explain token savings, noise sources, removed sections, and recommended command.
ctxclean mcp	Run a stdio MCP server exposing clean and report tools.
ctxrun <command>	Run a local command and clean output only when the command fails.

When To Use ContextClean

• Before pasting a failing CI log into an AI coding agent.
• Before sending a scraped web page or browser export to a model.
• Before giving an agent a project directory.
• Before asking for help with a stack trace dump.
• Before enforcing a fixed context-window budget.
• Before sharing a local repo snapshot where secrets or generated files may be present.

Page Index

• Installation
• Command Guide
• HTML And Markdown Cleaning
• Log Crushing And ctxrun
• Token Budgets And Reports
• Safety And Privacy
• Integrations
• Benchmarks And Validation
• Troubleshooting
• Roadmap And Contributing

Output Formats

ContextClean supports three output formats:

Format	Best for
text	Plain terminal output, simple copy/paste, scripts.
markdown	Agent prompts, readable cleaned context, reports.
json	Automation, dashboards, tests, metrics extraction.

JSON output is intended to be stable enough for automation. It includes token counts, compression metrics, budget metadata, truncation metadata, removed sections, noise sources, warnings, and cleaned content.

Operating Principles

• Prefer deterministic cleanup over model-based summarization.
• Preserve failure signal before optimizing for maximum compression.
• Redact secrets by default.
• Respect project ignore rules.
• Make truncation explainable.
• Keep benchmark claims tied to fixtures and measured token counts.

Current Status

The V0.1 line includes HTML cleanup, log crushing, token budgets, reports, repository safety defaults, MCP stdio mode, a GitHub Action wrapper, ctxrun, launch benchmarks, and initial Python helper scaffolding.