diff --git a/README.gif b/README.gif
new file mode 100644
index 0000000..3295ac2
Binary files /dev/null and b/README.gif differ
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d53862c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,81 @@
+# protoc-gen-go-value-scan
+
+Implements scanner and valuer interfaces for proto messages.
+
+![README](./README.gif)
+
+## What it does
+
+Takes this proto
+
+```proto
+syntax = "proto3";
+
+package foo.v1;
+
+option go_package = "git.wobcom.de/smartmetering/protoc-gen-go-value-scan/test/go/foo/v1;foov1";
+
+message Foo {
+    string bar  = 1;
+    string zonk = 2;
+}
+```
+
+and creates this go code
+
+```go
+// Code generated by protoc-gen-go-value-scan. DO NOT EDIT.
+
+package foov1
+
+import (
+	"database/sql/driver"
+	"fmt"
+
+	protojson "google.golang.org/protobuf/encoding/protojson"
+)
+
+func (x Foo) Value() (driver.Value, error) {
+	f := &x
+
+	opts := protojson.MarshalOptions{}
+	opts.UseProtoNames = false
+	opts.EmitUnpopulated = true
+
+	return opts.Marshal(f)
+}
+
+func (x *Foo) Scan(value interface{}) error {
+	switch v := value.(type) {
+	case []byte:
+		return protojson.Unmarshal(v, x)
+	case string:
+		return protojson.Unmarshal([]byte(v), x)
+	default:
+		return fmt.Errorf("type assertion failed")
+	}
+}
+```
+
+## Configuration
+
+| Option             | Meaning                                                                                | Default |
+| ------------------ | -------------------------------------------------------------------------------------- | ------- |
+| `use_proto_names`  | UseProtoNames uses proto field name instead of lowerCamelCase name in JSON field names | `true`  |
+| `emit_unpopulated` | EmitUnpopulated specifies whether to emit unpopulated fields                           | `true`  |
+| `exclude`          | Takes a message identifier. Can be multiple identifier delimited by `,`                | none    |
+
+### Example
+
+```yaml
+version: v1
+plugins:
+  - name: go
+    out: go/
+    opt:
+      - paths=source_relative
+  - name: go-value-scan
+    out: go/
+    opt:
+      - paths=source_relative,use_proto_names=false,emit_unpopulated=true,exclude=git.wobcom.de/smartmetering/protoc-gen-go-value-scan/test/go/foo/v1.ExcludeThis
+```