RAG Chunk Splitter.

A useful rule: if your top-k results keep containing the right document but not the right sentence, chunks are too large. If they keep containing half the answer, chunks are too small. Those two symptoms point in opposite directions, so diagnose before you turn the dial.

Overlap is insurance, and you pay the premium on every chunk

Overlap exists for exactly one reason: a fixed-size window cuts blind, so you duplicate the seam to make sure a sentence straddling the cut survives in at least one chunk. That is a real problem and overlap is a real fix — for fixed-size splitting.

The moment your splitter respects sentence or paragraph boundaries, most of what overlap protects against has already been handled, and the premium starts looking expensive. Twenty percent overlap means 20% more vectors to store, 20% more index to search, and a top-k list where two of your five slots are near-duplicates of each other. The overlap tax figure in the stats panel is the number to watch: it is total tokens across all chunks minus the tokens in your source, i.e. exactly what you are embedding twice. The one-off embedding bill is usually pocket change; the permanent index bloat and the crowded top-k are what actually hurt.

Splitting mid-sentence wrecks the embedding, not just the text

An embedding model compresses the whole chunk into one vector. Feed it a fragment that ends "…therefore the migration must run before" and it produces a vector for a statement that has no meaning. That vector does not merely fail to retrieve — it pollutes the index, because a semantically incoherent chunk lands somewhere near everything and near nothing, and it will surface for queries it has no business answering.

The nasty part is that this survives eyeball review. The chunk still reads like text, so the ingestion pipeline looks fine right up until someone asks the question that needed the second half. Tables lose their header row and become unretrievable columns of numbers. Code blocks get separated from the paragraph that explains what they do. Both are invisible in a chunk dump and obvious in production.

Structure-aware splitting for markdown and code

Most documents already contain the boundaries you want, and you get them for free. Markdown headings mark topic changes better than any similarity threshold you could tune, which is why the heading-aware mode here starts a new chunk at every #, ##, or ### and keeps the heading attached to its body. When a section is still too big and has to spill into several chunks, the heading is re-injected at the top of each continuation chunk — otherwise chunk three of "Rate limits" retrieves as an orphan paragraph belonging to nothing. Headings inside fenced code blocks are ignored, because #!/bin/sh is not a section.

For source code, apply the same principle with different boundaries: split on function, class, or module, never mid-body, and carry the imports or the class signature into each chunk as context. For HTML and PDFs, strip to structure first — a splitter fed raw PDF text extraction is splitting page furniture as often as it is splitting content.

How this tool splits

• Fixed-size slides a hard window across the raw text with a step of size minus overlap. In token mode the window is converted to characters using the document's own characters-per-token ratio, so the window tracks your text rather than a generic constant.
• Sentence and paragraph modes split into whole units first, then greedily pack units until the next one would blow the budget. Overlap is built by walking backwards over complete units, so you never get half a sentence of overlap. A unit that is larger than the target on its own is recursively broken down — paragraph to sentences, sentence to a hard window — which is the only point where a mid-sentence cut can happen.
• Markdown sections each pack independently. That means a document with many short sections produces many short chunks, and the tool will not glue two unrelated sections together to hit a target. That is deliberate: a chunk with two topics in it is worse than a chunk that is simply small.
• Token counts use OpenAI's o200k_base tokenizer, the same one as my token counter. They are exact for that tokenizer. Other embedding models count a little differently, so keep some headroom under a hard limit.

Two guardrails worth knowing about. Any chunk over 8,192 tokens is flagged, because that is the input ceiling on most current embedding models and anything past it gets silently truncated by the API rather than rejected. And an overlap greater than or equal to the chunk size is the classic infinite-loop footgun in hand-rolled splitters — this one clamps it, warns you, and stops after a hard chunk ceiling instead of locking up your tab.