Metadata-Version: 2.4
Name: mintoken
Version: 0.1.0
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
Project-URL: Repository, https://github.com/vijayPrajapatii/mintoken
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
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

# mintoken-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-cli 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-cli
```

Or from source:

```bash
git clone https://github.com/vijayPrajapatii/mintoken
cd mintoken/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.

## 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
```

You can also visit your dashboard at <https://mintoken.dev/dashboard> — savings flow there in real time (provided you've set `--key`).

## Privacy

- Auth tokens (OAuth or API key) are forwarded **unchanged** through localhost. They never leave your machine.
- Request bodies are compressed locally, in memory. We never log or store prompts.
- The only thing that goes to `api.mintoken.dev` is a small metric record per request: model name, token counts, duration. No content. No headers. No prompts.
- If you don't set `--key`, no telemetry is sent at all — fully local mode.

## License

MIT.
