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.

Related MCP server: local-executor-mcp

Tasks, not prompts

Install

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:

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 — 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, mcp-local-llm, 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