@hasna/terminal 0.7.0 → 0.7.1

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug Report
+about: Report a bug in open-terminal
+labels: bug
+---
+
+**Command:**
+`terminal exec "..."`
+
+**Expected:**
+What you expected to happen
+
+**Actual:**
+What actually happened
+
+**Environment:**
+- OS:
+- Node/Bun version:
+- open-terminal version: (`terminal --version`)
+- Provider: Cerebras / Anthropic

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature Request
+about: Suggest a feature for open-terminal
+labels: enhancement
+---
+
+**Use case:**
+What problem does this solve?
+
+**Proposed solution:**
+How should it work?
+
+**Alternatives considered:**
+Other approaches you thought about

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## [0.7.0] - 2026-03-15
+### Added
+- `terminal exec` command — smart execution for AI agents with full pipeline
+- Claude Code PostToolUse hook installer (`t hook install --claude`)
+- Command rewriter (auto-optimizes find, git log, npm ls, ps aux, etc.)
+- Lazy execution for large result sets (>100 lines → count + sample)
+- `--help` and `--version` flags
+
+## [0.6.0] - 2026-03-15
+### Added
+- Noise stripping pipeline (npm fund, progress bars, gyp, blank lines)
+- Fuzzy diff threshold (>80% similarity → diff-only, not just exact match)
+- Progressive disclosure (`expand` MCP tool — summary first, details on demand)
+- `read_symbol` MCP tool (read a function by name, not the whole file — 88% savings)
+
+## [0.5.0] - 2026-03-15
+### Added
+- AI-powered output processor (Cerebras qwen-3-235b summarization)
+- Session file cache with change detection
+- Search overflow guard (auto-truncate + suggest narrower pattern)
+- `symbols` CLI and MCP tool for file structure outline
+- `repo_state` MCP tool (git status + diff + log in one call)
+- `repo` and `symbols` CLI commands
+
+## [0.4.0] - 2026-03-15
+### Added
+- Semantic code search with AST parsing (`search_semantic` MCP tool)
+- Enhanced smart display with ls -la compression and date range collapsing
+### Fixed
+- Use qwen-3-235b exclusively (llama3.1-8b too unreliable)
+- Project context detection in system prompt
+
+## [0.3.0] - 2026-03-15
+### Added
+- SQLite session tracking for all terminal interactions
+- `sessions`, `sessions stats`, `sessions <id>` CLI commands
+- `session_history` MCP tool
+
+## [0.2.0] - 2026-03-15
+### Added
+- Multi-provider support (Cerebras + Anthropic)
+- Structured output parsers (ls, find, git, test, build, npm, errors)
+- Token compression engine with budget mode
+- MCP server with 16+ tools
+- Smart search with auto-filtering and relevance ranking
+- Reusable command recipes with collections and projects
+- Process supervisor for background commands
+- Diff-aware output caching
+- Token economy tracker
+- Session snapshots for agent handoff
+- Smart display (path grouping, node_modules collapse, pattern dedup)
+
+## [0.1.5] - 2026-03-14
+### Added
+- Tabs, browse mode, fuzzy history, ghost text, cd awareness
+
+## [0.1.0] - 2026-03-13
+### Added
+- Initial release — natural language terminal with Anthropic

package/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to open-terminal
+
+Thanks for your interest in contributing! open-terminal is an open-source smart terminal wrapper that saves AI agents 73-90% of tokens on terminal output.
+
+## Development Setup
+
+```bash
+git clone https://github.com/hasna/terminal.git
+cd terminal
+npm install
+npm run build    # TypeScript compilation
+bun test         # Run tests
+```
+
+## Architecture
+
+```
+src/
+  cli.tsx              # CLI entry point (TUI + subcommands)
+  ai.ts                # NL translation (Cerebras/Anthropic providers)
+  compression.ts       # Token compression engine
+  noise-filter.ts      # Strip noise (npm fund, progress bars, etc.)
+  command-rewriter.ts   # Auto-optimize commands before execution
+  output-processor.ts  # AI-powered output summarization
+  diff-cache.ts        # Diff-aware output caching
+  smart-display.ts     # Visual output compression for TUI
+  file-cache.ts        # Session file read cache
+  lazy-executor.ts     # Lazy execution for large results
+  expand-store.ts      # Progressive disclosure store
+  economy.ts           # Token savings tracker
+  sessions-db.ts       # SQLite session tracking
+  supervisor.ts        # Background process manager
+  snapshots.ts         # Session state snapshots
+  tree.ts              # Tree compression for file listings
+  mcp/
+    server.ts          # MCP server (20+ tools)
+    install.ts         # MCP installer for Claude/Codex/Gemini
+  providers/
+    base.ts            # LLM provider interface
+    anthropic.ts       # Anthropic provider
+    cerebras.ts        # Cerebras provider (default)
+  parsers/             # Structured output parsers
+  search/              # Smart search (file, content, semantic)
+  recipes/             # Reusable command templates
+```
+
+## How to Contribute
+
+### Adding a new parser
+Parsers detect and structure specific command output types. See `src/parsers/` for examples. Each parser needs:
+- `detect(command, output)` — returns true if this parser can handle the output
+- `parse(command, output)` — returns structured data
+
+### Adding a command rewrite rule
+See `src/command-rewriter.ts`. Add a pattern + rewrite function to the `rules` array.
+
+### Adding an MCP tool
+See `src/mcp/server.ts`. Register with `server.tool(name, description, schema, handler)`.
+
+## Running Tests
+
+```bash
+bun test                    # All tests
+bun test src/parsers/       # Parser tests only
+bun test --coverage         # With coverage
+```
+
+## Commit Convention
+
+We use conventional commits:
+- `feat:` — new feature
+- `fix:` — bug fix
+- `refactor:` — code restructuring
+- `test:` — adding tests
+- `docs:` — documentation
+- `chore:` — maintenance
+
+## License
+
+Apache 2.0 — Copyright 2026 Hasna, Inc.

