convez.ai
SkillAutomaçãoAvançado
TheColliery

CoalTipple

TheColliery/CoalTipple

Delega tarefas baratas para economizar tokens; escala complexas para qualidade.

Ver no GitHub
BomPluginScore · de 0 a 100

Roteador de modelos e esforço para Claude Code que delega tarefas grandes e baratas para camadas mais econômicas e escala problemas complexos para modelos mais fortes. Otimiza consumo de tokens mantendo qualidade através de decisão nativa sobre qual modelo executar cada subtarefa.

Instalação

$npx convez-ai TheColliery/CoalTipple

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
9
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 1 dia
Versão
v1.8.10
Issues abertas
1
Contribuidores
1

Casos de uso

  • Otimizar custos de processamento em workflows multi-modelo
  • Delegar tarefas mecânicas grandes para Haiku economizando tokens
  • Escalar problemas complexos para Opus garantindo qualidade de saída
  • Implementar inteligência de roteamento nativa em agentes Claude Code

Veredito

Ferramenta especializada e bem arquitetada para otimizar custos em Claude Code, resolvendo o dilema prático de quando escalar ou delegar. Requer profundo entendimento do ecossistema Claude Code; validação ao vivo 2.1.143, mas requer reverificação em versões mais recentes.

README

A tradução para o português deste README ainda está na fila.

🚂 CoalTipple

A model/effort router for Claude Code — delegate a task you can do but that is large and cheap down to a cheaper tier to save tokens, and hand a task beyond your reach up to a stronger tier for quality.

version license SKILL.md Claude Code status

Changelog · Security · Privacy · Releases

Part of TheColliery — sibling: CoalMine.

✅ Live -- in real use on Claude Code. The v1 core is validated on Claude Code 2.1.143 and active; the conductor hook fires a routing forcer on every prompt.

[!CAUTION] Claude Code only. CoalTipple's routing only actuates where an agent can pick a spawned worker's model + effort. Today that is Claude Code. Antigravity does NOT work -- its subagents inherit the parent's model (no per-spawn model parameter, no separate effort knob), so routing cannot actuate there. Other platforms (Codex, Cursor, ...) are under monthly review.


🚂 What CoalTipple is

A tipple is the sorting-and-rail-switching station of a coal mine. This tool switches rails for prompts across models (alongside CoalMine).

You are main. CoalTipple decides, per task, whether to:

DirectionWhenWhy
delegate-DOWNTask is mechanical and largeA cheaper tier does the bulk → saves tokens
escalate-UPTask is beyond the current tier's competenceA stronger tier does it right → protects quality
stay (route OFF)Task is small / no valid rankingBypasses routing to prevent overhead

Routing logic lives inside SKILL.md — the model reads and routes natively. No background daemon.


