agentleFS
BI-BlitzerBI-Blitzer/tandem-tokens/CLAUDE.md

tandem-tokens

CLAUDE.md1 starsChanged 4 months agoMITView on GitHub

This project is ollamaq: a harness that offloads bulk, mechanical, or generate-and-test work to local Ollama models so premium Claude tokens are spent only on orchestration and the final reduce/cleaning pass. Read PLAN.md for the architecture; README.md for commands. Worker output stays on disk. You read only results/<job_id>/digest.md (hard- capped at 8 KB: stats, samples, failures, cloud cost avoided when pricing is configured, and GPU energy Wh / $ / CO₂ when metered). Pull results/<job_id>/merged.jsonl into context only when you…

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If using the daemon, make sure one is running: ollamaq daemon (one per machine).

    line 47
  2. Very specific:

    Prefer the CLI for batch work.

    line 69

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

ollamaq — delegation policy for Claude Code

This project is ollamaq: a harness that offloads bulk, mechanical, or generate-and-test work to local Ollama models so premium Claude tokens are spent only on orchestration and the final reduce/cleaning pass. Read PLAN.md for the architecture; README.md for commands.

The core contract (do not break)

Worker output stays on disk. You read only results/<job_id>/digest.md (hard- capped at 8 KB: stats, samples, failures, cloud cost avoided when pricing is configured, and GPU energy Wh / $ / CO₂ when metered). Pull results/<job_id>/merged.jsonl into context only when you are deliberately running a reduce/clean pass over it, and prefer a slice. Never echo bulk worker output back into the conversation. After harvest, prefer ollamaq score for cumulative savings (cloud $ avoided − local energy $).

When to offload

Offload when the task is (a) ≥ ~20 similar independent items, AND one of:

  • mechanical — clean / normalize / extract / classify / summarize / boilerplate codegen over many rows, files, or records (use map mode), or
  • generate-and-test — produce candidates in volume and score them with a scriptable verifier (use gen_test mode), or
  • staged — a cheap model triages, an expensive model handles only the flagged subset (use pipeline mode).

When NOT to offload

  • A single hard reasoning problem (no map phase to parallelize) — do it yourself.
  • Anything needing repo-wide context the local model won't have.
  • Anything where a wrong answer silently corrupts data and there is no verifier.
  • Fewer than ~20 items — the setup/queue overhead exceeds the savings; just do it.

Routing (from config/models.yaml)

model: "auto" routes by task_tag: clean/extract/code → qwen2.5-14b-16k, summarize → hermes3-8b-32k (long context), classify → gemma2:9b (fast), generate → qwen3:8b. Default model is qwen2.5-14b-16k. Never target gemma2:27b (spills to CPU on the 16 GB card) unless the user explicitly opts in.

Workflow

  1. /offload — turn the request into a validated job spec, submit it, get a job id + rough ETA. For a small batch use ollamaq run <spec> --wait; for a large or long one use ollamaq submit <spec> and let the daemon drain it.
  2. If using the daemon, make sure one is running: ollamaq daemon (one per machine). After submitting, don't poll tightly — use /loop or a scheduled wake-up (≥20 min) to check ollamaq status.
  3. /harvest — when jobs are done, read their digests, and run the Opus/Sonnet reduce/clean pass over the residue the local model got wrong (guided by the digest's failures/samples), then write the final artifact. Cross-client policy also lives in skills/hybrid/SKILL.md and AGENTS.md (Codex/Grok/Cursor). Report energy lines from the digest when present.

Auto-offload nudge (hook)

A UserPromptSubmit hook (hooks/auto_offload.py, registered in .claude/settings.json) scans each prompt and, when it looks like a bulk mechanical data task, injects a [tandem-tokens] suggestion naming the likely mode. It surfaces the opportunity — you still decide whether to /offload. It stays silent on ordinary prompts. (A hook can't auto-execute a job: a prompt isn't a validated job spec.)

MCP tools (alternative to the CLI)

An MCP server (.mcp.json) exposes ollama_quick (one-shot, output-capped — for tiny delegations only), queue_submit, queue_status, queue_digest. Prefer the CLI for batch work; ollama_quick is for a single small prompt whose short result is fine to bring back into context.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.