diff --git a/code/libraries/coded-sequence/readme.md b/code/libraries/coded-sequence/readme.md
new file mode 100644
index 00000000..c08b4645
--- /dev/null
+++ b/code/libraries/coded-sequence/readme.md
@@ -0,0 +1,49 @@
+The coded-sequence library offers tools for encoding sequences 
+of integers with a variable-length encoding. 
+
+The Elias Gamma code is supported:
+https://en.wikipedia.org/wiki/Elias_gamma_coding
+
+The `GammaCodedSequence` class stores a sequence of ascending
+non-negative integers in a byte buffer.  The encoding also
+stores the length of the sequence (as a gamma-coded value), 
+which is used in decoding.
+
+Sequences are encoded with the `GammaCodedSequence.of()`-method,
+and require a temporary buffer to work in.
+```java
+// allocate a temporary buffer to work in, this is reused
+// for all operations and will not hold the final result
+ByteBuffer workArea = ByteBuffer.allocate(1024);
+
+// create a new GammaCodedSequence with the given values
+var gcs = GammaCodedSequence.of(workArea, 1, 3, 4, 7, 10);
+```
+
+The `GammaCodedSequence` class provides methods to query the
+sequence, iterate over the values, and access the underlying
+binary representation. 
+
+```java
+// query the sequence 
+int valueCount = gcs.valueCount();
+int bufferSize = gcs.bufferSize();
+
+// iterate over the values
+IntIterator iter = gcs.iterator();
+IntList values = gcs.values();
+
+// access the underlying data (e.g. for writing)
+byte[] bytes = gcs.bytes();
+ByteBuffer buffer = gcs.buffer();
+```
+
+The `GammaCodedSequence` class also provides methods to decode
+a sequence from a byte buffer or byte array.
+
+```java
+// decode the data
+var decodedGcs1 = new GammaCodedSequence(buffer);
+var decodedGcs2 = new GammaCodedSequence(buffer, start, end);
+var decodedGcs3 = new GammaCodedSequence(bytes);
+```
\ No newline at end of file