Learn Base64 with BaseHalf and AI
We opened the real base64-encoding folder in BaseHalf, laid encoding, padding, and variant notes out as cards beside a local copy of RFC 4648, listed those notes as upstream on the practice card, and had Claude Code in the Agent Area grade four Base64 cases as correct.
A Base64 string is easier to check when the alphabet, the padding rules, and the variants each have their own card, the RFC sits in the same folder, and an agent can see both the notes and the practice answers. We made an ordinary Desktop folder, put six short Markdown notes and a local copy of RFC 4648 into it, and opened that folder in BaseHalf. The window title became base64-encoding. The sidebar listed every file. Each file became a card. We started Claude Code in the Agent Area on the right, with the practice card selected.
The folder on disk was Desktop/basehalf-learn-sessions/base64-encoding/. These were the files on the canvas:
base64-encoding/
00-goal.md
01-encoding.md
02-padding.md
03-variants.md
04-practice.md
rfc4648.txt
sources.md
What each card held
00-goal.md set the boundary: encode and decode Base64, map 24-bit groups to the Table 1 alphabet, apply the three padding cases, tell base64 from base64url, and reject a string that a general decoder must not accept. Check four practice cases against RFC 4648. The folder studies Base64 and base64url. It does not walk the Base32 or Base16 encodings in the same document.
01-encoding.md kept the §4 process, which the RFC names "base64": 24-bit groups of input bits become four encoded characters. Three 8-bit octets are concatenated and then read as four 6-bit indices into Table 1: A-Z, a-z, 0-9, +, and /. The 65th character, =, is not an index; it marks padding. The card also pointed at the §9 worked example 0x14fb9c03d97e, which encodes to FPucA9l+.
02-padding.md kept the three end cases in §4. A multiple of 24 bits produces four characters and no =. Exactly 8 bits produces two characters and ==. Exactly 16 bits produces three characters and one =. Section 3.2 says implementations MUST include the appropriate pad characters unless the specification that refers to this document explicitly states otherwise. The card also kept the §10 test vectors BASE64("foo") = "Zm9v", BASE64("fo") = "Zm8=", and BASE64("f") = "Zg==", and the §3.5 rule that unused pad bits MUST be set to zero by a conforming encoder. If they are not, a decoder MAY reject the encoding.
03-variants.md kept base64url from §5: the same encoding, except Table 2 uses - (minus) for value 62 and _ (underline) for value 63. The RFC says this encoding should not be regarded as the same as "base64" and should not be referred to as only "base64". The pad character may be skipped when the data length is known implicitly; see §3.2. The card also kept §3.1: implementations MUST NOT add line feeds unless the referring specification explicitly directs encoders to add them after a specific number of characters. The 76-character MIME line length is a MIME rule, not a general Base64 rule. Section 3.3 says a general decoder MUST reject characters outside the base alphabet, unless the referring specification explicitly states otherwise. MIME is the RFC's example of a specification that ignores non-alphabet characters, including adjacent CRLF.
sources.md linked RFC 4648 (S. Josefsson, October 2006, "The Base16, Base32, and Base64 Data Encodings"), with the local copy rfc4648.txt. The RFC obsoletes RFC 3548. The folder uses RFC 4648 only. It does not treat MIME or PEM as the Base64 definition, except where RFC 4648 itself discusses them.
Upstream on the practice note
The practice note listed the three concept cards and sources.md in its upstream list. On the canvas, lines from 01-encoding, 02-padding, 03-variants, and sources ran into 04-practice. The file began with:
upstream:
- 01-encoding.md
- 02-padding.md
- 03-variants.md
- sources.mdThat list sticks in the file. Selection does not: it lives in .bh/cache/selection.yaml only while BaseHalf is open. We selected the practice card, and the status bar showed 04-practice, before asking Claude Code to grade it.
The four practice cases
The practice card asked for a short answer and a one-line reason in each case, preferring the cards and RFC 4648 over a remembered rule.
-
Using the §10 test vectors, what is
BASE64("foobar")? What isBASE64("f")? Why does the second encoding end with two=characters? -
Section 9 encodes the six octets
0x14fb9c03d97e. What is the Base64 output? Which character comes from value 62? What is the base64url spelling of the same bits? -
Is
Zg=a valid general-case Base64 encoding of"f"? IsZg(padding omitted)? IsZh==a canonical encoding of"f"? -
Should a general RFC 4648 encoder add a line feed to a long Base64 string? Should a general decoder accept
Zm9vYmFyfollowed by a newline?
Our answers:
-
Zm9vYmFy, andZg==."f"is one octet, which is exactly 8 bits, so §4 case (2) says the final unit is two characters followed by two=padding characters. The same pair is in the §10 test vectors. -
FPucA9l+. The last index is 62, which Table 1 writes as+. Table 2 writes value 62 as-, so the base64url spelling isFPucA9l-. Section 5 says base64url should not be referred to as only "base64". -
No, no, and no.
Zg=has only one pad, but"f"is the 8-bit case, which §4 says takes two=characters.Zgomits padding; §3.2 says implementations MUST include the appropriate pad characters unless a referring specification explicitly states otherwise, and in the general case padding is required.Zh==is not canonical:"f"is0x66, so the unused pad bits must be zero, which givesZg==(§3.5 and §4). A decoder MAY rejectZh==. -
No, and no. Section 3.1 says implementations MUST NOT add line feeds unless the referring specification explicitly directs encoders to add them after a specific number of characters; the 76-character MIME limit is not a general Base64 rule. A newline is outside the Table 1 alphabet, so §3.3 says a general decoder MUST reject the string, unless a referring specification (MIME is the RFC's example) explicitly says to ignore non-alphabet characters.

What Claude Code actually said
Treat the reply as a draft. In this session Claude Code (v2.1.325, shown in the window as Opus 5.5 with xhigh effort, Claude Ultra) said all four answers were correct, that each one matched the upstream notes and the local rfc4648.txt, and that it had not edited any files. The run lasted 1 minute 8 seconds. The practice files on disk kept the same timestamps they had before the session. It also said it had run a quick Python check that agreed with every answer, and that the check was only a sanity test; the RFC is what decides each case. We treated it that way, and checked the quotes against the local RFC.
For the first case it quoted the §10 vectors BASE64("f") = "Zg==" and BASE64("foobar") = "Zm9vYmFy", and §4 case (2): the final quantum of exactly 8 bits produces two characters followed by two = padding characters. We checked those passages; the quotes hold. Some of the line numbers it printed next to the quotes were a few lines off, so we used the section text, not those numbers. It added an optional note: the reason could also say why there are two characters in the first place. After the 8 bits get four zero bits, they make two 6-bit groups, and the two = fill out the 4-character unit. That follows §4 as well.
For the second case it agreed the output is FPucA9l+, quoting the §9 decimal row 5 15 46 28 0 61 37 62 and the output row F P u c A 9 l +. It quoted §5: the encoding is technically identical except for the 62nd and 63rd alphabet characters, and Table 2 writes 62 as - (minus), so the base64url spelling is FPucA9l-. None of the indices is 63, so only the last character changes. It also said the §5 line in our answer, that base64url should not be referred to as only "base64", is true, but does not decide this case. We checked those passages; the quotes and the table entry hold.

For the third case it agreed all three strings fail, for the reasons we gave. Zg= is not valid because §4 case (2) requires two = for an 8-bit input. Zg is not valid in the general case; it quoted §3.2 on padding being required when the size cannot be assumed, and the MUST to include pad characters unless a referring specification states otherwise. It noted that our answer kept that exception, and that §5 points to the same exception for base64url. The §5 pointer is right in substance: that section says the pad character may be skipped when the data length is known implicitly, and refers to §3.2. The line numbers it printed for that pointer landed on a nearby paragraph about an unused ~ alphabet, not on the padding sentence, so we used the section text. For Zh== it worked the bits: 0x66 is 01100110, which yields Z and then 10 followed by zero bits, 100000 (g). h is 33, 100001, so a pad bit is set. It still decodes to "f". It quoted §3.5, including the RFC's own wording that pad bits MUST be set to zero, that otherwise several strings can decode to the same octets, and that decoders MAY reject the encoding. We checked those passages; the quotes and the bit arithmetic hold.
For the fourth case it agreed both answers are no. It quoted §3.1: implementations MUST NOT add line feeds unless the referring specification explicitly directs encoders to add them after a specific number of characters. It placed the 76-character limit in MIME itself, quoting that MIME enforces a limit of 76 characters on the line length of base 64-encoded data. For the decoder it quoted §3.3: implementations MUST reject encoded data that contains characters outside the base alphabet, unless the referring specification explicitly states otherwise, and that MIME is the example of a specification that instead ignores those characters. We checked both sections; the quotes hold. The same section also says, a few lines later, that under such a MIME-style rule, adjacent CRLF characters are non-alphabet characters and are ignored. That does not change the general-case grade.
What this session can and cannot show
Four worked cases are a start, not a complete reading of RFC 4648. We did not walk Base32, Base16, the C implementation in §11, or the security notes in §12. The model can misquote a section or a line number; the local RFC is the check, and in this run the section quotes we verified held, while several line numbers did not. A later session can take the same folder, add a Base32 case, and keep going from there.