1 files changed, 34 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..aba79e3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,34 @@
+# codevec
+
+Semantic code search via embeddings.
+
+```bash
+codevec index .
+codevec query "websocket connection handling"
+```
+
+## Status
+
+**Design phase** — see [DESIGN.md](DESIGN.md)
+
+## Overview
+
+Index your codebase, query by concept. Get relevant code chunks with file paths and line numbers.
+
+- AST-aware chunking (tree-sitter) for Go, TypeScript, Python
+- sqlite-vec for fast similarity search
+- Incremental updates (only re-index changed files)
+- Integrates with claude-flow as a `CodeSearch` tool
+
+## Why
+
+`grep` finds keywords. `codevec` finds meaning.
+
+```bash
+# grep misses this
+grep "authentication"  # won't find verifyJWT()
+
+# codevec finds it
+codevec query "authentication"
+# src/auth.go:15-42 VerifyJWT (0.89)
+```