🤖 Compatibility

  • Claude Code (validated live on v2.1.143): Built Claude-Code-first and run end-to-end across all model tiers (Haiku, Sonnet, Opus). Re-verification on newer CC (2.1.18x) is in progress — the validated baseline stays 2.1.143 until confirmed the skill does not break.
  • Routing actuates on Claude Code only: CT needs a platform where an agent can pick a spawned worker's model + effort. CC's Agent/Task tool takes a model param -- that is the requirement.
  • Subagent-capable != qualifies: a platform can spawn workers yet give the agent no model choice (e.g. Antigravity, where the worker inherits the parent's model). There CT does not cleanly self-degrade -- a weak main hallucinates a delegate-down it cannot perform -- so CT is gated to CC. Other platforms (Cursor, Codex) are under monthly review.

🚀 Installation

Claude Code plugin

claude plugin marketplace add TheColliery/CoalTipple
claude plugin install coaltipple@coaltipple
# Restart Claude Code to load the /coaltipple commands (stats | off | memory)

Optional per-project config override: <project>/.claude/.coaltipple.json.

Verify (from clone)

node scripts/verify.mjs   # validates config, schemas, plugin files
node scripts/test.mjs     # runs zero-dependency unit tests

🎛️ The Two Knobs

Routing adjusts two independent knobs (always raise effort before tier):

KnobAxisScale
TIERcorrectness — which modelCoarse (low < mid < heavy < reasoning)
EFFORTsize — output volume / iterationFine-grained (low → max)
  • TIER tracks difficulty/sensitivity; EFFORT tracks output size. A short cryptographic function wants a high tier but low effort. A large mechanical template wants a cheap tier but high effort.

The qualityBar Staircase

qualityBar (0–100, default 60) defines the acceptable quality threshold:

  1. The task's grade picks the starting tier (cheapest possible).
  2. The worker runs, and output is verified against the task contract.
  3. Passes → done. Fails → climb one rung. Out of attempts/fails hard → jump to top tier.
  • Tune qualityBar by risk: raise (~85) for critical logic; lower (~45) for quick drafts.

🛡️ Routing the Work Safely

  • No Down-Delegation for Sensitive Tasks: Cryptography, auth, payments, and security paths are forced to the heavy tier based on keywords. They never fall to cheap tiers, even under quota limits.
  • Overhead Floor: Tasks below delegateMinLines (default 120) stay on main to avoid spawn overhead.
  • Prose Preservation: User-facing writing and translation stay on main to protect voice.
  • Verify, Do Not Eyeball: Output merges require passing objective checks (qaOnMerge: strict/standard/off).
  • Workers are Leaves: Workers cannot spawn nested subagents; they return results to main.

Damage Control

  • Isolation: Uses git worktree-isolation (or local .claude/.coaltipple/proposed/ sandbox with state.json journaling) to protect files from mid-run failures.
  • Rate Limits: Automatically falls back to the next available tier on limit-hits, but never below a sensitive task's minimum tier.
  • Side Effects: Commands with external side-effects (e.g. bash mutations, commits) are never delegated.

🔒 The Lock — Safe Routing States

The Lock guarantees CoalTipple is only ever in one of two states: routing correctly or routing off.

  • Always Buildable: Uses self-introspection, falling back to an alias floor, then a stub. Unknown models default to heavy.
  • Validity-Gated: Checks ranking schema, hash, and completeness before writing.
  • Fails Safe: Bypasses routing if the model ranking is broken.
  • Cached: Ranking cache (ranking.json) is trusted until rankingRefreshDays (default 30).

🧠 Memory Anchor

Workers start context-fresh. A memory anchor file gives a fresh worker project context.

  • If contextFiles is empty, CoalTipple auto-loads CLAUDE.md / AGENTS.md.
  • Offers once to set up an anchor on new projects. Manage manually via /coaltipple memory.

⚙️ Configuration (.coaltipple.json)

Shops zero-config with optimal defaults. Precedence: project override → global config → schema default.

Key settings (see scripts/lib/config-schema.mjs for the full SSoT schema):

KeyTypeDefaultWhat it does
enableRoutingBooleantrueMaster routing switch
modeEnumautoDirection: delegation (down) | escalation (up) | auto | off
qualityBarInteger 0–10060Quality threshold for the staircase
maxTotalAttemptsInteger 1–52Staircase attempt budget before jumping to top tier
delegateMinLinesInteger120Minimum lines threshold for down-delegation
qaOnMergeEnumstandardMerge verification rigor (strict | standard | off)
rankingModeEnumautoauto (LLM introspects) | manual (uses modelTiers pins)
modelTiersObjectunsetOptional manual model-to-tier mappings

Configurator CLI

node scripts/configure.mjs --list                        # show merged config
node scripts/configure.mjs --qualityBar 85               # update global qualityBar
node scripts/configure.mjs --project --mode delegation   # write project override
node scripts/configure.mjs --help                        # view all schema-driven flags

📊 Benchmark — Routing & Output Correctness

We evaluate both routing decisions (the Lock and probe tasks) and final output correctness:

Routing Decisions (Measured 2026-06-14/15, CoalTipple v1.0.3):

Probe TaskWhat it EvaluatesPass Rate
A: Delegate-downLarge, mechanical tasks offloaded correctly7 / 7 tiers
B: Sensitive safetyCrypto/auth tasks stay on heavy/main tier7 / 7 tiers
C: Escalate-upTasks beyond main's tier escalate for quality7 / 7 tiers
D: Context routingRight model capacity mapped correctly7 / 7 tiers
Lock rankingCorrect tier order classification5 / 7 tiers

Output Correctness (+1 Rung Escalation):

Main ModelEscalation RungTask Domains (Crypto, Proof, Research, Legal, Voice)Output Pass Rate
Haiku➡️ Sonnet5/5 tasks100%
Sonnet➡️ Opus5/5 tasks100%
Opus 4.6➡️ Self-inline5/5 tasks100%
Opus 4.7➡️ Self-inline5/5 tasks100%

Total: 20/20 PASS deliverables generated correctly.

The full output-quality harness (tasks, scorer, results) lives in the series umbrella at TheColliery/.github/benchmarks/CoalTipple.


🧭 Part of TheColliery

CoalTipple shares its engineering doctrine with CoalMine: Phoenix-13 hooks (zero-dependency, no network, fail-silent, no child processes, deterministic), single-source-of-truth config schemas, and a strict no-overkill discipline.

📄 License

MIT License. See LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados