Kevin

Keeps Every Verbose Item Narrow — context offloading plugin for OpenCode.

Intercepts large tool outputs, writes them to disk, and replaces them with compact pointers like:

[fw A1B2C3D4] bun test e=1 45K 891L | 2 failed, 48 passed | retrieve with context_open tool

Saves ~80% of context tokens on typical coding sessions.

---

Installation

// opencode.json
{
  "plugin": ["@bulga138/kevin"],
}

Or one-liner:

bash <(curl -fsSL https://raw.githubusercontent.com/bulga138/kevin/main/install.sh)

---

How it works

1. tool.execute.after — captures every tool output above the inline threshold (default 512 B) and writes it to ~/.cache/opencode/kevin/{session}/
2. chat.message — before the LLM sees each message, replaces stored outputs with compact [fw XXXXXXXX] pointers
3. experimental.session.compacting — injects the offload index into context compaction summaries so the model survives context resets
4. experimental.chat.system.transform — keeps the model passively aware of how many outputs are offloaded

---

Output tiers

Size	Exit code	What the model sees
< 512 B	any	Full output (inline)
512 B – 4 KB	any	Compact pointer only
> 4 KB	0 (success)	Compact pointer only
> 4 KB	≠ 0 (failure)	Pointer + last 10 lines

---

Tools available to the model

Tool	Description
context_open	Retrieve offloaded content by ID. Supports start_line / end_line for slicing.
context_recent	List recent offloaded outputs. Supports tags filter.
context_search	Full-text search — plain substring or /regex/flags. Returns ±context lines per match.
context_save	Manually offload arbitrary content with a label.
context_export	Export current session as markdown.
context_pin	Pin an entry to prevent LRU/TTL eviction.
kevin_unpin	Remove a pin.
kevin_note	Attach a free-text note to an entry.
kevin_tag	Add or remove tags on an entry.
kevin_diff	Unified diff between two offloaded outputs.
kevin_timeline	Chronological view of all offloaded outputs for the session.
kevin_doctor	Diagnostics: storage health, config, orphaned files.
kevin_stats	Token-saving statistics for the current session.

---

Configuration

All options can be set via environment variables (KEVIN_*) or a config file at ~/.config/kevin/config.json (or .kevin/config.json in the project directory). Environment variables take precedence.

Env var	Config key	Default	Description
KEVIN_INLINE_MAX	inline_max	512	Bytes below which output is kept inline
KEVIN_COMPACT_MAX	compact_max	4096	Upper boundary of compact-pointer tier
KEVIN_MAX_CACHE_MB	max_cache_mb	250	Cache ceiling before LRU eviction
KEVIN_TTL_SUCCESS_H	ttl_success_h	24	Hours before successful outputs expire (0 = never)
KEVIN_TTL_FAILURE_H	ttl_failure_h	48	Hours before failed outputs expire (0 = never)
KEVIN_DISABLE	disabled	false	Completely disable offloading
KEVIN_DISABLE_REDACTION	disable_redaction	false	Skip secret redaction
KEVIN_AUTO_PIN_FAILURES	auto_pin_failures	true	Auto-pin failed outputs
KEVIN_AUTO_PIN_MIN_BYTES	auto_pin_min_bytes	0	Auto-pin outputs above this size (0 = off)
KEVIN_AUTO_PIN_TOOLS	auto_pin_tools	""	Comma-separated tool names to always pin
KEVIN_POINTER_FORMAT	pointer_format	""	Custom pointer template (tokens: {id} {tool} {size} {lines} {exit} {ts})
KEVIN_INTERCEPT_MCP	intercept_mcp	false	Intercept MCP tool outputs
KEVIN_DISABLE_UPDATE_CHECK	disable_check	false	Disable automatic update check

Legacy FEWWORD_* prefixes are accepted as fallbacks for all options.

Config file example

{
  "inline_max": 1024,
  "compact_max": 8192,
  "ttl_success_h": 12,
  "ttl_failure_h": 72,
  "auto_pin_failures": true,
  "auto_pin_tools": ["test", "build"]
}

Per-project disable

mkdir -p .kevin && touch .kevin/DISABLE_OFFLOAD

---

Secret redaction

Before writing any output to disk, KEVIN automatically redacts:

• AWS access keys (AKIA…)
• AWS secret keys
• GitHub tokens (ghp_, gho_, ghs_, ghr_, github_pat_)
• OpenAI / Anthropic keys (sk-…)
• Generic key/token/secret/password assignments
• Bearer tokens in HTTP headers
• JWTs
• PEM private keys

Matched text is replaced with [REDACTED:{type}] so surrounding context is preserved.

Disable with KEVIN_DISABLE_REDACTION=1 (not recommended).

---

Storage layout

~/.cache/opencode/kevin/
├── {SESSION_ID}/
│   ├── {ID}.txt           # full (redacted) output
│   ├── {ID}.meta.json     # tool, exitCode, bytes, lines, hash, signature, tags, note…
│   ├── LATEST.txt         # symlink → most recent output
│   └── LATEST_{tool}.txt  # symlink → most recent output per tool
└── stats.json

---

CLI

kevin stats    # token savings for the current session
kevin list     # list all offloaded outputs
kevin clear    # clear the cache
kevin migrate  # backfill metadata fields from old versions

---

Architecture

src/
├── index.ts                  # Integration layer — hook/tool wiring only
├── config.ts                 # Env var + config file resolution
├── redaction.ts              # Secret pattern matching and redaction
├── pointer.ts                # Re-exports from offloadService (backward compat)
├── stats.ts                  # Session statistics sidecar
├── update-check.ts           # GitHub API update check
├── transport/
│   ├── fileTransport.ts      # FileTransport interface
│   │                           NodeFileTransport (production)
│   │                           MemoryTransport (tests)
│   └── index.ts
├── domain/
│   └── offloadService.ts     # ALL business logic (offload, search, diff, TTL…)
└── cli/
    ├── main.ts               # CLI dispatcher
    └── commands/
        ├── stats.ts
        ├── list.ts
        ├── clear.ts
        └── migrate.ts

Dependency flow: index.ts → offloadService → transport. No cycles.

---

Inspired by FewWord (Claude Code plugin),

License

MIT