# gremlord

> A thin local router that wraps Claude Code to run on any model provider with budget caps, LLM-triaged tier routing, and per-token spend tracking.

gremlord is an MIT-licensed, open-source CLI tool written in Go that wraps Claude Code in a local router, letting developers run the unmodified Claude Code harness against Anthropic, OpenAI, xAI, Ollama, vLLM, OpenRouter, or any OpenAI-compatible endpoint. It installs in one command, requires no daemon, and keeps Claude Code auto-updating on its own schedule. The project was formerly named "agentic" and migrated to the gremlord name; the latest release as of September 2026 is v0.1.6-gremlord.

## What It Is

gremlord sits between Claude Code and model providers by intercepting `ANTHROPIC_BASE_URL` — an officially supported gateway hook — and acting as a local proxy. Anthropic traffic passes through byte-faithfully; all other providers (OpenAI dialect, xAI, Ollama, vLLM, OpenRouter) go through full request/stream translation. The result is the same Claude Code TUI, tools, and auto-update behavior, but with the model layer swapped out and every token metered, priced, and checked against configurable budgets.

## How the Router Works

The architecture is deliberately minimal: a static Go binary with no persistent daemon. The first `gremlord` session binds the router port and serves all concurrent sessions; when it exits, another running session takes over within seconds. Model names are user-defined aliases in `config.yaml`, and anything starting with `claude-` passes through to Anthropic untouched.

Key routing mechanics include:
- **Two-dialect support**: Anthropic passthrough and full OpenAI-dialect translation for all other providers
- **LLM-classifier tier routing**: `--model auto` uses a cheap classifier (e.g., haiku) to assign each turn to a `deep`, `standard`, or `light` tier — sticky for the whole turn, no mid-flight model flips
- **Task specialist overrides**: A fixed label set (`implementation`, `sql_data`, `debugging`, `code_review`, `architecture`, `security_review`, `critical_review`) adds a second routing dimension without an extra classifier call
- **Size-aware routing**: Requests are checked against each candidate model's declared context window before routing; a request too large for all configured models is refused before reaching any provider
- **Context scaling**: Each model's real `context_window` (and optional `effective_context`) is declared so Claude Code's auto-compact fires at the right moment for 32K local models and 400K cloud models alike

## Spend Tracking and Budget Gates

Every routed API token is logged to a local SQLite database with pricing applied at request time. `gremlord cost --by model` breaks spend down by model, profile, or session. Hard-stop budgets (daily, weekly, monthly) are configurable globally or per profile; when a cap is hit, the router refuses the next request with a message in the TUI — in-flight responses are never cut. A live statusline registered by `gremlord setup` shows session and daily spend in real time.

## Subagents, Sessions, and CLI Delegation

- **Subagents on any model**: `gremlord agents sync` writes one subagent definition per configured model alias into `~/.claude/agents/`, making any alias selectable by name (e.g., `subagent_type: "gremlord-qwen"`) with full routing and budget enforcement
- **Session peer discovery**: `gremlord peers` matches Claude Code sessions by both auto-derived session name and project directory, surfacing ties rather than guessing
- **CLI delegation**: A `cli` provider type can hand whole tasks to a locally installed Codex or Grok CLI under the user's own subscription login; gremlord never reads or proxies the OAuth token

## Update: v0.1.6-gremlord

The latest release (v0.1.6-gremlord, published September 10, 2026) fixes `cost --receipt` to honor the `--since` flag. The project was renamed from "agentic" to "gremlord" in this release cycle; `gremlord setup` and `gremlord agents sync` handle migration from `~/.agentic` to `~/.gremlord`, copying config and cost history while leaving the originals intact. Recent additions include the `gremlord eval` paired model evaluation feature (experimental), Auto Goal loop detection, deferred tool loading re-enablement, and estimator calibration for translated model token counts.

## Tradeoffs to Know

Non-Anthropic models work through translation, but Claude Code's prompts and tool patterns are tuned for Claude — the project's own documentation notes they are "clunkier in the main loop" and better suited as cheap workhorses for background tasks and subagents. Specific gaps include no `cache_control` breakpoints on OpenAI-dialect backends, display-only thinking blocks, unavailability of Anthropic server tools (web search, code execution) on translated models, and token counting that deliberately overestimates by ~15% to prevent context overflow. The tool is explicitly positioned for a single developer, not a team gateway — for team deployments, the README points to LiteLLM as a more mature option.

## Features
- Multi-provider routing: Anthropic, OpenAI, xAI, Ollama, vLLM, OpenRouter, DeepSeek, Groq
- LLM-classifier tier routing (deep/standard/light) with per-turn sticky decisions
- Task specialist overrides for implementation, debugging, code review, architecture, security review, and more
- Size-aware routing that checks context window before picking a model
- Context scaling per model with configurable effective_context
- Per-token spend tracking in local SQLite database
- Hard-stop daily, weekly, and monthly budget caps (global and per profile)
- Live spend statusline in Claude Code TUI
- gremlord cost --by model/profile/session spend reports
- Subagent definitions auto-generated per model alias
- gremlord peers session discovery by name or project directory
- CLI delegation to Codex or Grok CLI under user's own subscription
- Paired model evaluations with optional blinded judge (gremlord eval)
- Auto Goal loop detection nudging Claude Code toward ScheduleWakeup or /loop
- Deferred tool loading re-enablement (ENABLE_TOOL_SEARCH)
- Estimator calibration for translated model token counts
- No daemon — leader election over a fixed port
- Profile system bundling model, small_fast model, tier mappings, and budgets
- gremlord context command showing true vs reported token trajectory
- Migration support from agentic (predecessor tool)

## Integrations
Claude Code, Anthropic API, OpenAI API, xAI (Grok), Ollama, vLLM, OpenRouter, DeepSeek, Groq, Codex CLI, Grok CLI, clauder (persistent memory MCP server), LiteLLM (compared, not integrated), SWE-bench (eval harness), Docker (for SWE-bench evals)

## Platforms
LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.1.6-gremlord

## Links
- Website: https://gremlord.com
- Documentation: https://github.com/gremlord/gremlord#readme
- Repository: https://github.com/gremlord/gremlord
- EveryDev.ai: https://www.everydev.ai/tools/gremlord