token-saver: Instructions file for Codex

Working on Token-Saver

Token-Saver is a Python 3.10+ CLI-output compressor, with Claude Code and Antigravity adapters and a Jekyll documentation site. Compression runs locally and deterministically, without an LLM or network call in the compression path.

Read the relevant instructions

This file applies to the repository. A nested AGENTS.md adds guidance for its directory; read it before editing there. CLAUDE.md describes plugin behavior and shell exclusions. Keep those guarantees consistent with code and tests.

Python style

Use the Google Python Style Guide as the review standard; CONTRIBUTING.md documents project tooling and exceptions.

• Format Python to 80 columns. Preserve literal fixture data when wrapping would change its meaning; justify any narrow exception rather than disabling a rule.
• Import modules by absolute package names and qualify their members. Typing symbols from typing, typing_extensions, and collections.abc are exempt.
• Write meaningful Google-style docstrings for public interfaces and nontrivial behavior. Describe relevant Args, Returns/Yields, Raises, and public Attributes; do not mechanically restate signatures or test names.
• Keep comprehensions simple: one for clause and at most one filter. Use loops for nested traversal and preserve processing order.
• Catch specific exceptions. A broad catch requires an explicit isolation boundary or re-raise; record suppressed failures without commands, captured output, secrets, exception text, or traceback locals.
• Include the repository's Apache 2.0 header in Python files. Preserve third-party copyright and license notices, including .pylintrc. Explain unavoidable local suppressions beside the relevant code.

Design and compatibility

• Keep parsing/compression, orchestration, persistence, CLI presentation, and platform integration separate. Prefer small interfaces and injected dependencies where a real boundary exists; avoid abstract wrappers that add no behavior or independent test seam.
• Extend the processor contract for a new command family instead of adding command-specific branches to the engine or platform hooks.
• Preserve public CLI behavior, processor extension points, return shapes, and installed-tree imports during refactors. New src subpackages need explicit packaging and installer coverage; current copying discovers top-level source modules and processor modules.
• Preserve failure details and secret redaction ahead of compression ratios. A redacted result must never be replaced by its unredacted input merely because a size threshold was not met.
• Follow the existing Python 3.10 syntax and standard-library runtime approach. Use explicit UTF-8 for text files and text subprocess output.