Metadata-Version: 2.4
Name: mintoken
Version: 0.2.1
Summary: Local-proxy CLI for mintoken — sit between Claude Code / Codex and the upstream LLM, dedupe + truncate context, save 40-70% on long agent sessions.
Author-email: Mintoken <hello.mintoken@gmail.com>
License: MIT
Project-URL: Homepage, https://mintoken.dev
Project-URL: Documentation, https://mintoken.dev/docs/cli
Project-URL: Repository, https://github.com/vijayPrajapatii/mintoken-cli
Project-URL: Issues, https://github.com/vijayPrajapatii/mintoken-cli/issues
Keywords: llm,proxy,compression,claude-code,codex,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: httpx>=0.27
Requires-Dist: tiktoken>=0.7
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Dynamic: license-file

# mintoken

[![PyPI](https://img.shields.io/pypi/v/mintoken.svg)](https://pypi.org/project/mintoken/)
[![License: MIT](https://img.shields.io/badge/License-MIT-orange.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-mintoken.dev-orange)](https://mintoken.dev/docs/cli)

Local-proxy for [Mintoken](https://mintoken.dev). Sit between your AI coding tool (Claude Code, Codex, Cursor, your own LangChain agent) and the upstream LLM provider. Dedupe repeated tool results, truncate giant logs, save 40-70% of input tokens on long agent sessions. **Same model output, no SDK changes, one env var swap.**

## Why

Modern AI coding agents loop. Every turn re-sends the entire prior conversation. After 20 turns of file reads + bash output + grep results, you're paying to re-send the same content over and over — typically 90% of your bill is **cache reads of stale context**.

`mintoken` sits on `localhost`, intercepts your agent's HTTPS traffic to the LLM provider, dedupes redundant tool results in older turns, truncates the boring middle of giant logs — then forwards what's left to the real provider. Anthropic / OpenAI bill you for the smaller request.

## Install

```bash
pip install mintoken
```

Or from source:

```bash
git clone https://github.com/vijayPrajapatii/mintoken-cli
cd mintoken-cli
pip install -e .
```

## Setup

```bash
# (optional) save your mintoken key so the dashboard tracks savings
mintoken login --key mt_live_...

# start the local proxy
mintoken proxy
```

You'll see:

```
mintoken-cli v0.1.0
listening on  http://127.0.0.1:8788
level         standard
mintoken key  mt_live_da7a…
anthropic →   https://api.anthropic.com
openai →      https://api.openai.com
```

## Use with Claude Code

```powershell
# PowerShell
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:8788"
claude
```

```bash
# bash / zsh
export ANTHROPIC_BASE_URL="http://127.0.0.1:8788"
claude
```

Your existing Claude Code OAuth session keeps working — the proxy forwards the auth header unchanged. The OAuth token never leaves your machine.

## Use with Codex / OpenAI clients

```powershell
$env:OPENAI_BASE_URL = "http://127.0.0.1:8788/v1"
codex
```

```bash
export OPENAI_BASE_URL="http://127.0.0.1:8788/v1"
codex
```

Or with the OpenAI SDK directly:

```python
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8788/v1", api_key="sk-...")
```

## Use with both at once

The proxy handles both providers on the same port. Set both env vars and run Claude Code + Codex side by side — they share the same proxy.

## Flags

```
mintoken proxy [OPTIONS]

  --port              -p   default: 8788
  --host                   default: 127.0.0.1
  --key                    mintoken API key (or set MINTOKEN_KEY env)
  --level             -l   light | standard | aggressive  (default: standard)
  --anthropic-upstream     default: https://api.anthropic.com
  --openai-upstream        default: https://api.openai.com
```

## Compression levels

| Level | Min tokens to engage | Tool-result truncate threshold | Recency window (untouched) |
|---|---:|---:|---:|
| `light` | 8,000 | 4,000 | last 8 turns |
| `standard` *(default)* | 4,000 | 2,000 | last 6 turns |
| `aggressive` | 2,000 | 1,000 | last 4 turns |

Aggressive saves the most but compresses content the model might still need. Light is conservative. Standard is the production default and is what we'd recommend for nearly everyone.

## How it works (v0.2+)

Starting in v0.2.0, the CLI is a thin client that delegates compression to mintoken's hosted API. Two reasons: it lets us ship algorithm improvements instantly to every user without a `pip install --upgrade`, and it unlocks Tier 2 model-based summarization (Pro plan) which can't run locally.

```
Claude Code / Codex
    ↓ POST localhost:8788/v1/messages
mintoken local proxy
    ├─→ POST api.mintoken.dev/v1/cli/compress-context  (auth: mt_live_…)
    │     ← compressed body + savings metrics
    ↓ forward to upstream
api.anthropic.com / api.openai.com
```

If `api.mintoken.dev` is unreachable or your key is invalid, the proxy forwards the original body untouched — your request always completes.

## What gets compressed

**Dedupe** — when the same tool_result content appears multiple times in older turns (e.g., your agent re-reads the same file 3x), the earliest copies are replaced with a small back-reference. Only the latest occurrence stays verbatim.

**Truncate** — when a single tool_result is bigger than the per-result threshold (e.g., a 4,000-token build log), the head + tail are kept and the middle is dropped with a marker.

## What is *never* touched

- The system prompt
- The most recent N messages (recency window)
- Mid-flight tool_use / tool_result pairs
- Any conversation under the min-tokens threshold

If compression somehow produces a *bigger* body, the original is forwarded untouched. **Never increases your bill.**

## Verify it's working

The proxy attaches three response headers to every forwarded request:

```
x-mintoken-cli-tokens-before: 9027
x-mintoken-cli-tokens-after:  2947
x-mintoken-cli-tokens-saved:  6080
```

If something went wrong, an `x-mintoken-cli-skipped` header tells you why (`auth_failed`, `quota_exceeded`, `cloud_unreachable`, `below_threshold`, `no_savings`, etc.).

You can also visit your dashboard at <https://mintoken.dev/dashboard> — savings flow there in real time.

## Privacy

- **What stays on your machine:** your upstream provider auth token (Anthropic OAuth, OpenAI API key). The proxy forwards it unchanged to the real provider.
- **What goes to api.mintoken.dev:** the request body — `messages`, `model`, tool definitions. Sent over HTTPS, processed in memory, never logged or stored. We persist token counts + metadata only (for your dashboard).
- **What we never see:** your provider auth token, any response from the upstream, anything outside the request body.

If your environment requires content not to leave your machine at all (regulated industries, defense, healthcare), email <hello.mintoken@gmail.com> about the self-hosted Enterprise tier.

## License

MIT.
