tidyout-cli 0.1.0__tar.gz

tidyout_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

tidyout_cli-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.eggs/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+env/
+.env
+.pytest_cache/
+.coverage
+htmlcov/
+*.egg
+.DS_Store

tidyout_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing a New Rule
+
+Adding support for a new command is just one file.
+
+## Steps
+
+1. Create `tidyout/rules/<command>.yaml`
+2. Follow the schema below
+3. Add a test in `tests/test_stripper.py`
+4. Open a PR
+
+## YAML Schema
+
+```yaml
+strip:
+  - pattern: "string or regex"
+    type: prefix | contains | exact | regex
+
+keep:
+  - pattern: "string or regex"
+    type: prefix | contains | exact | regex
+```
+
+**`type` options:**
+
+| Type | Behaviour |
+|---|---|
+| `prefix` | `line.startswith(pattern)` |
+| `contains` | `pattern in line` |
+| `exact` | `line == pattern` |
+| `regex` | `re.search(pattern, line)` |
+
+**Evaluation order:** `keep` always wins over `strip`. If a line matches a keep pattern it is always kept, even if it also matches a strip pattern.
+
+## Two-word commands
+
+For commands like `git status` or `docker logs`, name the file using an underscore:
+`git_status.yaml`, `docker_logs.yaml`, `npm_install.yaml`
+
+tidyout automatically tries the two-word key first, then falls back to the single-word key.
+
+## Transform hooks (optional)
+
+If the rule needs to reformat lines rather than just filter them (e.g., shorten a hash, reorder output), add a Python function in `tidyout/stripper.py` and register it in the `TRANSFORMS` dict:
+
+```python
+def transform_mycommand(lines):
+    # lines: filtered output after YAML rules applied
+    # return: final list of lines
+    return [line.upper() for line in lines]
+
+TRANSFORMS = {
+    ...
+    "mycommand": transform_mycommand,
+}
+```
+
+## Example rule
+
+`tidyout/rules/rspec.yaml` — strip passing examples, keep failures and summary:
+
+```yaml
+strip:
+  - pattern: "^  \\."
+    type: regex
+  - pattern: "^$"
+    type: exact
+
+keep:
+  - pattern: "example"
+    type: contains
+  - pattern: "failure"
+    type: contains
+  - pattern: "Failure/Error"
+    type: contains
+  - pattern: "rspec"
+    type: contains
+```

tidyout_cli-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: tidyout-cli
+Version: 0.1.0
+Summary: CLI wrapper that compresses command output for AI agents, reducing token usage by 60-97%
+License: MIT
+Keywords: ai,cli,compression,developer-tools,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tidyout
+
+A CLI wrapper that sits between you (or your AI agent) and the terminal. Prefix any command with `tidy` and tidyout executes it, strips the noise, and returns a compressed version with a token savings summary.
+
+```
+✂️  tidyout: 312 lines → 18 lines | saved ~2376 tokens (94% reduction)
+```
+
+Built for AI coding sessions (Claude Code, Cursor, Copilot) where terminal output burns tokens fast.
+
+## Install
+
+```bash
+pip install tidyout-cli
+```
+
+## Usage
+
+```bash
+tidy pytest tests/
+tidy git status
+tidy git log
+tidy ls -la
+tidy find . -name "*.py"
+tidy docker logs mycontainer
+tidy npm install
+tidy cargo build
+```
+
+Every run ends with a summary line:
+
+```
+✂️  tidyout: {original} lines → {compressed} lines | saved ~{tokens} tokens ({percent}% reduction)
+```
+
+Commands without a matching rule pass through unchanged and still show the summary (0% reduction).
+
+## Supported commands
+
+| Command | What gets stripped | Typical savings |
+|---|---|---|
+| `pytest` | PASSED lines, platform info, separators | ~80% |
+| `git status` | hints, up-to-date messages, blank lines | ~60% |
+| `git log` | Author email, full hashes, blank lines | ~50% |
+| `ls` | permissions, owner, group, timestamp — reformatted to `DIR:name` / `F:name:size` | ~70% |
+| `find` | `.git/`, `node_modules/`, `__pycache__/`, `./` prefix | ~40% |
+| `tree` | entries beyond depth 3, `node_modules`, `.git`, `__pycache__` | ~50% |
+| `pip install` | progress bars, Collecting/Downloading, already-satisfied | ~90% |
+| `npm install` | warn/notice lines, blank lines | ~85% |
+| `docker logs` | health check noise, keeps last 50 lines | ~70% |
+| `docker ps` | header, full IDs, padding — reformatted to `name:status:ports` | ~60% |
+| `jest` | passing test names, keeps failures and summary | ~80% |
+| `make` | Entering/Leaving directory noise | ~40% |
+| `cargo build` | dependency Compiling lines, Downloading | ~75% |
+
+## `tidy init` — inject rules into your AI agent config
+
+Running `tidy init` in your project directory automatically tells your AI agent to always use `tidy`:
+
+```bash
+tidy init
+```
+
+It detects which config file to update:
+
+- `CLAUDE.md` exists → appends tidyout usage rules
+- `.cursorrules` exists → appends tidyout usage rules
+- Neither exists → creates `CLAUDE.md` with the rules
+
+Injected block:
+
+```markdown
+## Token Optimization with tidyout
+Always prefix the following commands with `tidy` when running in terminal:
+pytest, npm test, jest, rspec, git status, git log, ls, find, tree,
+pip install, npm install, docker logs, docker ps, make, cargo build
+This reduces token usage by 60-97% on command outputs.
+```
+
+## Contributing a new rule
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — it's just one YAML file.