package/LICENSE

@@ -0,0 +1,190 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Hasna, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,186 +1,244 @@
 # open-terminal
 
-Smart terminal wrapper for AI agents and humans. Speak plain English or let agents execute commands with structured output, token compression, and massive context savings.
+**Your AI agent finally understands terminal output.**
 
-## Why?
+[![npm](https://img.shields.io/npm/v/@hasna/terminal)](https://www.npmjs.com/package/@hasna/terminal)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-78%20passing-brightgreen)]()
 
-AI agents waste tokens on terminal interaction. Every `npm test` dumps hundreds of lines into context. Every `find` returns noise. `open-terminal` sits between callers and the shell, making every interaction dramatically more efficient.
+Smart terminal wrapper that saves AI agents **73-90% of tokens** on command output. Instead of dumping raw bash into context, it compresses, structures, and summarizes intelligently.
 
-**For agents:** MCP server with structured output, token compression, diff-aware caching, smart search, process supervision. Cut token usage 50-90% on verbose commands.
+Also a natural language terminal for humans — type English, get shell commands.
 
-**For humans:** Natural language terminal powered by Cerebras (free, open-source) or Anthropic. Type "count typescript files" instead of `find . -name '*.ts' | wc -l`.
+## The Problem
 
-## Install
-
-```bash
-npm install -g @hasna/terminal
-```
-
-## Quick Start
-
-### For Humans (TUI Mode)
-
-```bash
-# Set your API key (pick one)
-export CEREBRAS_API_KEY=your_key  # free, open-source (default)
-export ANTHROPIC_API_KEY=your_key # Claude
+AI coding agents waste massive tokens on terminal output:
 
-# Launch
-t
 ```
+Agent runs: npm test
+Output: 200 lines of passing tests + 2 failures
+Tokens wasted: ~2,000 (agent only needed the 2 failures)
 
-Type in plain English. The terminal translates, shows you the command, and runs it.
-
-### For AI Agents (MCP Server)
-
-```bash
-# Install for your agent
-t mcp install --claude   # Claude Code
-t mcp install --codex    # OpenAI Codex
-t mcp install --gemini   # Gemini CLI
-t mcp install --all      # All agents
-
-# Or start manually
-t mcp serve
+Agent runs: find . -name "*.ts"
+Output: 500 lines including node_modules
+Tokens wasted: ~4,000 (agent needed ~20 source files)
 ```
 
-## MCP Tools
-
-| Tool | Description | Token Savings |
-|------|-------------|---------------|
-| `execute` | Run command with structured output, compression, or AI summary | 50-90% |
-| `execute_diff` | Run command, return only what changed since last run | 80-95% |
-| `browse` | List files as structured JSON, auto-filter node_modules | 60-80% |
-| `search_files` | Find files by pattern, categorized (source/config/other) | 70-90% |
-| `search_content` | Grep with grouping by file and relevance ranking | 60-80% |
-| `explain_error` | Structured error diagnosis with fix suggestions | N/A |
-| `bg_start` | Start background process with port auto-detection | N/A |
-| `bg_status` | List managed processes with health info | N/A |
-| `bg_wait_port` | Wait for a port to be ready | N/A |
-| `bg_stop` / `bg_logs` | Stop process / get recent output | N/A |
-| `list_recipes` / `run_recipe` / `save_recipe` | Reusable command templates | N/A |
-| `snapshot` | Capture terminal state for agent handoff | N/A |
-| `token_stats` | Token economy dashboard | N/A |
-
-### Example: Structured Output
+**open-terminal fixes this.** Every command goes through a smart pipeline:
 
 ```
-Agent: execute("npm test", {format: "json"})
-
-→ {"passed": 142, "failed": 2, "failures": [{"test": "auth.test.ts:45", "error": "expected 200 got 401"}]}
-  (saved 847 tokens vs raw output)
+Raw output (2,000 tokens)
+  → Noise filter (strip npm fund, progress bars)
+  → Command rewriter (git log → --oneline -20)
+  → AI summarization (Cerebras, $0.001/call)
+  → Structured output (JSON, not text)
+Result: 200 tokens (90% saved)
 ```
 
-### Example: Diff Mode
+## How It Compares
 
-```
-Agent: execute_diff("npm test")  # first run → full output
-Agent: execute_diff("npm test")  # second run → only changes
+| Feature | Raw Bash | RTK | open-terminal |
+|---------|----------|-----|---------------|
+| Output compression | None | Regex stripping | AI-powered summarization |
+| Structured data | No | No | JSON parsers for git, test, build, errors |
+| Diff caching | No | No | Only shows what changed between runs |
+| Command optimization | No | No | Auto-rewrites suboptimal commands |
+| Semantic search | No | No | AST-powered code navigation |
+| Smart display | No | No | Groups paths, collapses patterns |
+| Progressive disclosure | No | No | Summary first, expand on demand |
+| MCP tools | 0 | 0 | 20+ tools |
+| NL terminal | No | No | Speak English, get shell commands |
+| Token tracking | No | No | Full economy dashboard with ROI |
 
-→ {"diffSummary": "+1 new line, -1 removed", "added": ["PASS auth.test.ts:45"], "removed": ["FAIL auth.test.ts:45"], "tokensSaved": 892}
-```
+**RTK compresses. open-terminal comprehends.**
 
-### Example: Smart Search
-
-```
-Agent: search_files("*hooks*")
+## Install
 
-→ {"source": ["src/lib/webhooks.ts", "src/hooks/useAuth.ts"], "filtered": [{"count": 47, "reason": "node_modules"}], "tokensSaved": 312}
+```bash
+npm install -g @hasna/terminal
 ```
 
-## Recipes
+## Quick Start
 
-Reusable command templates with variable substitution:
+### For AI Agents
 
 ```bash
-# Save a recipe
-t recipe add kill-port "lsof -i :{port} -t | xargs kill"
+# Smart execution — the primary interface for agents
+terminal exec "npm test"              # AI-summarized, noise-stripped
+terminal exec "find . -name '*.ts'"   # auto-filtered, lazy if >100 results
+terminal exec "git log"               # auto-rewritten to --oneline -20
+terminal exec "npm ls"                # auto-rewritten to --depth=0
 
-# Run it
-t recipe run kill-port --port=3000
+# Useful CLI commands
+terminal repo                         # git status + diff + log in one call
+terminal symbols src/app.ts           # file outline (functions, classes, exports)
+terminal --help                       # full feature list
+```
 
-# List recipes
-t recipe list
+### For AI Agents (MCP Server)
 
-# Project-scoped recipes
-t project init
-t recipe add dev-start "npm run dev" --project
+```bash
+# Install MCP server for your agent
+terminal mcp install --claude    # Claude Code
+terminal mcp install --codex     # OpenAI Codex
+terminal mcp install --gemini    # Gemini CLI
 
-# Collections
-t collection create docker "Docker commands"
-t recipe add docker-build "docker build -t {tag} ." --collection=docker
+# Or start manually
+terminal mcp serve
 ```
 
-## Token Economy
-
-Track how many tokens you've saved:
+### For Humans (NL Terminal)
 
 ```bash
-t stats
-```
+# Set API key
+export CEREBRAS_API_KEY=your_key   # free, open-source (default)
+# or
+export ANTHROPIC_API_KEY=your_key  # Claude
 
+# Launch
+terminal
+```
+
+Type in plain English: "list all typescript files" → `find . -name '*.ts'`
+
+## Benchmarks
+
+Real commands tested on a TypeScript monorepo:
+
+| Command | Raw Tokens | Compressed | Saved |
+|---------|-----------|------------|-------|
+| `ls -laR src/` (budget 150) | 1,051 | 164 | **84%** |
+| `grep export` (overflow guard) | 3,852 | 764 | **80%** |
+| `find *.png` (smart display) | 800 | 82 | **90%** |
+| `bun test` (2nd run, diff) | 423 | 10 | **98%** |
+| `find . -type f` (AI summary) | 2,017 | 94 | **95%** |
+| `npm install` (structured) | 49 | 9 | **82%** |
+| **Total (10 commands)** | **13,067** | **3,495** | **73%** |
+
+**ROI:** AI summarization costs $0.001 per call (Cerebras). Saves $0.029 in Claude Sonnet tokens. **21x return.**
+
+At scale: 500 commands/day = **$41/month saved** per agent.
+
+## MCP Tools (20+)
+
+### Execution
+| Tool | Description |
+|------|-------------|
+| `execute` | Run command with structured output, compression, or AI summary |
+| `execute_smart` | AI-summarized output with progressive disclosure |
+| `execute_diff` | Only return what changed since last run |
+| `expand` | Retrieve full output from a previous execute_smart call |
+
+### Search
+| Tool | Description |
+|------|-------------|
+| `search_files` | Find files by pattern, auto-filter node_modules |
+| `search_content` | Smart grep with file grouping and overflow guard |
+| `search_semantic` | AST-powered search — find functions/classes by meaning |
+| `read_file` | Cached file reading with offset/limit pagination |
+| `read_symbol` | Read a specific function by name (88% vs whole file) |
+| `symbols` | File structure outline with line numbers |
+| `browse` | Structured directory listing |
+
+### Git & Process Management
+| Tool | Description |
+|------|-------------|
+| `repo_state` | Branch + status + staged/unstaged + recent commits (one call) |
+| `explain_error` | Structured error diagnosis with fix suggestions |
+| `bg_start` / `bg_stop` / `bg_status` | Background process management |
+| `bg_wait_port` / `bg_logs` | Wait for port ready, tail process output |
+
+### Recipes & State
+| Tool | Description |
+|------|-------------|
+| `list_recipes` / `run_recipe` / `save_recipe` | Reusable command templates |
+| `snapshot` | Capture terminal state for agent handoff |
+| `token_stats` | Token savings dashboard |
+| `session_history` | Query past session data |
+
+## Smart Pipeline
+
+Every command through `terminal exec` goes through:
+
+1. **Command Rewriting** — auto-optimizes before execution
+   - `find . | grep -v node_modules` → `find . -not -path '*/node_modules/*'`
+   - `cat file | grep X` → `grep X file`
+   - `git log` → `git log --oneline -20`
+   - `npm ls` → `npm ls --depth=0`
+
+2. **Noise Stripping** — removes zero-value output
+   - npm fund warnings, progress bars, gyp noise, blank line runs
+
+3. **Lazy Execution** — large results return count + sample
+   - `>100 lines → {count: 500, sample: [first 20], categories: {src: 300, test: 150}}`
+
+4. **AI Summarization** — Cerebras qwen-3-235b ($0.001/call)
+   - Keeps: errors, failures, warnings, key results
+   - Drops: passing tests, verbose logs, progress output
+
+5. **Diff Caching** — identical/similar re-runs return diff only
+   - Exact match: "unchanged" (98% savings)
+   - >80% similar: diff-only format
+
+6. **Structured Parsing** — JSON instead of text
+   - Git status/log, test results, build output, npm install, errors
+
+## CLI Commands
+
+```
+terminal                        Launch NL terminal (TUI)
+terminal exec <command>         Smart execution with full pipeline
+terminal repo                   Git repo state in one call
+terminal symbols <file>         File outline (functions, classes, exports)
+terminal stats                  Token economy dashboard
+terminal sessions               List recent sessions
+terminal sessions stats         Session analytics
+terminal recipe add/list/run    Reusable command recipes
+terminal collection create/list Recipe collections
+terminal snapshot               Terminal state as JSON
+terminal mcp serve              Start MCP server
+terminal mcp install --claude   Install for Claude Code
+terminal --help                 Full help
+terminal --version              Version
 ```
-Token Economy:
-  Total saved:  124.5K
-  By feature:
-    Structured: 45.2K
-    Compressed: 32.1K
-    Diff cache: 28.7K
-    Search:     18.5K
-```
-
-## TUI Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `ctrl+t` | New tab |
-| `tab` | Switch tabs |
-| `ctrl+w` | Close tab |
-| `ctrl+b` | Browse mode (file navigator) |
-| `ctrl+r` | Fuzzy history search |
-| `ctrl+l` | Clear scrollback |
-| `ctrl+c` | Cancel / exit |
-| `?` | Explain command before running |
-| `e` | Edit translated command |
-| `→` | Accept ghost text suggestion |
 
 ## Configuration
 
-Config stored at `~/.terminal/config.json`:
-
-```json
-{
-  "provider": "cerebras",
-  "permissions": {
-    "destructive": true,
-    "network": true,
-    "sudo": false,
-    "install": true,
-    "write_outside_cwd": false
-  }
-}
+```bash
+# API key (pick one)
+export CEREBRAS_API_KEY=your_key   # default, free tier available
+export ANTHROPIC_API_KEY=your_key  # Claude models
 ```
 
+Config at `~/.terminal/config.json`, sessions at `~/.terminal/sessions.db`, recipes at `~/.terminal/recipes.json`.
+
 ## Architecture
 
 ```
-┌──────────────────────────────────────────┐
-│            open-terminal                  │
-│  ┌──────────┐  ┌──────────┐  ┌────────┐ │
-│  │ Human    │  │ MCP      │  │ CLI    │ │
-│  │ TUI      │  │ Server   │  │ Tools  │ │
-│  └────┬─────┘  └────┬─────┘  └───┬────┘ │
-│       └──────────┬───┘────────────┘      │
-│   ┌──────────────────────────────────┐   │
-│   │  Output Intelligence Router      │   │
-│   │  Parsers → Compression → Diff    │   │
-│   └──────────────┬───────────────────┘   │
-│   ┌──────────────────────────────────┐   │
-│   │  Shell (zsh/bash)                │   │
-│   └──────────────────────────────────┘   │
-└──────────────────────────────────────────┘
+┌──────────────────────────────────────────────┐
+│              open-terminal                    │
+│                                              │
+│  ┌────────┐  ┌──────────┐  ┌─────────────┐ │
+│  │ Human  │  │ terminal │  │ MCP Server  │ │
+│  │ TUI    │  │ exec     │  │ (20+ tools) │ │
+│  └───┬────┘  └────┬─────┘  └──────┬──────┘ │
+│      └────────────┼────────────────┘        │
+│                   ▼                          │
+│  ┌──────────────────────────────────────┐   │
+│  │         Smart Pipeline               │   │
+│  │  Rewrite → Noise → Lazy → AI → Diff │   │
+│  └──────────────────┬───────────────────┘   │
+│                     ▼                        │
+│  ┌──────────────────────────────────────┐   │
+│  │  Shell (zsh/bash)                    │   │
+│  └──────────────────────────────────────┘   │
+└──────────────────────────────────────────────┘
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
 ## License
 
-MIT
+Apache 2.0 — Copyright 2026 Hasna, Inc.

package/benchmarks/benchmark.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env bun
+// Reproducible benchmark: measures token savings across real commands
+// Run: bun benchmarks/benchmark.mjs
+
+import { compress, stripAnsi } from "../dist/compression.js";
+import { parseOutput, estimateTokens, tokenSavings } from "../dist/parsers/index.js";
+import { searchContent } from "../dist/search/index.js";
+import { diffOutput, clearDiffCache } from "../dist/diff-cache.js";
+import { smartDisplay } from "../dist/smart-display.js";
+import { stripNoise } from "../dist/noise-filter.js";
+import { rewriteCommand } from "../dist/command-rewriter.js";
+import { execSync } from "child_process";
+
+const cwd = process.cwd();
+const run = (cmd) => { try { return execSync(cmd, { encoding: "utf8", cwd, maxBuffer: 10*1024*1024 }).trim(); } catch(e) { return e.stdout?.trim() ?? ""; } };
+
+let totalRaw = 0, totalSaved = 0;
+const rows = [];
+
+function track(name, rawText, compressedText) {
+  const raw = estimateTokens(rawText);
+  const comp = estimateTokens(compressedText);
+  const saved = Math.max(0, raw - comp);
+  totalRaw += raw;
+  totalSaved += saved;
+  rows.push({ name, raw, comp, saved, pct: raw > 0 ? Math.round(saved/raw*100) : 0 });
+}
+
+console.log("open-terminal benchmark — measuring real token savings\n");
+
+// 1. Noise filter on npm install-like output
+const npmSim = "added 847 packages in 12s\n\n143 packages are looking for funding\n  run `npm fund` for details\n\nfound 0 vulnerabilities\n";
+const npmClean = stripNoise(npmSim).cleaned;
+track("npm install (noise filter)", npmSim, npmClean);
+
+// 2. Command rewriting
+const rwTests = [
+  ["find . -name '*.ts' | grep -v node_modules", "find pipe→filter"],
+  ["cat package.json | grep name", "cat pipe→grep"],
+  ["git log", "git log→oneline"],
+  ["npm ls", "npm ls→depth0"],
+];
+for (const [cmd, label] of rwTests) {
+  const rw = rewriteCommand(cmd);
+  if (rw.changed) {
+    const rawOut = run(cmd) || cmd;
+    const rwOut = run(rw.rewritten) || rw.rewritten;
+    track(`rewrite: ${label}`, rawOut, rwOut);
+  }
+}
+
+// 3. Structured parsing
+const gitStatus = run("git status");
+const gsParsed = parseOutput("git status", gitStatus);
+if (gsParsed) track("git status (structured)", gitStatus, JSON.stringify(gsParsed.data));
+
+const gitLog = run("git log -15");
+const glParsed = parseOutput("git log -15", gitLog);
+if (glParsed) track("git log -15 (structured)", gitLog, JSON.stringify(glParsed.data));
+
+// 4. Token budget compression
+const bigLs = run("ls -laR src/");
+const c1 = compress("ls -laR src/", bigLs, { maxTokens: 150 });
+track("ls -laR src/ (budget 150)", bigLs, c1.content);
+
+// 5. Search overflow guard
+const rawGrep = run("grep -rn export src/ | head -200");
+const search = await searchContent("export", cwd, { maxResults: 10 });
+track("grep export (overflow guard)", rawGrep, JSON.stringify(search));
+
+// 6. Smart display on paths
+const findPng = run("find . -name '*.png' -not -path '*/node_modules/*' 2>/dev/null | head -50");
+if (findPng) {
+  const display = smartDisplay(findPng.split("\n"));
+  track("find *.png (smart display)", findPng, display.join("\n"));
+}
+
+// 7. Diff caching (identical re-run)
+clearDiffCache();
+const testOut = run("bun test 2>&1");
+diffOutput("bun test", cwd, testOut);
+const d2 = diffOutput("bun test", cwd, testOut);
+track("bun test (identical re-run)", testOut, d2.diffSummary);
+
+// 8. Diff caching (fuzzy — simulated 95% similar)
+clearDiffCache();
+const testA = "PASS test1\nPASS test2\nPASS test3\nPASS test4\nPASS test5\nPASS test6\nPASS test7\nPASS test8\nPASS test9\nFAIL test10\nTests: 9 passed, 1 failed";
+const testB = "PASS test1\nPASS test2\nPASS test3\nPASS test4\nPASS test5\nPASS test6\nPASS test7\nPASS test8\nPASS test9\nPASS test10\nTests: 10 passed, 0 failed";
+diffOutput("test", "/tmp", testA);
+const fuzzyDiff = diffOutput("test", "/tmp", testB);
+track("test (fuzzy diff, 1 change)", testA, fuzzyDiff.added.join("\n") + "\n" + fuzzyDiff.removed.join("\n"));
+
+// 9. Budget compression on large ls
+const bigLs2 = run("ls -laR . 2>/dev/null | head -300");
+const c2 = compress("ls -laR .", bigLs2, { maxTokens: 100 });
+track("ls -laR . (budget 100, 300 lines)", bigLs2, c2.content);
+
+// Print results
+console.log("┌─────────────────────────────────────────────┬──────┬──────┬───────┬──────┐");
+console.log("│ Scenario                                    │  Raw │ Comp │ Saved │    % │");
+console.log("├─────────────────────────────────────────────┼──────┼──────┼───────┼──────┤");
+for (const r of rows) {
+  console.log("│ " + r.name.padEnd(43) + " │ " + String(r.raw).padStart(4) + " │ " + String(r.comp).padStart(4) + " │ " + String(r.saved).padStart(5) + " │ " + (r.pct + "%").padStart(4) + " │");
+}
+console.log("├─────────────────────────────────────────────┼──────┼──────┼───────┼──────┤");
+const pct = Math.round(totalSaved/totalRaw*100);
+console.log("│ " + "TOTAL".padEnd(43) + " │ " + String(totalRaw).padStart(4) + " │ " + String(totalRaw-totalSaved).padStart(4) + " │ " + String(totalSaved).padStart(5) + " │ " + (pct + "%").padStart(4) + " │");
+console.log("└─────────────────────────────────────────────┴──────┴──────┴───────┴──────┘");
+
+// Cost analysis
+const sonnetRate = 3.0;
+const cerebrasInputRate = 0.60;
+const savingsUsd = totalSaved * sonnetRate / 1_000_000;
+console.log(`\nAt Claude Sonnet $3/M: ${totalSaved} tokens saved = $${savingsUsd.toFixed(6)}`);
+console.log(`At 500 commands/day: ~$${(savingsUsd * 50).toFixed(2)}/day, $${(savingsUsd * 50 * 30).toFixed(0)}/month saved`);

package/dist/cli.js

@@ -53,18 +53,35 @@ if (args[0] === "--version" || args[0] === "-v") {
 }
 // ── Exec command — smart execution for agents ────────────────────────────────
 if (args[0] === "exec") {
-    const command = args.slice(1).join(" ");
+    // Parse flags: --json, --offset=N, --limit=N, --raw
+    const flags = {};
+    const cmdParts = [];
+    for (const arg of args.slice(1)) {
+        const flagMatch = arg.match(/^--(\w+)(?:=(.+))?$/);
+        if (flagMatch) {
+            flags[flagMatch[1]] = flagMatch[2] ?? "true";
+        }
+        else {
+            cmdParts.push(arg);
+        }
+    }
+    const command = cmdParts.join(" ");
+    const jsonMode = flags.json === "true";
+    const rawMode = flags.raw === "true";
+    const offset = flags.offset ? parseInt(flags.offset) : undefined;
+    const limit = flags.limit ? parseInt(flags.limit) : undefined;
     if (!command) {
-        console.error("Usage: terminal exec <command>");
+        console.error("Usage: terminal exec <command> [--json] [--raw] [--offset=N] [--limit=N]");
         process.exit(1);
     }
     const { execSync } = await import("child_process");
-    const { stripAnsi } = await import("./compression.js");
+    const { compress, stripAnsi } = await import("./compression.js");
     const { stripNoise } = await import("./noise-filter.js");
     const { processOutput, shouldProcess } = await import("./output-processor.js");
     const { rewriteCommand } = await import("./command-rewriter.js");
-    const { shouldBeLazy, toLazy } = await import("./lazy-executor.js");
-    const { estimateTokens } = await import("./parsers/index.js");
+    const { shouldBeLazy, toLazy, getSlice } = await import("./lazy-executor.js");
+    const { parseOutput, estimateTokens } = await import("./parsers/index.js");
+    const { recordSaving, recordUsage } = await import("./economy.js");
     // Rewrite command if possible
     const rw = rewriteCommand(command);
     const actualCmd = rw.changed ? rw.rewritten : command;
@@ -76,20 +93,52 @@ if (args[0] === "exec") {
         const duration = Date.now() - start;
         const clean = stripNoise(stripAnsi(raw)).cleaned;
         const rawTokens = estimateTokens(raw);
-        // Lazy mode for huge output
-        if (shouldBeLazy(clean)) {
+        // Track usage
+        recordUsage(rawTokens);
+        // --raw flag: skip all processing
+        if (rawMode) {
+            console.log(clean);
+            process.exit(0);
+        }
+        // --json flag: always return structured JSON
+        if (jsonMode) {
+            const parsed = parseOutput(actualCmd, clean);
+            if (parsed) {
+                const saved = rawTokens - estimateTokens(JSON.stringify(parsed.data));
+                if (saved > 0)
+                    recordSaving("structured", saved);
+                console.log(JSON.stringify({ exitCode: 0, parser: parsed.parser, data: parsed.data, duration, tokensSaved: Math.max(0, saved) }));
+            }
+            else {
+                const compressed = compress(actualCmd, clean, { format: "json" });
+                console.log(JSON.stringify({ exitCode: 0, output: compressed.content, duration, tokensSaved: compressed.tokensSaved }));
+            }
+            process.exit(0);
+        }
+        // Pagination: --offset + --limit on a previous large result
+        if (offset !== undefined || limit !== undefined) {
+            const slice = getSlice(clean, offset ?? 0, limit ?? 50);
+            console.log(slice.lines.join("\n"));
+            if (slice.hasMore)
+                console.error(`[open-terminal] showing ${slice.lines.length}/${slice.total}, ${slice.total - (offset ?? 0) - slice.lines.length} remaining`);
+            process.exit(0);
+        }
+        // Lazy mode for huge output (threshold 200, skip cat/summary commands)
+        if (shouldBeLazy(clean, actualCmd)) {
             const lazy = toLazy(clean, actualCmd);
             const savedTokens = rawTokens - estimateTokens(JSON.stringify(lazy));
+            if (savedTokens > 0)
+                recordSaving("compressed", savedTokens);
             console.log(JSON.stringify({ ...lazy, duration, tokensSaved: savedTokens }));
             process.exit(0);
         }
-        // AI summary for medium-large output
+        // AI summary for medium-large output (>15 lines)
         if (shouldProcess(clean)) {
             const processed = await processOutput(actualCmd, clean);
             if (processed.aiProcessed && processed.tokensSaved > 30) {
+                recordSaving("compressed", processed.tokensSaved);
                 console.log(processed.summary);
-                const savedTokens = rawTokens - estimateTokens(processed.summary);
-                console.error(`[open-terminal] ${rawTokens} → ${rawTokens - savedTokens} tokens (saved ${savedTokens}, ${Math.round(savedTokens / rawTokens * 100)}%)`);
+                console.error(`[open-terminal] ${rawTokens} → ${rawTokens - processed.tokensSaved} tokens (saved ${processed.tokensSaved}, ${Math.round(processed.tokensSaved / rawTokens * 100)}%)`);
                 process.exit(0);
             }
         }
@@ -97,6 +146,7 @@ if (args[0] === "exec") {
         console.log(clean);
         const savedTokens = rawTokens - estimateTokens(clean);
         if (savedTokens > 10) {
+            recordSaving("compressed", savedTokens);
             console.error(`[open-terminal] saved ${savedTokens} tokens (noise filter)`);
         }
     }

package/dist/lazy-executor.js

@@ -1,9 +1,18 @@
 // Lazy execution — for large result sets, return count + sample + categories
 // instead of full output. Agent requests slices on demand.
 import { dirname } from "path";
-const LAZY_THRESHOLD = 100; // lines before switching to lazy mode
+const LAZY_THRESHOLD = 200; // lines before switching to lazy mode (was 100, too aggressive)
+// Commands where the user explicitly wants full output — never lazify
+const PASSTHROUGH_COMMANDS = [
+    /\bcat\b/, /\bhead\b/, /\btail\b/, /\bbat\b/, /\bless\b/, /\bmore\b/,
+    /\bsummary\b/i, /\bstatus\b/i, /\breport\b/i, /\bstats\b/i,
+    /\bweek\b/i, /\btoday\b/i, /\bdashboard\b/i,
+];
 /** Check if output should use lazy mode */
-export function shouldBeLazy(output) {
+export function shouldBeLazy(output, command) {
+    // Never lazify explicit read commands or summary commands
+    if (command && PASSTHROUGH_COMMANDS.some(p => p.test(command)))
+        return false;
     return output.split("\n").filter(l => l.trim()).length > LAZY_THRESHOLD;
 }
 /** Convert large output to lazy format: count + sample + categories */
@@ -26,7 +35,7 @@ export function toLazy(output, command) {
         count: lines.length,
         sample,
         categories: Object.keys(categories).length > 1 ? categories : undefined,
-        hint: `${lines.length} results. Showing first 20. Use offset/limit to paginate, or narrow your search.`,
+        hint: `${lines.length} results. Showing first 20. Use terminal exec --offset=20 --limit=20 to paginate.`,
     };
 }
 /** Get a slice of output */

package/dist/mcp/server.js

@@ -69,7 +69,7 @@ export function createServer() {
         if (!format || format === "raw") {
             const clean = stripAnsi(output);
             // Lazy mode: if >100 lines, return count + sample instead of full output
-            if (shouldBeLazy(clean)) {
+            if (shouldBeLazy(clean, command)) {
                 const lazy = toLazy(clean, command);
                 const detailKey = storeOutput(command, clean);
                 return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/terminal",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Smart terminal wrapper for AI agents and humans — structured output, token compression, MCP server, natural language",
   "type": "module",
   "bin": {

package/src/cli.tsx

@@ -59,16 +59,33 @@ if (args[0] === "--version" || args[0] === "-v") {
 // ── Exec command — smart execution for agents ────────────────────────────────
 
 if (args[0] === "exec") {
-  const command = args.slice(1).join(" ");
-  if (!command) { console.error("Usage: terminal exec <command>"); process.exit(1); }
+  // Parse flags: --json, --offset=N, --limit=N, --raw
+  const flags: Record<string, string> = {};
+  const cmdParts: string[] = [];
+  for (const arg of args.slice(1)) {
+    const flagMatch = arg.match(/^--(\w+)(?:=(.+))?$/);
+    if (flagMatch) { flags[flagMatch[1]] = flagMatch[2] ?? "true"; }
+    else { cmdParts.push(arg); }
+  }
+  const command = cmdParts.join(" ");
+  const jsonMode = flags.json === "true";
+  const rawMode = flags.raw === "true";
+  const offset = flags.offset ? parseInt(flags.offset) : undefined;
+  const limit = flags.limit ? parseInt(flags.limit) : undefined;
+
+  if (!command) {
+    console.error("Usage: terminal exec <command> [--json] [--raw] [--offset=N] [--limit=N]");
+    process.exit(1);
+  }
 
   const { execSync } = await import("child_process");
-  const { stripAnsi } = await import("./compression.js");
+  const { compress, stripAnsi } = await import("./compression.js");
   const { stripNoise } = await import("./noise-filter.js");
   const { processOutput, shouldProcess } = await import("./output-processor.js");
   const { rewriteCommand } = await import("./command-rewriter.js");
-  const { shouldBeLazy, toLazy } = await import("./lazy-executor.js");
-  const { estimateTokens } = await import("./parsers/index.js");
+  const { shouldBeLazy, toLazy, getSlice } = await import("./lazy-executor.js");
+  const { parseOutput, estimateTokens } = await import("./parsers/index.js");
+  const { recordSaving, recordUsage } = await import("./economy.js");
 
   // Rewrite command if possible
   const rw = rewriteCommand(command);
@@ -82,21 +99,50 @@ if (args[0] === "exec") {
     const clean = stripNoise(stripAnsi(raw)).cleaned;
     const rawTokens = estimateTokens(raw);
 
-    // Lazy mode for huge output
-    if (shouldBeLazy(clean)) {
+    // Track usage
+    recordUsage(rawTokens);
+
+    // --raw flag: skip all processing
+    if (rawMode) { console.log(clean); process.exit(0); }
+
+    // --json flag: always return structured JSON
+    if (jsonMode) {
+      const parsed = parseOutput(actualCmd, clean);
+      if (parsed) {
+        const saved = rawTokens - estimateTokens(JSON.stringify(parsed.data));
+        if (saved > 0) recordSaving("structured", saved);
+        console.log(JSON.stringify({ exitCode: 0, parser: parsed.parser, data: parsed.data, duration, tokensSaved: Math.max(0, saved) }));
+      } else {
+        const compressed = compress(actualCmd, clean, { format: "json" });
+        console.log(JSON.stringify({ exitCode: 0, output: compressed.content, duration, tokensSaved: compressed.tokensSaved }));
+      }
+      process.exit(0);
+    }
+
+    // Pagination: --offset + --limit on a previous large result
+    if (offset !== undefined || limit !== undefined) {
+      const slice = getSlice(clean, offset ?? 0, limit ?? 50);
+      console.log(slice.lines.join("\n"));
+      if (slice.hasMore) console.error(`[open-terminal] showing ${slice.lines.length}/${slice.total}, ${slice.total - (offset ?? 0) - slice.lines.length} remaining`);
+      process.exit(0);
+    }
+
+    // Lazy mode for huge output (threshold 200, skip cat/summary commands)
+    if (shouldBeLazy(clean, actualCmd)) {
       const lazy = toLazy(clean, actualCmd);
       const savedTokens = rawTokens - estimateTokens(JSON.stringify(lazy));
+      if (savedTokens > 0) recordSaving("compressed", savedTokens);
       console.log(JSON.stringify({ ...lazy, duration, tokensSaved: savedTokens }));
       process.exit(0);
     }
 
-    // AI summary for medium-large output
+    // AI summary for medium-large output (>15 lines)
     if (shouldProcess(clean)) {
       const processed = await processOutput(actualCmd, clean);
       if (processed.aiProcessed && processed.tokensSaved > 30) {
+        recordSaving("compressed", processed.tokensSaved);
         console.log(processed.summary);
-        const savedTokens = rawTokens - estimateTokens(processed.summary);
-        console.error(`[open-terminal] ${rawTokens} → ${rawTokens - savedTokens} tokens (saved ${savedTokens}, ${Math.round(savedTokens/rawTokens*100)}%)`);
+        console.error(`[open-terminal] ${rawTokens} → ${rawTokens - processed.tokensSaved} tokens (saved ${processed.tokensSaved}, ${Math.round(processed.tokensSaved/rawTokens*100)}%)`);
         process.exit(0);
       }
     }
@@ -105,6 +151,7 @@ if (args[0] === "exec") {
     console.log(clean);
     const savedTokens = rawTokens - estimateTokens(clean);
     if (savedTokens > 10) {
+      recordSaving("compressed", savedTokens);
       console.error(`[open-terminal] saved ${savedTokens} tokens (noise filter)`);
     }
   } catch (e: any) {

package/src/lazy-executor.ts

@@ -3,7 +3,7 @@
 
 import { dirname } from "path";
 
-const LAZY_THRESHOLD = 100; // lines before switching to lazy mode
+const LAZY_THRESHOLD = 200; // lines before switching to lazy mode (was 100, too aggressive)
 
 export interface LazyResult {
   lazy: true;
@@ -13,8 +13,17 @@ export interface LazyResult {
   hint: string;
 }
 
+// Commands where the user explicitly wants full output — never lazify
+const PASSTHROUGH_COMMANDS = [
+  /\bcat\b/, /\bhead\b/, /\btail\b/, /\bbat\b/, /\bless\b/, /\bmore\b/,
+  /\bsummary\b/i, /\bstatus\b/i, /\breport\b/i, /\bstats\b/i,
+  /\bweek\b/i, /\btoday\b/i, /\bdashboard\b/i,
+];
+
 /** Check if output should use lazy mode */
-export function shouldBeLazy(output: string): boolean {
+export function shouldBeLazy(output: string, command?: string): boolean {
+  // Never lazify explicit read commands or summary commands
+  if (command && PASSTHROUGH_COMMANDS.some(p => p.test(command))) return false;
   return output.split("\n").filter(l => l.trim()).length > LAZY_THRESHOLD;
 }
 
@@ -41,7 +50,7 @@ export function toLazy(output: string, command: string): LazyResult {
     count: lines.length,
     sample,
     categories: Object.keys(categories).length > 1 ? categories : undefined,
-    hint: `${lines.length} results. Showing first 20. Use offset/limit to paginate, or narrow your search.`,
+    hint: `${lines.length} results. Showing first 20. Use terminal exec --offset=20 --limit=20 to paginate.`,
   };
 }
 

package/src/mcp/server.ts

@@ -81,7 +81,7 @@ export function createServer(): McpServer {
       if (!format || format === "raw") {
         const clean = stripAnsi(output);
         // Lazy mode: if >100 lines, return count + sample instead of full output
-        if (shouldBeLazy(clean)) {
+        if (shouldBeLazy(clean, command)) {
           const lazy = toLazy(clean, command);
           const detailKey = storeOutput(command, clean);
           return {