Metadata-Version: 2.4
Name: tokenlint
Version: 0.1.1
Summary: Catch LLM cost anti-patterns in your Python AI app before they hit prod — a local, static token-cost linter.
Project-URL: Homepage, https://github.com/zlyan1110/tokenlint
Project-URL: Source, https://github.com/zlyan1110/tokenlint
Project-URL: Issues, https://github.com/zlyan1110/tokenlint/issues
Project-URL: Changelog, https://github.com/zlyan1110/tokenlint/blob/main/CHANGELOG.md
Author: TokenLint
License: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,cost,fastapi,linter,llm,openai,static-analysis,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# TokenLint

**Your LLM bill is bleeding and you don't know which line of code is doing it.** TokenLint scans your Python AI app *locally and statically* (it never runs your code or sends it anywhere) and flags the patterns that quietly inflate token costs — premium models on trivial steps, missing output caps, un-cached static prompts, and **unbounded agent loops that burn tokens unpredictably** — before they hit production.

Runs in your editor, your terminal, or CI. Zero dependencies, zero network calls.

```bash
pipx install tokenlint     # or: pip install tokenlint
tokenlint .                # scan your project
```

```
TokenLint  — LLM cost pre-flight

  app/agent.py
    FAIL R004-unbounded-agent-loop  line 30
         LLM call inside a `while True` with no break — token runaway risk.
         → Add an explicit max-steps budget and a token/cost ceiling.
         ~$0.0050/call (gpt-4o)
    WARN R001-expensive-model  line 19
         Call uses 'claude-opus-4', a premium-priced model.
         → If this step is simple, route it to claude-sonnet/haiku.
         ~$0.0377/call

  1 fail   7 warn   0 info
```

## What it catches today (v0.1, free, MIT)

| Rule | What it flags |
|------|---------------|
| `R001-expensive-model` | Premium model (Opus / GPT-4o / o1…) on a step that a cheaper model could do |
| `R002-no-max-tokens` | No output cap — one runaway completion can 10× a call's cost |
| `R003-no-prompt-cache` | Large static Anthropic system/context with no `cache_control` (often ~90% of input spend is cacheable) |
| `R004-unbounded-agent-loop` | LLM call inside `while True` with no break — the #1 way agents quietly burn money |
| `R004-llm-call-in-loop` | LLM call in a loop — cost scales with iterations; needs a budget |
| `R005-large-inline-prompt` | Oversized inline prompt literal sitting in the hot path |

Works with the **Anthropic** and **OpenAI** SDKs and raw call patterns. LangChain / LlamaIndex detection is on the roadmap.

## CI usage

```bash
tokenlint . --fail-on warn   # exit non-zero on warnings too, to block a costly merge
```

## Use it inside Claude Code (plugin)

TokenLint ships as a Claude Code plugin: a `/tokenlint:cost-preflight` skill that
scans your project and offers fixes, plus a non-blocking hook that flags an
**unbounded agent loop the moment you write one**.

```bash
# from the repo (once it's on GitHub)
/plugin marketplace add zlyan1110/tokenlint
/plugin install tokenlint@tokenlint

# or try it locally without installing
claude --plugin-dir ./tokenlint
```

Then in a session:

```
/tokenlint:cost-preflight          # scan the whole project
/tokenlint:cost-preflight app/     # scan a path
```

The skill auto-loads when you're working in `.py` files and will offer to apply
fixes (caps, prompt caching, model routing, agent budgets) with your approval.

## TokenLint Pro

The free linter tells you *where* you're leaking. **Pro fixes it for you:**

- **Auto-fix diffs** — PR-ready patches that add caps, prompt caching, and budgets
- **Model-routing config generator** — send cheap steps to cheap models automatically
- **Agent token-budget guard** — a drop-in wrapper that hard-stops runaway loops
- **Self-host break-even calculator + vLLM/TGI deploy configs** — *when* does running your own inference beat the API, and how to configure it

**Pro is in development — not yet for sale.** ⭐ [Star the repo](https://github.com/zlyan1110/tokenlint) to be notified when it lands. _(Planned: ~$39 one-time or $19/mo for the always-current ruleset.)_

## Why local + static?

Observability platforms (Helicone, Langfuse, …) show you cost *after* traffic runs through them. TokenLint catches it *before* you ship — in the same loop where you write the code (including inside Claude Code / Cursor). The two are complementary; this one is free and runs offline.

## License

MIT for the core linter. Pricing table in `tokenlint/pricing.py` is editable — verify against current provider pricing.
