broisnischal/phobos

Phobos is a set of add-ons for Claude Code, the AI coding assistant, designed to stop it from wasting tokens, which are the units you pay for and that limit how much an AI model can read and remember in one session. It works through two mechanisms: skills that gently guide the AI's behavior, and hooks that firmly enforce rules before an action happens. None of it calls an AI model itself, so it adds no extra cost or delay on its own. The main feature is a read guard that blocks Claude Code from opening files that are usually useless to read directly, such as dependency folders, build output, lock files, minified JavaScript, and other binary files. It also caps how much of any single file gets read, both by file size and by number of lines, so one giant file cannot flood the conversation. A companion command guard applies similar limits to shell commands and searches, blocking things like an unbounded recursive search with no limit set, a flood-prone command such as listing every file recursively, or re-running the exact same command that already failed without changing anything. Beyond the guards, phobos keeps a small running summary of what changed in the project and writes it to a file, so a new session, or one that just cleared its memory, can quickly get its bearings from a short snapshot instead of re-reading the whole conversation history. It also logs recent activity and can show a status line with real time cost and context usage, plus scripts to measure actual token usage and estimate how much the tool has saved. Everything is configurable through environment variables and can be turned off per session or uninstalled entirely, and installation works either as a plain script or as an official Claude Code plugin. The project is written mostly in Shell script and is aimed at developers who use Claude Code regularly and want to control their token spending, rather than at end users of an app. It is licensed under MIT, based on the license badge shown in the README.