CODEX Codebook Suite

CODEX is a three-tool suite for exploring codebook ciphers — the kind of cipher used for diplomatic and military communication from the Renaissance through World War II. A codebook is a giant lookup table that maps words, phrases, and letter chunks to fixed-length code groups. The receiver uses a copy of the same codebook to translate the code groups back into plaintext.

Unlike a Caesar or Vigenère cipher, where the same key transforms every letter the same way, a codebook gives every token its own arbitrary code. That makes simple frequency analysis much harder — especially when the codebook includes homophones (several different codes for the same common word) and null codes (dummy groups that decode to nothing).

These three pages let you do the whole cycle: build a codebook, use it to encode and decode messages with an optional cipher layer on top, and then watch a simulated cryptanalyst attack the output to see how much can be recovered without the codebook.

The Tools

1. CODEX App

Encoder · Decoder

The main tool. Encode any plaintext into a stream of fixed-length code groups using a codebook generated from a seed phrase. Five layers of substitution are tried in order for each input chunk: phrases → words → trigrams → digrams → single letters. Optionally apply a superencipherment layer on top — additive (a separate random pad added to every code character, producing a true one-time pad), Vigenère, Caesar, monoalphabetic substitution, columnar transposition, or combinations — for extra protection. When Additive is selected, a pad field appears with Generate / Copy / Save buttons so you can mint a cryptographically random one-time pad and store it alongside the ciphertext for the recipient.

2. CODEX Maker

Standalone codebook generator

A dedicated codebook builder with finer-grained control than the App’s built-in maker. Choose word count (from ~1,000 up to all ~177,000 in the dictionary), homophone density per token type, code group length and character set (lowercase, uppercase, digits), null code count, and optionally upload your own word list. Exports JSON or TSV files that the App can import. Also generates and downloads a companion additive pad (1,000 to 100,000 random base-62 characters) so a sender and receiver can share a complete one-time-pad kit — codebook plus pad — in one session. A security-guidance panel estimates how much ciphertext your settings will resist before falling to frequency analysis.

3. CODEX Decryptor

Automated cryptanalysis demonstrator

Paste output from the App and watch a seven-step analyst pipeline attack it: format detection, cipher fingerprinting, cipher-layer removal, group frequency analysis, best-guess mapping, a context attack using word segmentation and bigram analysis, and finally a combined reconstruction. Each panel shows the key statistics with reference ranges and longer “how it works” explanations. A long companion section, Beyond Frequency Analysis, covers the techniques (cribs, n-gram context, homophone clustering, language models) that a real analyst would bring to bear.

Suggested Workflow

1. Use the Maker to generate a codebook with the settings you want to study (e.g. 3,000 words, 1x homophones, no nulls). Download as JSON.

2. Open the App, import the JSON, paste in a message of a few hundred to a few thousand words, and encode it (start with cipher: None to make the next step simpler).

3. Copy the ciphertext into the Decryptor and see how much the analyst recovers. Then go back to the Maker, turn homophones up to 3x or 5x, regenerate, re-encode the same message, and see how the attack degrades.

4. Repeat with a superencipherment layer enabled in the App (Vigenère is a good start) to see whether the Decryptor can spot and strip it.

5. Try the additive layer. Select “Additive” from the Superencipherment dropdown in the App, click Generate in the pad field to mint a random one-time pad, click Save to download it, then encode. Paste the ciphertext into the Decryptor: it will mark additive as a statistical tie with Vigenère; switch the cipher override to “Additive” and read the explanation of why a single additive-enciphered message is effectively unrecoverable without the pad.

6. For the most realistic re-enactment, generate both the codebook and a long companion pad from the Maker. Share both files with a friend (one playing sender, one playing receiver), and use one chunk of the pad per message.

Things to Try

Generate two codebooks with the same seed but different group lengths. Encode the same message with each. Does the ciphertext change in any structural way besides group length?
Encode a 200-word message with no homophones and no cipher layer. How many tokens does the Decryptor recover? Now try 2,000 words.
Crank homophones to 5x and re-encode the same message. Does the Decryptor still find common function words like “the” and “of”?
Turn on null insertion at 20% density. Watch the Decryptor’s frequency chart for the characteristic flat plateau of low-frequency groups that flags nulls.
Try the same plaintext with different cipher layers and see which ones the Decryptor identifies correctly.
Encode the same short message twice using additive superencipherment with the same pad (just copy the pad from the first encode and paste it back for the second), then paste both outputs into a single Decryptor session. The combined frequency profile starts to leak information — this is the “depth” attack that broke real one-time-pad systems in WWII (VENONA).
Build a custom codebook from a word list in another language (or a domain-specific vocabulary like chemistry terms) and see how the frequency analysis behaves when the underlying plaintext doesn’t match English letter frequencies.

How CODEX Fits Into Crypto History

CODEX is a deliberate simplification of the diplomatic and military codebooks that dominated secret communication from the 1500s through the 1940s. Real codebooks had thousands or tens of thousands of entries, were printed and bound as physical volumes, and were sometimes overlaid with an additional cipher layer called a superencipherment — almost exactly the structure CODEX models. For the historical background and the specific codes that shaped 20th-century history, see Codebooks: A History and The Zimmermann Telegram in the Early Modern Cryptanalysis section.

Disclaimer: these pages are educational demos provided as-is, with no warranty of any kind. The author is not responsible for any consequences arising from their use.

Send comments and bug reports to chris@chrisspackman.com.

Version 0.3 — Last updated: 2026-05-25

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.