# LocalTokens

**Turn your machine — or your whole LAN of ollama nodes — into a local
token generator for coding agents.** An MCP server that lets Claude Code,
opencode or codex delegate bounded *processing tasks* to local models,
cutting cloud-credit usage while the agent keeps doing the thinking.

Pure Python stdlib. Zero dependencies. One file of config (optional).

## Why

A large share of daily agent spend goes to work that doesn't need a
frontier model: first-pass code review, summarising files, boilerplate,
format conversions, commit messages. LocalTokens moves that work to your own
hardware with two real levers:

1. **File-aware tools** — the agent sends *paths*, never contents. Files
   are read locally and go straight to the local model: they never enter
   the agent's context window.
2. **Local generation** — bulk output is produced by your nodes; the
   agent only reviews the result.

Unlike single-node delegation servers, LocalTokens speaks to a **pool of
nodes**: tasks fan out across your LAN in parallel, with per-task
failover, round-robin with random start (multiple agent sessions won't
stampede one node), and your workstation's ollama used only as a last
resort so it never becomes the straggler.

Savings are **measured, not assumed** — every call logs two honest
counters (input reading avoided vs. output generated locally, which is
re-read as input) to a JSONL ledger; the `estado` tool reports totals.

## Tasks, not prompts

| Tool | Task | Fan-out |
|---|---|---|
| `procesar` | one bounded task (boilerplate, docstrings, commit msg…) | 1 node |
| `lote` | N independent tasks at once | 1 node per task |
| `revisar_archivos` | first-pass code review of file paths | 1 node per file |
| `resumir_archivos` | summarise/extract from files | 1 node per file |
| `estado` | pool health + accumulated savings | — |

## Install

```bash
pip install -e .            # or: pipx install .
ollama pull qwen2.5-coder:7b llama3.2:3b   # on each node you'll use

# Claude Code
claude mcp add --scope user localtokens localtokens

# codex
codex mcp add localtokens -- localtokens

# opencode (~/.config/opencode/opencode.json)
# "mcp": { "localtokens": { "type": "local", "command": ["localtokens"] } }
```

Then let it configure itself:

```bash
localtokens init            # detects CPU/RAM/GPU, scans your LAN for
                            # ollama nodes, recommends models for your
                            # hardware and writes the config
localtokens init --solo-mostrar     # report only, write nothing
localtokens init --sin-escanear     # skip the LAN scan (localhost only)
localtokens init --rango 10.0.0.0/24  # scan a specific subnet
```

`init` detects your local CPU, RAM and GPU (nvidia-smi/rocm-smi), probes
your subnet for ollama nodes (TCP port 11434, two passes), inventories
which models each node serves, and recommends models your hardware can
actually run — a 24 GB GPU gets `qwen2.5-coder:32b`, a 2013 CPU-only box
gets `qwen2.5-coder:1.5b`. Existing config is backed up before writing.

Prefer manual setup? Copy `config.example.json` to
`~/.config/localtokens/config.json` and list every node (**first entry =
the machine you work on**; it is deliberately deprioritised). On each remote node, run ollama reachable
from the LAN: `OLLAMA_HOST=0.0.0.0:11434 ollama serve`.

An optional agent skill that teaches *when* to delegate ships in
[`skills/localtokens/SKILL.md`](skills/localtokens/SKILL.md) — copy it to
`~/.claude/skills/localtokens/`.

## Design notes

- The agent supervises: local output is volume, not judgment. Bounded,
  self-contained tasks only — architecture decisions stay with the agent.
- Responses are capped (20 KB default) so a 12-file review cannot blow up
  the very context it is saving; per-file input is capped at 24 KB.
- A background pre-warm loads models on remote nodes at server start, so
  the first task of the day doesn't look like a hang.
- Path guardrail (exact directory segments + filename patterns) refuses
  `.ssh`, `.env`, keys, credentials. It is a guardrail against accidents,
  **not** a sandbox; contents travel over plain HTTP on your LAN.

Related work: [houtini-lm](https://github.com/houtini-ai/houtini-lm),
[mcp-local-llm](https://github.com/aplaceforallmystuff/mcp-local-llm),
[claude-code-router](https://github.com/musistudio/claude-code-router).
LocalTokens's differentiator is the parallel multi-node pool.

---

## Español

**Convierte tu máquina — o tu red local de equipos con ollama — en un
generador de tokens locales para agentes de código.** El agente delega
*tareas de procesamiento* acotadas (no prompts a modelos concretos):
LocalTokens decide modelo, nodo y reparto en paralelo con failover.

Las dos palancas de ahorro: los archivos se leen localmente (nunca pasan
por el contexto del agente) y la generación de volumen la hacen tus
nodos. El ahorro se mide en dos cuentas honestas por llamada
(`tokens_lectura` y `tokens_generacion`) en un registro JSONL.

Instalación: `pip install -e .`, luego registra `localtokens` en tu
cliente (arriba los tres comandos). Sin configuración usa
`localhost:11434`; con `~/.config/localtokens/config.json` listas todos tus
equipos (la primera URL = tu máquina de trabajo, que queda al final de
la rotación a propósito). Código y herramientas en español — nació en el
proyecto ECO, construido en español por diseño.

## License

MIT