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 an analyst’s pipeline attack it: format detection, cipher fingerprinting (a Vigenère layer is found by its period and stripped without the key), group frequencies, and a context attack that identifies the codes the text’s shape gives away: the space, the capital-letter marker, the commonest punctuation mark and “the”. The real progress comes from the interactive crib attack: name words you expect in the message and the Decryptor finds where their spelled-out shape fits, solving the cribs as a system and handing back letter codes. A built-in worked example shows a short dispatch going from unreadable to half recovered in a few clicks. The long companion section, Beyond Frequency Analysis, is honest about what frequency counting cannot do against a codebook and what a real analyst did instead.

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. Expect the structural codes (space, capital marker, punctuation, “the”) and not much more — that is the real limit of frequency analysis against a codebook, and the page explains why. Then enter a few names from your message as cribs in panel 6½ and watch the reconstruction fill in. Go back to the Maker, turn homophones up to 3x or 5x, regenerate, re-encode the same message, and see how even the structural identifications degrade.

4. Repeat with a superencipherment layer enabled in the App (Vigenère is a good start). The Decryptor finds the key length from the period in the code characters and aligns the layer away without ever learning the key; a Caesar shift or substitution it simply ignores, because relabelling the groups changes none of their frequencies.

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: no period shows up, so it reports an additive (random keystream) layer, and the explanation says 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. Which codes does the Decryptor identify on its own? Now try 2,000 words: does more text add identifications, or only confidence? Then add two or three names from the message as cribs.
Crank homophones to 5x and re-encode the same message. Does the Decryptor still find the space code and “the”? Do the cribs still place?
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 two different short messages using additive superencipherment with the same pad (leave the pad in its field for the second encode; the App warns you that the pad has been used), 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.5.0 — Last updated: 2026-10-25

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