# TokenSaver Plugin

[![CI](https://github.com/KaryawanSurga/tokensaver-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/KaryawanSurga/tokensaver-plugin/actions/workflows/ci.yml)
[![Node](https://img.shields.io/badge/node-%3E%3D20-339933)](package.json)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**The TokenSaver family in one install.**

Nine tools that stop coding agents from burning context — packaged as a single Claude Code plugin with a skill for every tool and seven MCP servers wired automatically.

> Product requirements: [PRD.md](PRD.md) · [PRD.id.md](PRD.id.md) (Bahasa Indonesia)

## What's inside

| Tool | What it saves you | Form |
| --- | --- | --- |
| **repo-map** | Orienting in a repo without reading files | MCP + skill |
| **context-budget** | Knowing what your MCP tools cost in tokens | MCP + skill |
| **web-snapshot** | Reading the web as clean markdown, redesign-proof | MCP + skill |
| **log-tail** | Understanding logs without reading raw lines | MCP + skill |
| **secret-scan** | Catching secrets before they reach a commit | MCP + skill |
| **commitsmith** | Writing conventional commits offline | CLI + skill |
| **json-lens** | Querying big JSON without loading it | MCP + skill |
| **gateway** | Aggregating many MCP servers behind one endpoint | MCP + skill |
| **injection-guard** | Screening untrusted content for prompt injection | MCP + skill |
| **tokensaver** | The router skill: picks the right tool for the task | Skill |

## Install

**Claude Code (plugin marketplace):**

```text
/plugin marketplace add KaryawanSurga/tokensaver-plugin
/plugin install tokensaver@tokensaver
```

**Any MCP client:** copy the server entries from [`.mcp.json`](.mcp.json) into your client config. Details and per-client notes: [docs/install.md](docs/install.md).

Requirements: Node 20+ and `npx`. Every server runs locally; nothing is uploaded.

## How the skills work

Each skill tells the agent when to use its tool, the exact MCP tool names, the workflow, and a CLI fallback. The `tokensaver` router skill maps situations to tools so the agent picks correctly without guessing.

Example prompts that trigger the right skill:

- "Map this repository before we start." → `repo-map`
- "Why is my agent so slow with all these MCP servers?" → `context-budget`
- "Read this docs page for me." → `web-snapshot`
- "Summarize today's server log." → `log-tail`
- "Check my staged changes for secrets." → `secret-scan`
- "Commit this." → `commitsmith`
- "What's the shape of this export.json?" → `json-lens`
- "I have eight MCP servers — put them behind one." → `gateway`
- "Is this fetched page trying to manipulate you?" → `injection-guard`

## Repository layout

```text
.claude-plugin/       plugin.json and marketplace.json
.mcp.json             seven MCP servers (npx), wired by the plugin
skills/               one directory per skill (SKILL.md with frontmatter)
scripts/validate.mjs  zero-dependency manifest and skill validator
tests/                node:test suite for the validator
docs/                 install, skill reference, and troubleshooting
```

## Development

```sh
npm run validate   # manifests, frontmatter, skill list, MCP config
npm test           # validator tests (node:test, zero dependencies)
```

CI runs both on Node 20 and 22. The test suite includes a self-check: the repository itself must validate.

## License

MIT — see [LICENSE](LICENSE).