<p align="center"> <img src="banner.png" alt="Kevin Malone - Why waste time say lot word when few word do trick?" width="600"> </p>

FewWord

"Why waste time say lot word when few word do trick? Big output go file. Small word stay. Context happy. Me happy. Everyone go home by seven."

— Kevin Malone

A Claude Code plugin that automatically offloads large command outputs to files, keeping your context clean and retrievable.

---

The Problem

AI coding agents hit a wall when:

• Tool outputs bloat your context — One big test run or log dump eats 10k tokens that sit there forever
• Plans get lost — After context summarization, Claude forgets what it was doing
• You're paying for waste — Most of your context is irrelevant to the current step

---

The Solution

FewWord implements dynamic context discovery — patterns from Manus and LangChain that use the filesystem as infinite, searchable memory.

Instead of this:

[26,000 tokens of command outputs sitting in context forever]

You get this (~35 tokens):

[fw A1B2C3D4] find e=0 15K 882L | /open A1B2C3D4

For failures, you also get a preview:

[fw E5F6G7H8] pytest e=1 45K 234L | /open E5F6G7H8
FAILED test_auth.py::test_login - AssertionError
FAILED test_api.py::test_endpoint - TimeoutError
2 failed, 48 passed in 12.34s

---

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code Session                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   You: "Run the test suite"                                     │
│                              │                                   │
│                              ▼                                   │
│   ┌──────────────────────────────────────────┐                  │
│   │  PreToolUse Hook Intercepts              │                  │
│   │  ─────────────────────────               │                  │
│   │  Command: pytest                         │                  │
│   │  Output: 45,678 bytes (>8KB threshold)   │                  │
│   └──────────────────────────────────────────┘                  │
│                              │                                   │
│              ┌───────────────┴───────────────┐                  │
│              ▼                               ▼                   │
│   ┌─────────────────────┐      ┌─────────────────────────┐      │
│   │  Write to Disk      │      │  Return to Context      │      │
│   │  ─────────────────  │      │  ────────────────────   │      │
│   │  .fewword/scratch/  │      │  File: pytest_143022.txt│      │
│   │  tool_outputs/      │      │  Size: 45KB, Exit: 1    │      │
│   │  pytest_143022.txt  │      │  === Last 10 lines ===  │      │
│   │                     │      │  FAILED auth_test...    │      │
│   │  [Full 45KB output] │      │  [~200 tokens only]     │      │
│   └─────────────────────┘      └─────────────────────────┘      │
│                                                                  │
│   Later: "What tests failed?"                                   │
│                              │                                   │
│                              ▼                                   │
│   Claude: grep FAILED .fewword/scratch/tool_outputs/pytest.txt  │
│           → Retrieves exactly what's needed                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Result: 45KB output → ~35 tokens in context + full data on disk when needed.

---

Test Results

We ran the same 3 commands (find, ls -la, env) in two fresh Claude Code sessions:

| Metric | WITH Plugin | WITHOUT Plugin | |--------|-------------|----------------| | Message Tokens | 4.7k | 26.0k | | Tokens Saved | 21.3k | — | | Savings | 82% | — |

Understanding the Numbers

When you run /context, you see several categories:

