Why it is worth attention

It provides practical, measurable token savings through guards, state handoff, and activity logging, with easy installation via plugin marketplace or script, and includes a benchmark to verify real savings.

Who it is for

Claude Code users seeking to reduce API costs
Developers working on large codebases with many irrelevant files
Teams wanting to enforce best practices in AI-assisted coding sessions
Power users who want fine-grained control over Claude Code's behavior

Use cases

Preventing Claude Code from reading node_modules, build artifacts, or lockfiles
Blocking unbounded grep and recursive ls commands that waste tokens
Tracking activity and context usage across sessions to optimize workflow
Maintaining a compact state handoff between sessions to avoid transcript bloat

Strengths

No model calls in the request path, so it adds negligible overhead
Highly configurable via environment variables and allowlists
Multiple installation methods including plugin marketplace and manual setup
Built-in benchmarks and savings estimates to validate impact

Considerations

Only works within Claude Code and requires a Bash environment (e.g., Git Bash on Windows)
Plugin installation cannot set the main status line; the full install.sh script is needed for that feature
Dollar savings figures are estimates, not guaranteed exact savings

README quick start

phobos

Skills and hooks for Claude Code that cut down on wasted tokens. Skills steer the model, hooks enforce it. Nothing runs in the request path.

Install

git clone https://github.com/broisnischal/phobos.git ~/src/phobos
bash ~/src/phobos/install.sh

On Windows, run this from Git Bash. Restart Claude Code after.

Check the install any time:

bash ~/.claude/skills/phobos/hooks/doctor.sh

Flags: --skills-only, --settings-only, --no-guard, --no-cmd-guard, --no-statusline, --quiet.

Install as a plugin

phobos is also a Claude Code plugin marketplace. Inside Claude Code:

/plugin marketplace add broisnischal/phobos
/plugin install phobos@phobos

This installs all three skills (phobos, phobos-code, phobos-plan) and wires every hook automatically — no settings.json edits, updated with /plugin marketplace update.

One difference from install.sh: a plugin can't set the main status line — Claude Code only lets plugins define agent/subagentStatusLine, and the plugin's cache path is versioned and ephemeral. To get the effort/context gauge shown above, run install.sh (which wires it for you), or point your own settings.json statusLine at a stable clone: bash "$HOME/.claude/skills/phobos/hooks/statusline.sh".

What you get

Read guard
Command guard
Turn triage
Context aware
Context gauge
Session usage
Activity
State handoff
Tab spinner
Skills for plan and code
/phobos-update command

The read guard

Denies reads of:

node_modules/, vendor/, .venv/, __pycache__/, .cache/
dist/, build/, .next/, .nuxt/, .output/, coverage/
lockfiles — package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock, poetry.lock, uv.lock, go.sum
*.min.js, *.map, *.pyc, *.so, fonts, other binaries
.git/ internals
unbounded reads over 2 MB

Images and PDFs always pass.

Unbounded reads are also capped by line count (default 2000), not just size — a file can be small in bytes but thousands of lines long.

echo 'node_modules/my-patched-pkg' >> .claude/phobos-guard-allow   # per-repo allowlist
PHOBOS_GUARD=off claude                                            # off for one se

Description

the best token is the token never spent

Related repositories

Similar projects matched by category, topics, and programming language.

jamesob

Featured

local-llm

A comprehensive guide for building and configuring a high-end local machine to run state-of-the-art LLMs, with detailed hardware choices, BIOS tuning, and Docker-based model serving.

AI & Machine LearningLarge Language Models

1,660

bjan

Featured

claudemux

Claudemux is a lightweight, dependency-minimal message bus that lets multiple Claude Code sessions communicate in real-time over tmux, enabling one session to ask another a question and receive the answer without manual intervention.

AI & Machine LearningAI Agents

AARomanov1985

Audio-Cassette-Simulation

A set of bash scripts using ffmpeg to simulate vintage cassette tape audio profiles with noise, wow/flutter, bandwidth limits, and EQ.

Shell

373