GitHub - Tetrahedroned/Agent-Braille: Deterministic 8-bit machine-to-machine protocol for AI agent state. ~92% fewer state-tracking tokens on real Claude Code sessions, a proven single-bit-error-safe command code, fully reproducible. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
Tetrahedroned
Agent-Braille
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>1 Commit<br>1 Commit
ab1
ab1
bench
bench
paper
paper
tests
tests
.gitignore
.gitignore
AB-1_CANONICAL.md
AB-1_CANONICAL.md
CITATION.cff
CITATION.cff
LICENSE
LICENSE
README.md
README.md
View all files
Repository files navigation
Agent Braille (AB-1)
A measured agent-state protocol. Every claim here was tested, including the<br>ones that failed; the failures and the fixes are in the open.
AB-1 is a deterministic 8-bit semiotic layer over the Unicode Braille<br>Patterns block (U+2800–U+28FF) for machine-to-machine communication of AI<br>agent state. One code point encodes one machine state across eight orthogonal<br>dimensions of agency. This repository is the reference implementation, the<br>benchmark harness, and the honest evidence ledger behind the paper.
The code is the canonical specification. Where the prose and the code<br>disagree, the code wins.
What survives measurement (and what didn't)
This project's credibility is the arc, not a list of wins:
Atomicity — claimed, falsified, fixed with receipts. The premise that<br>Braille cells are atomic single tokens is false on every stock<br>production tokenizer (~3 tokens/cell on cl100k/o200k; BERT maps all 256 to<br>[UNK]). AB-1 ships a vocabulary extension that makes every cell exactly<br>one token, 256/256, exact round-trip, measured before/after.
Hardened lexicon — proven. Exhaustive enumeration over all 256 states<br>and all single-bit flips: a single-parity-check command code (128<br>commands, distance 2) is single-error detecting with zero<br>unvetted→audited promotions; an extended Hamming [8,4,4] code (16<br>commands, distance 4) is single-error correcting. Tokenizer- and<br>model-independent.
Token efficiency — triangulated on public reproducible data. Against a<br>steelman (delta-encoded JSON, same emit-on-change discipline), AB-1 carries<br>agent state tracking in ~92% fewer tokens on stock cl100k/o200k,<br>~97% with the extension . Converged across a synthetic sweep, a private<br>agent ledger, and the public Crucible Claude Code session log (anyone can<br>reproduce the public number).
Separability — a scoped probe, explicitly NOT load-bearing.<br>Characterized on three axes (quant depth F16→Q2_K, size 1B→14B, controlled<br>cross-family at 3B/F16). No stock model robustly encodes AB-1 bit-structure<br>at any size/quant/lineage; degradation appears only at the 2-bit extreme.<br>This motivates the model-independent mechanisms; it is not the spine.
Security syntax-firewall — an explicit hypothesis, not a result.
Layout
ab1/ reference implementation (zero-dependency core)<br>core.py 8-bit encoding, the bit-table convention<br>dsp.py Differential State Protocol (emit-on-change)<br>crc.py CRC-8 checksum cell<br>lexicon.py hardened command codes + Hamming analysis<br>tokenizer.py the vocabulary extension (atomicity by construction)<br>bench/ reproducible experiments; bench/results/FINDINGS.md is<br>the full honest ledger<br>tests/ spec-anchor + roundtrip tests<br>AB-1_CANONICAL.md the consolidated specification (CC-BY-4.0)<br>paper/ the arXiv paper (LaTeX) + bibliography
Reproduce
python -m venv .venv && . .venv/bin/activate<br>pip install tiktoken transformers # tokenizer experiments<br>python tests/test_core.py # 5/5 spec + roundtrip<br>python bench/tokenizer_parity.py # atomicity (negative result)<br>python bench/extension_proof.py # the fix, before/after<br>python bench/lexicon_proof.py # the proof (deterministic)<br>python bench/token_reduction.py --trace bench/results/crucible_trace.json
Separability experiments (bench/quant_*.py, bench/cross_family.py)<br>require local GGUF models and a GPU; they self-persist results to<br>bench/results/ and survive a mid-run crash (incremental...