---
## โจ Features
- **๐ Smart filtering**: Intercepts bash command output and applies targeted filters to strip verbose content
- **๐ Multi-domain rules**: Built-in filters for git, package managers, test runners, and file listing commands
- **๐ Savings tracking**: Records bytes/tokens saved per session with historical reports
- **๐ Discovery mode**: Identifies commands that could benefit from new filter rules
- **๐ฆ Passthrough mode**: One-shot bypass for debugging or when full output is needed
- **โก Zero-config**: Works out of the box with sensible defaults
## ๐ฏ How It Works
The extension hooks into PI's `tool_result` event for bash commands. When a bash command completes, the output is matched against a registry of filter rules. If a rule matches, the output is processed through a configurable pipeline:
1. **stripAnsi** โ Remove ANSI escape sequences
2. **replace** โ Apply regex replacements
3. **matchOutput** โ Return a short message for known patterns (e.g., "All tests passed.")
4. **stripLinesMatching/keepLinesMatching** โ Filter lines by regex
5. **truncateLinesAt** โ Truncate long lines with a marker
6. **headLines/tailLines** โ Keep only head/tail with omission marker
7. **maxLines** โ Hard cap on total lines
8. **onEmpty** โ Fallback message when output is empty after filtering
## ๐ฆ Installation
**From npm:**
```bash
pi install npm:@the-forge-flow/pi-token-saver
```
**From GitHub:**
```bash
pi install git:github.com/MonsieurBarti/pi-token-saver
```
Then reload PI with `/reload`.
## ๐ Usage
### Commands
| Command | Description |
|---|---|
| `/token-saver:gain` | Show savings report โ bytes and estimated tokens saved this session and historically |
| `/token-saver:discover` | Show commands that ran without a filter rule, ranked by average output size |
| `/token-saver:passthrough` | Bypass filtering for the next bash command (one-shot) |
### Built-in Filter Rules
#### Git Commands
| Command | Filter |
|---|---|
| `git status` | Strip "use git..." hint lines |
| `git log` | Keep commit headers, author, date, and message; cap at 80 lines |
| `git diff` | Strip ANSI; cap at 200 lines |
| `git show` | Strip ANSI; cap at 150 lines |
| `git blame` | Truncate lines at 120 chars; cap at 200 lines |
#### Package Managers
| Command | Filter |
|---|---|
| `npm/yarn/pnpm/bun install` | Keep errors, warnings, summary lines; "Install complete." if empty |
| `npm/yarn/pnpm/bun run` | Keep errors, warnings, stack traces; "Script completed." if empty |
| `turbo run` | Keep errors, warnings, cache status; "Turbo run complete." if empty |
#### Test Runners
| Command | Filter |
|---|---|
| `vitest` | "All tests passed." on success; keep failures, errors, stack traces, summary |
| `jest` | "All tests passed." on success; keep failures, errors, stack traces, summary |
| `bun test` | "All tests passed." on success; keep failures, errors, stack traces |
| `tsc` | Keep errors/warnings; "No TypeScript errors." if clean |
#### File Listing
| Command | Filter |
|---|---|
| `ls` | Strip ANSI; cap at 50 lines; "Empty directory." if empty |
| `find` | Strip ANSI; drop permission errors; cap at 100 lines |
## ๐ Project Structure
```
src/
โโโ index.ts # Extension entry point
โโโ pi-hook.ts # tool_result hook registration
โโโ filter-engine/ # Core filtering pipeline
โ โโโ index.ts # FilterEngine, FilterRegistry, pipeline stages
โโโ command-registry/ # Built-in filter rules
โ โโโ git.ts # git status/log/diff/show/blame
โ โโโ package-manager.ts # npm/yarn/pnpm/bun/turbo
โ โโโ test-runner.ts # vitest/jest/bun test/tsc
โ โโโ file-listing.ts # ls/find
โโโ savings-tracker/ # Per-session and historical savings
โโโ gain-command/ # /token-saver:gain
โโโ discover-command/ # /token-saver:discover
โโโ passthrough-mode/ # /token-saver:passthrough
tests/
โโโ unit/ # Unit tests
```
## ๐งช Development
```bash
# Install dependencies
bun install
# Run tests
bun test
# Lint & format
bun run lint
# Type check
bun run typecheck
# Build for publish
bun run build
```
Pre-commit hooks (lefthook) run biome, typecheck, and tests.
Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/) โ enforced by commitlint.
## ๐ค Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing`)
3. Commit with conventional commits (`git commit -m "feat: add something"`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a Pull Request
## ๐ License
MIT ยฉ [MonsieurBarti](https://github.com/MonsieurBarti)
---
