Touchmark: five characters that end session blur
Last week I ran twelve AI sessions in parallel. Builds, audits, research legs, a render pipeline. All twelve produced files. All twelve transcripts look the same in hindsight: scrollback, tool calls, a wall of green checkmarks.
Three days later I opened a handoff doc and could not answer the only question that mattered. Which session wrote this?
The answer cost an hour of archaeology through git logs and file timestamps. That hour is the tax. It is not a tooling gap you notice once. It is a recurring leak in every parallel workflow, and it compounds with every session you add.
1. The blur problem
Parallel sessions are anonymous by default. The harness gives each one an ID, but nothing surfaces it. Every terminal pane shows the same shape. Every artifact lands with no mark of origin.
Anonymous sessions make anonymous artifacts. A spec, a render, a stamped commit: once it leaves the session, its provenance is gossip. You either remember which pane made it, or you dig.
The fix is not a dashboard. It is a face. Give every session a mark that is cheap to compute, impossible to misread, and visible wherever the session touches the world. Then stamp that mark onto everything the session produces.
That is what touchmark does. The rest of this post is the mechanism.
2. The face
Every session already has an ID. A UUID, a slug, a key the harness assigned at boot. Touchmark takes that key, appends a salt, and runs it through :
material = session_key + "\n" + "touchmark-v1"
digest = SHA-256(material)
The digest is 256 bits. Useless to a human. So the code takes a reading of it and keeps five characters.
The alphabet is 32 symbols: digits 0 to 9, then most of the uppercase letters. Four letters are removed on purpose. I and L go because they misread as 1. O goes because it misreads as 0. U goes so a random code can never spell a word. What survives is an alphabet where every character is hard to confuse with any other, on any screen, in any font.
Five characters at five bits each gives 25 bits. That is 33,554,432 possible codes. The right way to judge that number is not as a global namespace. It is as a local working set, and there the math is kind. By the birthday bound, the chance of two sessions sharing a code is roughly n squared over 2 to the 26. One hundred live sessions: about 0.015 percent. One thousand: about 1.5 percent. You feel collisions at scales no single operator reaches, and you never feel them in a working week.
Why five and not four or eight. Four characters is 16 bits: a collision inside a busy month. Eight characters is 40 bits: overkill, and now the code no longer fits in glance memory. Five characters is the largest code a person holds without effort. You can say it over a call. You can spot it in a screenshot. You can type it without checking.
The code is deterministic. Same session key, same five characters, on any machine, in any language. The JavaScript port on the download page is pinned bit-identical to the Python CLI by a golden-vector fixture, so the face a browser shows you is the face the CLI stamps.
3. The grid
The code is for reading. The grid is for seeing.
The same digest drives a second rendering: an 8 by 8 grid of cells, where the hash places between 12 and 18 dots. Different session, different constellation. Same session, identical constellation, every time.
Why a grid at all, when the code already identifies the session. Because text costs attention and pattern costs almost none. Reading a code is foveal work: you stop, you fixate, you parse. Recognising a dot pattern is peripheral work. Your visual system flags same or different before you have decided to look. Twelve panes on a screen and your eye catches the odd grid out without a single act of reading.
The sparsity is tuned. With 64 cells, the dot count k is drawn from the range 12 to 18. Below 12 the faces converge: too few dots, and unrelated sessions start to look alike. Above 18 the grid turns to static: too many dots, and every face reads as the same noise. Inside the band, at k equals 15, the number of distinct grids is the binomial coefficient 64 choose 15, about 1.6 times 10 to the 14. The alphabet of faces is effectively inexhaustible next to any session set.
The grid and the code come from the same digest, so they never disagree. The code is what you type into a search box. The grid is what your eye catches first.
4. The stamp
A face nobody wears is decoration. The point of the mark is that it travels onto the work.
touchmark stamp <file> writes a block into a markdown artifact. A real specimen, minted from the session key touchmark-sample:
---
touchmark:
schema_version: 1
code: "31T2J"
session_key: "touchmark-sample"
harness: claude
minted_at: "2026-07-25T14:07:24Z"
---
touchmark verify <file> recomputes the code from the stamped session key and compares. Exit 0 when the mark matches. Exit 1 when it does not, or when the file carries no readable mark at all. That exit code is the whole API surface for automation: a gate in a pipeline is one line, and a forged or stale stamp fails closed.
touchmark scrub-check <file> runs the other direction. Exit 0 is clean. Exit 1 means the file carries touchmark patterns that should not leave the building: session keys, stamped marks, stray sigils in prose. This is the check that runs before anything publishes.
Now the artifact carries its own . The question from the opening, which session wrote this, stops being archaeology. It is a read of five characters in the file's own header, verifiable by anyone with the same one-file tool.
5. The contract
Notice what the software does not do. It does not watch your sessions. It does not intercept your saves. It mints, stamps, verifies, and scrubs when asked.
The sigil works because of a behavioral contract, not because of enforcement. Three rules:
- Mint on start. Every session gets its face at boot, before the first artifact exists. A session that mints late has already shipped anonymous work.
- Stamp artifacts. Anything meant to outlive the session carries the mark. Specs, handoffs, plans, publishable drafts. Ephemeral scrollback can stay anonymous; deliverables cannot.
- Scrub before publish. Public output gets checked. The mark is for your trail, not for leaking your session graph to strangers.
This is why the tool ships as a skill file and a single script rather than a daemon. The protocol is the product. The script just makes the protocol cheap to keep: one command per rule, each one fast enough that keeping the contract costs less than breaking it.
A protocol you keep beats a feature you configure.
6. The packaging
The distribution is a zip with an install.sh inside. Not pip, not a package registry, not a versioned dependency.
The reason is what the artifact actually is. pip installs code into an environment, and touchmark is not code you import. It is a convention wired into a harness: a skill the model reads, a statusline field, a stamp command in reach. install.sh places those wires where the harness expects them and proves the wiring with a self-test. A registry entry cannot do that, so the registry would be ceremony.
The reason for the adversarial scrub is what a grep cannot see. A token scan catches strings: paths, names, key patterns. It cannot catch a semantic fingerprint, text that names no secret yet describes something identifiable to anyone who knows the private context. The public build of this tool was reviewed with adversarial passes seeded with that context, and those passes caught lineage vocabulary that every regex called clean. Both layers ship in the box. Only one of them would have been enough.
The stance on the gift is stated plainly: as-is gift, no support, no roadmap. The declared envelope is macOS and Linux, Python 3.9 or later, Claude Code. Inside that envelope it is dogfooded daily and pinned by a parity gate. Outside it, you are on your own and the price reflects that.
The tool is free. The deep dive you just read is the whole pitch. If the blur problem is yours, the download is one email gate away:
Mark the session. Stamp the artifact. Trust the trail.