tidyout_cli-0.1.0/README.md

@@ -0,0 +1,82 @@
+# tidyout
+
+A CLI wrapper that sits between you (or your AI agent) and the terminal. Prefix any command with `tidy` and tidyout executes it, strips the noise, and returns a compressed version with a token savings summary.
+
+```
+✂️  tidyout: 312 lines → 18 lines | saved ~2376 tokens (94% reduction)
+```
+
+Built for AI coding sessions (Claude Code, Cursor, Copilot) where terminal output burns tokens fast.
+
+## Install
+
+```bash
+pip install tidyout-cli
+```
+
+## Usage
+
+```bash
+tidy pytest tests/
+tidy git status
+tidy git log
+tidy ls -la
+tidy find . -name "*.py"
+tidy docker logs mycontainer
+tidy npm install
+tidy cargo build
+```
+
+Every run ends with a summary line:
+
+```
+✂️  tidyout: {original} lines → {compressed} lines | saved ~{tokens} tokens ({percent}% reduction)
+```
+
+Commands without a matching rule pass through unchanged and still show the summary (0% reduction).
+
+## Supported commands
+
+| Command | What gets stripped | Typical savings |
+|---|---|---|
+| `pytest` | PASSED lines, platform info, separators | ~80% |
+| `git status` | hints, up-to-date messages, blank lines | ~60% |
+| `git log` | Author email, full hashes, blank lines | ~50% |
+| `ls` | permissions, owner, group, timestamp — reformatted to `DIR:name` / `F:name:size` | ~70% |
+| `find` | `.git/`, `node_modules/`, `__pycache__/`, `./` prefix | ~40% |
+| `tree` | entries beyond depth 3, `node_modules`, `.git`, `__pycache__` | ~50% |
+| `pip install` | progress bars, Collecting/Downloading, already-satisfied | ~90% |
+| `npm install` | warn/notice lines, blank lines | ~85% |
+| `docker logs` | health check noise, keeps last 50 lines | ~70% |
+| `docker ps` | header, full IDs, padding — reformatted to `name:status:ports` | ~60% |
+| `jest` | passing test names, keeps failures and summary | ~80% |
+| `make` | Entering/Leaving directory noise | ~40% |
+| `cargo build` | dependency Compiling lines, Downloading | ~75% |
+
+## `tidy init` — inject rules into your AI agent config
+
+Running `tidy init` in your project directory automatically tells your AI agent to always use `tidy`:
+
+```bash
+tidy init
+```
+
+It detects which config file to update:
+
+- `CLAUDE.md` exists → appends tidyout usage rules
+- `.cursorrules` exists → appends tidyout usage rules
+- Neither exists → creates `CLAUDE.md` with the rules
+
+Injected block:
+
+```markdown
+## Token Optimization with tidyout
+Always prefix the following commands with `tidy` when running in terminal:
+pytest, npm test, jest, rspec, git status, git log, ls, find, tree,
+pip install, npm install, docker logs, docker ps, make, cargo build
+This reduces token usage by 60-97% on command outputs.
+```
+
+## Contributing a new rule
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — it's just one YAML file.

tidyout_cli-0.1.0/docs/superpowers/specs/2026-05-12-tidyout-design.md

