phobos

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 cost/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
• Skills for plan and code

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 session
bash ~/src/phobos/install.sh --no-guard                            # never install it

The command guard

A second PreToolUse guard, on Bash and Grep — same idea, stop the waste before it lands in context:

• Grep in content mode with no head_limit — denied; add a limit, or locate with files_with_matches first.
• Bash floods — recursive ls, recursive grep, unbounded git log — denied unless piped or redirected; the reason gives the bounded form.
• Repeat failures — the same command re-run after it already failed, with nothing edited since, is denied so a broken command stops burning turns.

PHOBOS_CMD_GUARD=off claude                    # off for one session
bash ~/src/phobos/install.sh --no-cmd-guard    # never install it

State handoff

# phobos state

_generated 2026-07-09T09:20Z · git a1b2c3d (main), 3 uncommitted — a snapshot, re-verify before acting._

## Working set (uncommitted)
- src/api.ts
- src/api.test.ts

Written to .claude/phobos-state.md on edit turns and before every compaction, and injected at session start — so a new session (or a post-/compact//clear turn) re-orients from a small stamped snapshot instead of the transcript. The git stamp is the staleness flag: trust it as of that SHA, then verify.

Activity ledger

edited: api.ts, api.test.ts · 1.4k out
— context compacted (auto) —
edited: README.md · 0.6k out

Written to .claude/phobos-activity.log, tailed into every new session.

Benchmark and savings

bash ~/.claude/skills/phobos/hooks/benchmark.sh   # real measured tokens and estimated cost
bash ~/.claude/skills/phobos/hooks/savings.sh     # an estimate of tokens/cost saved

when             model            turns      out       in    cacheR    cacheW   hit%    est$    time
2026-07-05T10:11 claude-opus-4-8     12     8200     4100    210000      9000    98%   $0.39    7m0s
2026-07-06T14:02 claude-sonnet-5     40    15500     9000    880000     30000    98%   $0.64  30m30s
---
totals:   2 sessions · 23700 out tok · 13100 in tok · 1090000 cache-read tok · 39000 cache-write tok · ~$1.02 est.
averages: 11850 out tok/session · 1125s/session
trend:    ▄█  (out tokens per session, oldest → newest)

Dollar figures are estimates, not an invoice.

Update

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

Tuning knobs