Total Context: 84k tokens (with plugin) vs 105k tokens (without)
├── System prompt:  3.8k  (constant - Claude's instructions)
├── System tools:  15.8k  (constant - built-in tools)
├── MCP tools:     14.7k  (constant - browser automation, etc.)
├── Messages:       4.7k  ← THIS IS WHAT FEWWORD REDUCES (was 26k)
└── Free space:      ...

The 82% savings (21.3k tokens) is specifically on Message tokens — that's where your actual conversation and command outputs live.

---

Installation

Step 1: Add the marketplace

claude plugin marketplace add sheeki03/Few-Word

Step 2: Install the plugin

claude plugin install fewword@sheeki03-Few-Word

Step 3: Start a new session for hooks to load.

That's it! FewWord works automatically — no configuration needed.

<details> <summary><b>Alternative: Install from inside Claude Code</b></summary>

You can also run these commands inside an active Claude session:

/plugin marketplace add sheeki03/Few-Word
/plugin install fewword@sheeki03-Few-Word

Then start a new session.

</details>

---

Updates

FewWord checks for updates automatically on session start. Notifications are rate-limited (at most once every 24 hours).

To update manually:

claude plugin update fewword@sheeki03-Few-Word

Then start a new session for hooks to reload.

Check your version: /version

Disable update checks: export FEWWORD_DISABLE_UPDATE_CHECK=1

---

Commands

| Command | What It Does | |---------|--------------| | /help | Show detailed help and how the plugin works | | /stats | Show session statistics and estimated token savings | | /version | Show installed version and update command | | /open <id> | Retrieve an offloaded output by ID | | /recent | Show recent offloaded outputs (recovery after compaction) | | /pin <id> | Pin an output to prevent auto-cleanup | | /init | Set up FewWord directory structure | | /cleanup | See storage stats, clean old files | | /search <term> | Search through all offloaded context | | /save <content> | Manually save content to FewWord storage | | /export | Export session history as markdown report |

---

What It Does

Automatic Behaviors

| Feature | What Happens | |---------|--------------| | Tiered Offloading | < 512B: inline. 512B-4KB: compact pointer (~35 tokens). > 4KB: pointer + preview (failures only). | | Smart Retention | Exit 0 (success) → 24h retention. Exit != 0 (failure) → 48h retention. LRU eviction at 250MB. | | LATEST Aliases | LATEST.txt and LATEST_{cmd}.txt symlinks for quick retrieval | | Session Tracking | Per-session stats for /stats | | Plan Persistence | Active plan in .fewword/index/current_plan.yaml, auto-archived on completion |

Hook Events

| Event | Action | |-------|--------| | SessionStart | Creates directories, runs smart cleanup (TTL + LRU), shows inventory, updates .gitignore | | PreToolUse | Intercepts Bash commands, wraps large outputs, writes manifest, creates LATEST aliases | | SessionEnd | Archives completed plans | | Stop | Warns if scratch storage exceeds 100MB |

---

Directory Structure

your-project/
└── .fewword/
    ├── scratch/                     # Ephemeral (auto-cleaned by TTL + LRU)
    │   ├── tool_outputs/            # Command outputs (24h success, 48h failure)
    │   │   ├── LATEST.txt           # Symlink to most recent output
    │   │   ├── LATEST_{cmd}.txt     # Symlink to most recent per command
    │   │   └── {cmd}_{ts}_{id}_exit{code}.txt
    │   └── subagents/               # Agent workspaces
    ├── memory/                      # Persistent (never auto-cleaned)
    │   ├── plans/                   # Archived completed plans
    │   ├── pinned/                  # Pinned outputs (via /pin)
    │   └── history/                 # Archived sessions
    ├── index/                       # Metadata
    │   ├── session.json             # Current session ID
    │   ├── current_plan.yaml        # Active plan
    │   └── tool_outputs.jsonl       # Append-only manifest
    └── DISABLE_OFFLOAD              # Escape hatch file

Note: The plugin automatically adds .fewword/scratch/ and .fewword/index/ to .gitignore.

---

Escape Hatch

If automatic offloading causes issues:

# Disable via file
touch .fewword/DISABLE_OFFLOAD

# Or via environment variable
export FEWWORD_DISABLE=1

---

What Gets Skipped

The plugin conservatively skips these commands:

• Interactive: ssh, vim, less, top, python, node, psql, etc.
• Already redirecting: commands with >, 2>, | tee
• Heredocs: commands containing <<
• Pipelines: commands containing | (v1 limitation)
• Trivial: commands under 10 characters

---

Configuration

Defaults (v1.3.5)

| Setting | Value | |---------|-------| | Inline threshold | 512B (outputs below this shown inline) | | Preview threshold | 4KB (outputs above this get tail preview on failure) | | Preview lines | 5 (tail only, for failures) | | Success retention (exit 0) | 24 hours | | Failure retention (exit != 0) | 48 hours | | Scratch max size | 250MB (LRU eviction) |

Environment Variable Overrides

# Tiered offloading thresholds
FEWWORD_INLINE_MAX=512              # Below this: show inline
FEWWORD_PREVIEW_MIN=4096            # Above this: add preview (failures only)
FEWWORD_PREVIEW_LINES=5             # Max preview lines

# Pointer customization
FEWWORD_OPEN_CMD=/open      # Command shown in pointer
FEWWORD_SHOW_PATH=1                 # Append file path to pointer
FEWWORD_VERBOSE_POINTER=1           # Use old verbose format (v2.0 style)

# Retention settings
FEWWORD_RETENTION_SUCCESS_MIN=1440  # 24h default
FEWWORD_RETENTION_FAIL_MIN=2880     # 48h default
FEWWORD_SCRATCH_MAX_MB=250          # LRU cap

Note: Longer retention keeps command outputs on disk longer. If you work with sensitive data, consider lowering TTLs via environment variables or adding .fewword/scratch/ to your backup exclusions.

---

Privacy & Security

Security Hardening (v1.3.5)

| Protection | What It Does | |------------|--------------| | Path Traversal Prevention | All file operations validate paths stay within working directory | | Bounded File Reads | Large files (>2MB) skipped to prevent memory exhaustion | | Secret Redaction | AWS keys, GitHub tokens, API keys auto-redacted before writing to disk | | Test Mode Safety | Matched secrets masked by default (use --show-matches to reveal) | | Manifest Integrity | Robust JSON escaping prevents corruption from special characters |

Bash Commands

| Logged | NOT Logged | |--------|------------| | Timestamp, session ID | Raw command arguments (may contain secrets) | | Tool name (e.g., "find", "pytest") | Full command text | | Output file path | Environment variables |

MCP Tools (Browser automation, GitHub, etc.)

FewWord intercepts MCP tool calls (mcp__*) for two purposes:

| What We Do | What We DON'T Do | |------------|------------------| | Log tool name (e.g., mcp__github__create_issue) | Log argument values (may contain tokens, secrets) | | Log input parameter keys (e.g., ["repo", "title"]) | Store or transmit your data anywhere | | Clamp pagination (limit requests to 100 results max) | Block read-only operations |

Example metadata entry:

{
  "timestamp": "2026-01-08T14:30:00",
  "tool": "mcp__github__search_issues",