fycw 0.1.0

Context-hygiene layer for Claude Code: curated compression, offload, /clear, reload.

FYCW — Fuck Your Context Window

🇬🇧 English | 🇩🇪 Deutsch

A context-hygiene layer for Claude Code. When your context window fills up, run /fycw-flush — Claude reviews what actually matters, compresses it into a single file, you /clear, and reload it. A transparent, controllable replacement for the opaque auto-compact.

fycw init          # scaffold it into your project

That's it. You get a memory bank in your repo:

.fycw/
├── handoff.md       compressed restart snapshot (written by /fycw-flush)
├── active.md        what you're working on right now
├── progress.md      done / open / next steps
├── decisions.md     append-only decision log
├── map.md           a map of the codebase so Claude stops re-reading it
├── index.md         index of offloaded chunks in archive/
└── archive/         older context, pulled back on demand

---

What it is (and isn't)

FYCW is not a hack that intercepts or enlarges Claude's context window — that can't be done from the outside. It's a lightweight discipline + offloading layer built from Claude Code's own primitives (slash commands + CLAUDE.md + a memory folder). Three things do the work:

• A memory bank (.fycw/) — durable, human-readable project state that lives in your repo and survives /clear.
• A curated flush — you review what matters, Claude compresses it into a self-contained handoff.md, then you clear and reload. A transparent replacement for the black-box /compact.
• Subagent offloading — heavy reading happens in a subagent's context window, so your main context stays free (the single biggest lever).

The result: context grows more slowly, and your working state is always recoverable.

---

Prerequisites

Requirement	Minimum	Check	Install
Claude Code	any	claude --version	docs.claude.com
Python	3.9+	python --version	python.org
uv (recommended)	any	uv --version	see below

macOS (Homebrew):

brew install uv

Windows (winget):

winget install astral-sh.uv

Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

---

Install

Step 1 — install the CLI (pick one):

uv tool install fycw      # recommended (isolated tool env)
pipx install fycw         # alternative
pip install fycw          # may need PATH setup — see troubleshooting

Prefer not to install at all? Run it straight from PyPI:

uvx fycw init             # runs the latest fycw without installing

Step 2 — scaffold FYCW into your project:

cd /path/to/your/project
fycw init

Open the project in Claude Code and you're set. fycw init is idempotent and never overwrites your .fycw/*.md memory content.

Options

Command	What it does
fycw init [PATH]	Scaffold into PATH (default: current dir)
fycw init --with-hooks	Also install the optional SessionStart/PreCompact hooks
fycw init --force	Refresh the commands and the CLAUDE.md block (keeps memory)
fycw uninstall [PATH]	Remove commands + CLAUDE.md block, keep the memory bank
fycw uninstall --purge	Also delete .fycw/ (irreversible)

Windows / PowerShell: the slash commands (/fycw-flush etc.) run inside Claude Code, so they work the same on every OS. The fycw CLI itself is cross-platform.

---

Tutorial (a typical session)

1. Install FYCW into your project (above).
2. Seed the map. Open Claude Code and ask: "Fill in .fycw/map.md with a map of this repo." Tell it to use a subagent so the reading doesn't eat your context.
3. Work normally. Claude keeps active.md / progress.md updated and logs choices to decisions.md.
4. Context fills up (~70–80%). Run /fycw-flush. Claude reviews the conversation against the Relevance rubric, writes a compact handoff.md, and offloads bulky finished work to archive/. Open handoff.md and tweak it if you like — it's just a file.
5. /clear, then /fycw-load. Fresh context window, full working state restored from handoff.md.
6. Later, pull an old thread back with /fycw-recall auth flow — only that archive chunk is loaded, not everything.

---

Commands (inside Claude Code)

Command	What it does
/fycw-load	Rebuild the working context from handoff.md (+ map.md, index.md)
/fycw-save	Update the memory bank from the current state
/fycw-flush	Curated compress → write handoff.md → prep for /clear
/fycw-recall <topic>	Pull one specific archived chunk back into context
/fycw-status	Estimate what's eating context; recommend save/flush

---

How it works

Memory bank. .fycw/ holds distilled state, not raw dumps. map.md is the highest-leverage file — a good map means Claude rarely re-reads directories. It's plain markdown in your repo: diffable, editable, shareable.

Curated flush = transparent compaction. The CLAUDE.md protocol contains a Relevance rubric (an explicit KEEP / DROP list): goal, decisions + rationale, constraints, blockers, file references and next steps are kept; raw file contents, long logs, intermediate reasoning and repetition are dropped. /fycw-flush applies that rubric to produce handoff.md, which /fycw-load reads back after /clear.

Subagents. Any "read a lot to understand something" task is delegated to a subagent that returns only a compact summary, keeping large file contents out of your main window entirely.

---

Hooks (optional)

Hooks can auto-load the memory bank at session start and nudge a flush before compaction:

fycw init --with-hooks

⚠️ Verify the hook schema. Claude Code's hook event names and JSON structure change between versions. Check the current hooks docs before relying on them; if an event doesn't exist in your version, drop it — the slash commands cover the same purpose manually.

⚠️ Windows: the shipped hook commands are POSIX-shell one-liners (cat, 2>/dev/null), so they need Git Bash on Windows. Without it (Claude Code then falls back to PowerShell) the SessionStart hook fails silently — skip --with-hooks and use /fycw-load manually instead.

---

Team setup

.fycw/ is meant to be committed — persistent, shareable memory with history is the whole point. One person runs fycw init and commits it; teammates pull and their Claude Code sessions start with the same map and handoff.

Note: .fycw/ can contain sensitive project context. Be mindful with public repos.

---

Updating & uninstalling

uv tool upgrade fycw           # get the latest CLI
fycw init --force              # refresh commands + CLAUDE.md block in a project

fycw uninstall                 # remove from a project, keep memory
fycw uninstall --purge         # also delete .fycw/

---

FAQ

Does this expand or hack the context window? No. That's not possible from outside Claude Code. FYCW slows context growth and makes state recoverable; it doesn't change the window size.

How is /fycw-flush different from /compact? /compact is automatic, opaque, and gone after /clear. The FYCW flush is reviewed by you, written to a readable file you can edit, survives /clear, and lives in git.

Does it work with other agents (Cursor, Cline, …)? The concept ports easily, but the CLI targets Claude Code's .claude/commands + CLAUDE.md layout.

---

Troubleshooting

fycw: command not found after installing — the CLI is installed but its bin dir isn't on your PATH.

• uv (uv tool install fycw): run uv tool update-shell, then open a new terminal.
• pipx (pipx install fycw): run pipx ensurepath, then open a new terminal.
• pip: add ~/.local/bin (Linux) or ~/Library/Python/3.x/bin (macOS) to your PATH, or run python -m fycw.

uvx fycw — will it resolve? Yes: the package and the command are both named fycw, so uvx fycw init works directly (no --from needed).

---

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Templates live in src/fycw/templates/; keep the tool dependency-free.

License

MIT. Publishing your own copy (to GitHub + PyPI)? See PUBLISHING.md.