Metadata-Version: 2.4
Name: fycw
Version: 0.1.0
Summary: Context-hygiene layer for Claude Code: curated compression, offload, /clear, reload.
Project-URL: Homepage, https://github.com/Pettielein/fycw
Project-URL: Repository, https://github.com/Pettielein/fycw
Project-URL: Issues, https://github.com/Pettielein/fycw/issues
Author: Philipp
License: MIT
License-File: LICENSE
Keywords: ai,claude-code,context-management,developer-tools,llm,productivity
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# FYCW — *Fuck Your Context Window*

🇬🇧 English | 🇩🇪 [Deutsch](README.de.md)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![PyPI](https://img.shields.io/pypi/v/fycw)](https://pypi.org/project/fycw/) [![Python](https://img.shields.io/pypi/pyversions/fycw)](https://pypi.org/project/fycw/) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

A **context-hygiene layer for [Claude Code](https://docs.claude.com/en/docs/claude-code/overview).** 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](https://docs.claude.com/en/docs/claude-code/overview) | any | `claude --version` | [docs.claude.com](https://docs.claude.com/en/docs/claude-code/overview) |
| Python | 3.9+ | `python --version` | [python.org](https://www.python.org/downloads/) |
| 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](CONTRIBUTING.md). Templates live in `src/fycw/templates/`; keep the tool dependency-free.

## License

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