coldhat 0.1.0

╔════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                                                            ║
║                  ██████╗ ██████╗ ██╗     ██████╗ ██╗  ██╗ █████╗ ████████╗                 ║
║                 ██╔════╝██╔═══██╗██║     ██╔══██╗██║  ██║██╔══██╗╚══██╔══╝                 ║
║                 ██║     ██║   ██║██║     ██║  ██║███████║███████║   ██║                    ║
║                 ██║     ██║   ██║██║     ██║  ██║██╔══██║██╔══██║   ██║                    ║
║                 ╚██████╗╚██████╔╝███████╗██████╔╝██║  ██║██║  ██║   ██║                    ║
║                  ╚═════╝ ╚═════╝ ╚══════╝╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝                    ║
║                                                                                            ║
║                            will another model keep your rules?                             ║
║                                                                                            ║
╚════════════════════════════════════════════════════════════════════════════════════════════╝

coldHat puts your working rules on any AI chat in one line. Type this into Claude, ChatGPT or Grok:

open sesame coldhat.f-keys.com/u/vince-gonzalez

The assistant reads the hat, answers with its hat code to prove it read it, and works by those rules for the rest of the chat. Live at coldhat.f-keys.com.

Recorded 2026-10-11 in Claude (incognito) and Grok (private). Both quote 33963b16, the frontier hat's live code, which they can only know by reading the page. Models keep their own copy of a page for a while, so after an edit the code they quote can trail the live one. A playful version, with the main hat's joke opener, is in docs/demo.gif.

You want to	Do this
Wear a hat	type open sesame coldhat.f-keys.com/u/<github-user>
Wear one in a chat that can't browse	Copy hat on coldhat.f-keys.com, then paste
Make your own	write it at coldhat.f-keys.com/make, or start from coldhat-starter
Bring the instructions you already keep for Claude, ChatGPT, Grok or Cursor	coldhat.f-keys.com/import: shared rules become your hat, the rest become sets you load by name
Add it to an app once	add the MCP connector https://coldhat.f-keys.com/mcp (tool wear_hat, prompt open_sesame)

Try one now. Starter hats anyone can wear:

Hat	Type this
Code reviewer: verdict first, findings by severity with line, failure and fix	open sesame coldhat.f-keys.com/u/vince-gonzalez/reviewer
Grant writer: rubric first, every number sourced, every limit met	open sesame coldhat.f-keys.com/u/vince-gonzalez/grants
Plain-English editor: shorter, clearer, still your voice	open sesame coldhat.f-keys.com/u/vince-gonzalez/editor
Frontier: mechanical register, rules over manners	open sesame coldhat.f-keys.com/u/vince-gonzalez/frontier

A hat is a hat.md in a public GitHub repository named coldhat, so only its owner can change it. Extra hats go in hats/<name>.md at /u/<user>/<name>. Dated facts under ## Status (- label: value · as of YYYY-MM-DD · check after N days) are checked by the server against today's date, and the assistant asks about any that have gone stale. Which chat boxes work was measured, not assumed.

Edit your hat in your own editor

pip install -e .                 # once, from a clone of your coldhat repository
coldhat check hat.md             # the same checks the server and the web editor run
coldhat publish hat.md -m "Won the grant"

publish checks the file, commits only that file, pushes, and waits until the live hat code matches your local one.

Under the hood

• worker/: the Cloudflare Worker behind coldhat.f-keys.com: hat pages, the editor, llms.txt, the MCP server. Edge-cached, rate-limited, every name checked before GitHub is asked. 53 tests run in workerd.
• src/coldhat/: the Python toolchain for authoring hats as cards, locking them, and measuring them with evals across models.

hat (files you own)  ->  compile  ->  hat.md | Claude skill | OpenAI bundle | paste file
                                       |
                     evals: bait questions, graded  ->  runs (fingerprinted)
                                       |
                     tune: edit cards, re-run, compare  ->  fine-tuning JSONL

A hat (as cards)

hats/vince/
  coldhat.json   manifest: id, version, activation phrases, file digests
  hat.md         brim: activation table and precedence
  head.md        voice, register, example answers
  footer.md      the check before every answer
  cards/         the body: one rule per file

A card:

---
id: work-premise
load: always
tags: irreversible public account destructive force push premise verify command
---
# State the premise before anything irreversible

Before anything irreversible, public or touching an account, state the premise...

load: always cards sit in the instructions. load: retrieve cards are fetched when a task calls for them, so the hat can grow without filling the context.

Activation. open sesame puts on head, body and footer. open sesame head puts on the voice alone. hat off removes it.

Integrity. coldhat lock records a sha256 for every file. A hat whose files differ from the lock refuses to load. The fingerprint is a hash over all of them, and every eval run records it, so a score always names the exact hat that earned it.

