diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bffd83c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# claude-statusline
+
+A custom status line binary for
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code), written in Go.
+Reads JSON from stdin (provided by Claude Code's status hook) and outputs a
+formatted, ANSI-colored status line.
+
+```
+● Opus 4 ➜ statusline git:(master)                               6k/200k
+```
+
+**What it shows:**
+
+- Gitea service status (green/red dot)
+- Model name
+- Current directory
+- Git branch and dirty indicator
+- Context window usage
+
+## Install
+
+```bash
+go install gitea.kajkowalski.nl/kjanat/claude-statusline@latest
+cp "$(go env GOPATH)/bin/claude-statusline" ~/.claude/statusline
+```
+
+Or build from source:
+
+```bash
+git clone https://gitea.kajkowalski.nl/kjanat/claude-statusline.git
+go build -C claude-statusline -ldflags="-s -w" -o ~/.claude/statusline .
+```
+
+## Configure Claude Code
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.claude/statusline",
+    "padding": 0
+  }
+}
+```
+
+## Development
+
+Requires Go 1.25+.
+
+```bash
+# Build
+task build
+
+# Run tests
+task test
+
+# Run tests with coverage
+task test:cover
+
+# Lint
+task lint
+
+# Run with test fixture
+task run
+```
+
+## License
+
+MIT