Metadata-Version: 2.4
Name: mujin-skillbudget
Version: 0.1.0
Summary: Budget the always-loaded token cost of your AI agent context (CLAUDE.md, skill descriptions, Cursor rules) and fail CI when it bloats.
Project-URL: Homepage, https://github.com/mujinlabs/skillbudget
Project-URL: Issues, https://github.com/mujinlabs/skillbudget/issues
Author: Mujin Labs
License: MIT
License-File: LICENSE
Keywords: ai-agents,ci,claude-code,context,cursor,mcp,skills,tokens
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Provides-Extra: accurate
Requires-Dist: tiktoken; extra == 'accurate'
Description-Content-Type: text/markdown

# skillbudget

**Your agent's always-loaded context has a token budget. Spend it wisely — and fail CI when you blow it.**

Every turn, before the user says a word, your coding agent loads `CLAUDE.md`, every
skill's description, and your always-apply rules into its context window. Teams quietly
let this grow to tens of thousands of tokens — one enterprise setup burned
[143K of 200K tokens (72%) on definitions alone](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2808).
A bloated `CLAUDE.md` (>5K tokens) measurably shrinks the room left for actual work.

`skillbudget` measures that always-on surface and gives you a CI gate.

```bash
pipx install mujin-skillbudget

skillbudget scan --budget 8000     # exit 1 if always-on context exceeds the budget
```

```
always-on context budget: 8,000 tokens   [estimated (~4 chars/token — pip install tiktoken for exact)]

    1,853  CLAUDE.md
       16  skill deploy · frontmatter
       13  skill test · frontmatter
  -------
    1,882  TOTAL always-on  (1,882/8,000  ok)

  on-invocation (not counted — loads only when triggered):
      500  skill deploy · body

  suggestions:
  - CLAUDE.md is 1,853 tokens — move rarely-needed guidance into on-demand skills.
```

## What counts (and what doesn't)

The key insight most "context size" tools miss: **skill bodies are lazy.** A skill only
puts its *name + description* into context until it's actually invoked. So skillbudget
charges the always-on budget for:

- `CLAUDE.md` (or `AGENTS.md`) — loaded every turn,
- each skill's **frontmatter** (`.claude/skills/*/SKILL.md` description),
- Cursor rules with `alwaysApply: true`.

…and reports skill **bodies** and glob-scoped rules separately as *on-invocation* cost —
real, but only when triggered. Budget the thing that's always there.

## Exact counts

By default it estimates (~4 chars/token, zero dependencies, fully offline). For exact
`cl100k_base` counts, `pip install mujin-skillbudget[accurate]` (pulls `tiktoken`) — it's
auto-detected.

## CI gate

```yaml
# .github/workflows/context-budget.yml
jobs:
  skillbudget:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.11" }
      - run: pipx install mujin-skillbudget
      - run: skillbudget scan --budget 8000   # fails the build if context bloats
```

`--json` for machine output, `--no-fail` to report without gating.

## Part of a set

- [**agentsync**](https://github.com/mujinlabs/agentsync) — keep CLAUDE.md / AGENTS.md / Cursor / Copilot in sync.
- [**agentaudit**](https://github.com/mujinlabs/agentaudit) — audit skills / MCP servers / plugins for security & quality.

Sync your config → budget its size → audit it for risk. Same files, same CI.

---

Built by **[Mujin Labs](https://github.com/mujinlabs)** — tooling for the autonomous-agent era. MIT.
