weasel

Weasel is a single-file operating guide designed to keep AI coding assistants from falling apart during long work sessions. The problem it addresses is a specific kind of failure that shows up when you use tools like Claude or similar AI agents for extended tasks: the assistant starts drifting, rewriting plans instead of executing them, treating old notes as if they are still current, looping through the same checks without making progress, or narrating what it intends to do rather than actually doing it.

The solution is a CLAUDE.md file, which is a special configuration file that AI coding assistants read at the start of a session to understand how they should behave in a given project. Weasel's version of this file gives the agent six compact rules: act only after checks pass, rely on current evidence rather than memory, keep state summaries short, break out of loops early, only update plans when behavior actually needs to change, and keep safety guardrails functional rather than treating them as excuses to avoid action.

The repository also includes a companion file for agents that look for AGENTS.md instead of CLAUDE.md, a short demo prompt you can paste into any capable AI assistant to test the approach in about 60 seconds, and screenshots from demo sessions showing what a well-grounded agent response looks like versus the usual wall of status paragraphs.

To use it, you copy CLAUDE.md into any project where you use a coding assistant and start the session by asking the assistant to read that file. For longer sessions, you can ask the assistant to maintain a small state file tracking the current task, the last action taken, what was verified, and what the next concrete step is. That state file is meant to be a handoff surface, not a diary.

This is intentionally minimal. There is no framework, no server, no installation, and no hidden system. It is one copyable file, MIT licensed.