@@ -0,0 +1,169 @@
+# tidyout — Design Spec
+**Date:** 2026-05-12  
+**Status:** Approved
+
+---
+
+## What It Does
+
+`tidyout` is a Python CLI wrapper that sits between an AI agent (Claude Code, Cursor, etc.) and the terminal. When a command is prefixed with `tidy`, tidyout:
+
+1. Executes the real command and captures stdout + stderr
+2. Looks up a strip/keep rule for the command
+3. Applies the rule to compress the output
+4. Prints the compressed output followed by a token savings summary
+
+Goal: reduce token consumption in AI agent sessions by stripping human-pretty noise and returning machine-readable output.
+
+---
+
+## CLI Usage
+
+```bash
+tidy pytest tests/
+tidy git status
+tidy ls -la
+tidy docker logs mycontainer
+tidy init
+```
+
+Every run ends with:
+```
+✂️  tidyout: {original} lines → {compressed} lines | saved ~{tokens} tokens ({percent}% reduction)
+```
+
+Token estimate: `1 token ≈ 4 characters`. Savings calculated from character count difference.
+
+---
+
+## Architecture
+
+```
+tidy <cmd> [args]
+        │
+        ▼
+   cli.py:main()
+        │
+        ├── cmd == "init" → init_agent.py
+        │
+        └── everything else → runner.py
+                │
+                ▼
+         subprocess (stdout+stderr merged)
+                │
+                ▼
+         stripper.py
+                │
+                ├── loads rules/<cmd>.yaml  (or no rule → pass-through)
+                ├── applies strip/keep logic line-by-line
+                └── computes token savings
+                │
+                ▼
+         print output + ✂️ summary line
+```
+
+**Command detection:**
+- Single-word commands: `tidy pytest tests/` → rule key `pytest`
+- Two-word subcommands: `tidy git status` → rule key `git_status`, `tidy docker logs` → `docker_logs`
+- No matching rule → pass-through: run command, return output as-is, still print summary line (0% reduction)
+
+---
+
+## YAML Rule Schema
+
+Each file in `tidyout/rules/` follows this schema:
+
+```yaml
+strip:
+  - pattern: "regex or string"
+    type: regex | prefix | exact | contains
+
+keep:
+  - pattern: "..."
+    type: regex | prefix | exact | contains
+```
+
+**Evaluation order per line:**
+1. Matches any `keep` pattern → kept (keep always wins)
+2. Matches any `strip` pattern → dropped
+3. Otherwise → kept
+
+**Special transforms** (reformatting, not just filtering) for `ls`, `git_log`, `docker_ps`, `git_status` are implemented as post-processing hooks in `stripper.py`, keyed by command name.
+
+---
+
+## Components
+
+| File | Responsibility |
+|---|---|
+| `cli.py` | Parse `sys.argv`, detect `init`, dispatch to runner or init_agent |
+| `runner.py` | `subprocess.run` with merged stdout+stderr, returns raw output string |
+| `stripper.py` | Load rule YAML, apply strip/keep, run transform hooks, calculate savings |
+| `init_agent.py` | Detect/create CLAUDE.md / .cursorrules, append tidyout usage block |
+| `rules/*.yaml` | One file per command, declarative strip/keep patterns |
+
+---
+
+## Rules Inventory
+
+| Rule file | Command | Typical savings |
+|---|---|---|
+| `pytest.yaml` | `pytest` | ~80% |
+| `git_status.yaml` | `git status` | ~60% |
+| `git_log.yaml` | `git log` | ~50% |
+| `ls.yaml` | `ls` | ~70% |
+| `find.yaml` | `find` | ~40% |
+| `tree.yaml` | `tree` | ~50% |
+| `pip_install.yaml` | `pip install` | ~90% |
+| `npm_install.yaml` | `npm install` | ~85% |
+| `docker_logs.yaml` | `docker logs` | ~70% |
+| `docker_ps.yaml` | `docker ps` | ~60% |
+| `jest.yaml` | `jest` | ~80% |
+| `make.yaml` | `make` | ~40% |
+| `cargo_build.yaml` | `cargo build` | ~75% |
+
+---
+
+## `tidy init` Behavior
+
+- Detects `CLAUDE.md` in CWD → appends tidyout usage block
+- Detects `.cursorrules` in CWD → appends tidyout usage block
+- Neither exists → creates `CLAUDE.md` with the block
+- Prints exactly what action was taken
+
+**Injected block:**
+```markdown
+## Token Optimization with tidyout
+Always prefix the following commands with `tidy` when running in terminal:
+pytest, npm test, jest, rspec, git status, git log, ls, find, tree,
+pip install, npm install, docker logs, docker ps, make, cargo build
+This reduces token usage by 60-97% on command outputs.
+```
+
+---
+
+## Token Savings Calculation
+
+```python
+original_chars = len(original_output)
+compressed_chars = len(compressed_output)
+saved_tokens = (original_chars - compressed_chars) // 4
+percent = int((1 - compressed_chars / original_chars) * 100) if original_chars else 0
+```
+
+`1 token ≈ 4 characters` is the standard cross-industry rule of thumb (from OpenAI tokenizer research, also used by Anthropic). Accurate enough for an estimate.
+
+---
+
+## Testing
+
+- `tests/test_stripper.py` — unit tests per rule: feed known raw output string, assert compressed output matches expected
+- `tests/test_cli.py` — integration tests for `tidy init`: verify file creation/appending with correct content
+
+---
+
+## Packaging & Publishing
+
+- `pyproject.toml`: package `tidyout`, version `0.1.0`, entry point `tidy = tidyout.cli:main`, Python `>=3.9`
+- GitHub Actions workflow at `.github/workflows/publish.yml`: triggers on `v*.*.*` tags, runs tests, builds, publishes to PyPI via `PYPI_API_TOKEN` secret
+- GitHub repo: `sathish-2000/tidyout`