Authority. A hat describes how to work. It grants no tools, permissions or access; the host's own rules and the user's live instructions outrank it.

Delivery modes

Mode	Instructions carry	The other cards arrive
inline	every card	already there
tool	always-on cards and a titled list of the rest	the model calls coldhat_lookup
rag	always-on cards	the host attaches matching cards to each message

Retrieval is BM25 over card titles, tags and bodies; standard library only and deterministic.

Commands

pip install -e ".[all]"

Command	What it does
coldhat lock HAT	record file digests
coldhat validate HAT	check structure and lock
coldhat inspect HAT	activation, always-on cards, instruction size per mode
coldhat retrieve HAT "query"	which cards a task pulls
coldhat build HAT	write dist/<id>/: MASTER.md, a Claude skill folder, OpenAI bundles
coldhat run HAT SUITE --provider anthropic|openai	put the hat on a model and run every case
coldhat sheet SUITE --out replies.json	print the questions for a chat window and write a blank replies file
coldhat grade HAT SUITE replies.json --label NAME	grade replies collected by hand
coldhat report RUN [RUN]	show a run, or compare two case by case
coldhat agree HAT RUN_A RUN_B	judge whether two models took the same positions
coldhat export HAT --suite SUITE [--run RUN]	write chat-format fine-tuning JSONL

run and grade exit 0 when every case passed, 1 when any failed, and 2 when none failed but some could not be fully graded.

Credentials come from each SDK's own environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY). Name the OpenAI model with --model or COLDHAT_OPENAI_MODEL. Claude defaults to claude-opus-5-5, with the API's refusal fallback enabled.

Evals

A suite is a JSON list of cases. Each case is a prompt, usually a bait question built to tempt the model into breaking one rule, and a list of checks:

Check	Passes when
regex	the pattern is in the reply
not_regex	the pattern is absent
max_words	the reply is at most n words
judge	a grading model says the reply meets the rubric

voice_bans run on every reply: announced honesty, filler words, a closing "want me to...?" menu.

A judge check with no judge model is not_run. A judge that errors is error. Either one makes the case incomplete, which is never counted as a pass. An empty reply fails outright, since it would otherwise pass every "must not contain" check.

Tuning

1. Run the suite on a model.
2. Read the failures. Each one points at a card, the head, or a missing card.
3. Edit, coldhat lock, run again.
4. coldhat report OLD NEW shows which cases flipped and confirms the hat changed.

Once a hat scores well, coldhat export turns the head's example answers, the suite's reference answers and the replies from judged, passing runs into training data. It only takes replies from runs of the current fingerprint, so behavior from an older hat cannot leak in.

Chat-window run

1. coldhat build hats/vince and copy dist/vince/MASTER.md into the chat.
2. coldhat sheet evals/vince.json --out claude.json, send each question in that chat, paste each reply into the file.
3. Repeat in a second model's chat with --out gpt.json.
4. coldhat grade hats/vince evals/vince.json claude.json --label claude, same for gpt.json.
5. coldhat report on both runs, and coldhat agree to see whether they took the same positions.

Security

A hat is instructions, not a credential, and open sesame is not a password. Commits pass a secret and private-term scrubber before they exist, CI runs it again with gitleaks over the full history, hats refuse to read outside their own folder, and the only tool a hat exposes is a read-only search over its own cards. Details and limits are in SECURITY.md.

To install the commit hook in a clone:

git config core.hooksPath .githooks
git config scrub.privateTerms /path/to/your/private-terms.sha256

python tools/scrub.py --hash WORD prints the line to add for a term.

Tests

python -m unittest discover -s tests

No network and no keys. Each gate is tested on input built to pass it and input built to fail it, and both provider adapters are driven through their tool loops with fake clients.

---

╔════════════════════════════════════════════════════════════╗
║                                                            ║
║      ███████╗      ██╗  ██╗███████╗██╗   ██╗███████╗       ║
║      ██╔════╝      ██║ ██╔╝██╔════╝╚██╗ ██╔╝██╔════╝       ║
║      █████╗  █████╗█████╔╝ █████╗   ╚████╔╝ ███████╗       ║
║      ██╔══╝  ╚════╝██╔═██╗ ██╔══╝    ╚██╔╝  ╚════██║       ║
║      ██║           ██║  ██╗███████╗   ██║   ███████║       ║
║      ╚═╝           ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚══════╝       ║
║                                                            ║
║               ·   C  R  E  A  T  I  V  E   ·               ║
║                                                            ║
║          ────────────────────────────────────────          ║
║                                                            ║
║                      Vincent Gonzalez                      ║
║                         f-keys.com                         ║
║                 ORCID 0009-0005-3640-014X                  ║
║                                                            ║
╚════════════════════════════════════════════════════════════╝

Part of F-Keys — independent hardware, software and internet products. See the working log and live status.