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.

Alternative: Install from inside Claude Code

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.

---

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",
  "input_keys": ["query", "repo", "limit"],
  "input_count": 3
}

Your actual query strings, repo names, and other sensitive values are never logged.

---

License

MIT — Use it, modify it, share it.

---

Contributing

Issues and PRs welcome! Ideas for improvement:

• Opencode Support