tidyout_cli-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tidyout-cli"
+version = "0.1.0"
+description = "CLI wrapper that compresses command output for AI agents, reducing token usage by 60-97%"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["cli", "ai", "tokens", "compression", "developer-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+tidy = "tidyout.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["tidyout"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tidyout_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,98 @@
+import os
+import pytest
+from pathlib import Path
+
+from tidyout.init_agent import run_init, TIDYOUT_BLOCK
+
+
+def test_init_creates_claude_md_when_neither_exists(tmp_path):
+    orig = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        run_init()
+        claude_md = tmp_path / "CLAUDE.md"
+        assert claude_md.exists()
+        content = claude_md.read_text()
+        assert "tidyout" in content
+        assert "tidy" in content
+    finally:
+        os.chdir(orig)
+
+
+def test_init_appends_to_existing_claude_md(tmp_path):
+    orig = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        claude_md = tmp_path / "CLAUDE.md"
+        claude_md.write_text("# Existing content\n")
+        run_init()
+        content = claude_md.read_text()
+        assert "# Existing content" in content
+        assert "tidyout" in content
+    finally:
+        os.chdir(orig)
+
+
+def test_init_does_not_create_new_claude_md_when_cursorrules_exists(tmp_path):
+    orig = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        cursorrules = tmp_path / ".cursorrules"
+        cursorrules.write_text("# Cursor rules\n")
+        run_init()
+        assert not (tmp_path / "CLAUDE.md").exists()
+        assert "tidyout" in cursorrules.read_text()
+    finally:
+        os.chdir(orig)
+
+
+def test_init_appends_to_cursorrules(tmp_path):
+    orig = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        cursorrules = tmp_path / ".cursorrules"
+        cursorrules.write_text("# Cursor rules\n")
+        run_init()
+        content = cursorrules.read_text()
+        assert "# Cursor rules" in content
+        assert "tidyout" in content
+    finally:
+        os.chdir(orig)
+
+
+def test_init_prefers_claude_md_over_cursorrules(tmp_path):
+    orig = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        claude_md = tmp_path / "CLAUDE.md"
+        cursorrules = tmp_path / ".cursorrules"
+        claude_md.write_text("# Claude\n")
+        cursorrules.write_text("# Cursor\n")
+        run_init()
+        assert "tidyout" in claude_md.read_text()
+        assert "tidyout" not in cursorrules.read_text()
+    finally:
+        os.chdir(orig)
+
+
+def test_init_block_contains_key_commands(tmp_path):
+    orig = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        run_init()
+        content = (tmp_path / "CLAUDE.md").read_text()
+        for cmd in ["pytest", "git status", "git log", "docker logs", "npm install"]:
+            assert cmd in content
+    finally:
+        os.chdir(orig)
+
+
+def test_init_prints_action(tmp_path, capsys):
+    orig = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        run_init()
+        out = capsys.readouterr().out
+        assert "CLAUDE.md" in out
+    finally:
+        os.chdir(orig)