diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..f7dff97
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elijah Voigt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2b9377c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,156 @@
+# claudbg
+
+A CLI tool for inspecting [Claude Code](https://claude.ai/code) sessions.
+Reads JSONL session files from `~/.claude/projects/`, caches them in a local
+SQLite database, and lets you list, dump, and transcribe sessions and
+sub-agent runs.
+
+```
++----------+--------------------------+----------------------------+-------------------+----------+
+| ID       | Date                     | Project                    | Model             | Messages |
++==========================================================================================================================+
+| 21fae0a8 | 2026-03-28T20:36:00.417Z | /home/user/my-project      | claude-sonnet-4-6 | 663      |
+| 80e9ebac | 2026-03-28T17:45:00.872Z | /home/user/my-project      | claude-sonnet-4-6 | 36       |
+| 18b7e801 | 2026-03-28T03:13:13.354Z | /home/user/other-project   | claude-sonnet-4-6 | 239      |
++----------+--------------------------+----------------------------+-------------------+----------+
+```
+
+## Features
+
+- **List sessions** sorted by most recent activity
+- **Dump** raw message entries from any session
+- **Transcribe** sessions as a human-readable chat log
+- **Inspect sub-agent runs** with the same list/dump/transcribe commands
+- **Live follow** (`--follow`) streams new entries as a session is written
+- **Multiple output formats**: table, JSON, XML
+- **Local cache** with lazy sync — only re-parses files that have changed on disk
+
+## Installation
+
+### Prerequisites
+
+- Rust (stable) — install via [rustup](https://rustup.rs)
+
+### From source
+
+```bash
+git clone https://github.com/pop/claudbg
+cd claudbg
+cargo install --path .
+```
+
+### With Nix flakes
+
+```bash
+nix run github:pop/claudbg
+```
+
+Or add to your flake inputs and install into your profile:
+
+```nix
+inputs.claudbg.url = "github:pop/claudbg";
+```
+
+## Usage
+
+### Listing sessions
+
+```bash
+# Show all sessions, most recent first
+claudbg sessions list
+
+# Show full UUIDs and paths
+claudbg sessions list --verbose
+
+# Output as JSON
+claudbg sessions list --output json
+```
+
+### Reading a session
+
+Session IDs can be given as the full UUID or an 8-character prefix.
+
+```bash
+# Dump raw message entries (sequence, timestamp, type, role, content preview)
+claudbg sessions dump 21fae0a8
+
+# Full content, no truncation
+claudbg sessions dump 21fae0a8 --verbose
+
+# Human-readable transcript (user/assistant turns, tool calls)
+claudbg sessions transcribe 21fae0a8
+
+# Include thinking blocks and tool output in the transcript
+claudbg sessions transcribe 21fae0a8 --include thinking,output
+
+# Stream new entries as they are written (e.g. while a session is active)
+claudbg sessions transcribe 21fae0a8 --follow
+```
+
+### Sub-agent runs
+
+Claude Code uses sub-agents for long-running tasks. `claudbg agents`
+mirrors the sessions commands for those runs.
+
+```bash
+# List all sub-agent runs within a session
+claudbg agents list 21fae0a8
+
+# Transcribe a specific sub-agent run
+claudbg agents transcribe 21fae0a8 <agent-id>
+
+# Follow a live sub-agent run
+claudbg agents transcribe 21fae0a8 <agent-id> --follow
+```
+
+### Indexing
+
+The database is kept in sync lazily (on every read command). You can also
+trigger a full resync manually:
+
+```bash
+# Sync any changed session files
+claudbg index
+
+# Force rebuild of the entire cache
+claudbg index --force
+```
+
+### Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--output table\|json\|xml` | Output format (default: `table`) |
+| `--verbose` | Show full UUIDs and untruncated content |
+| `--include thinking,output` | Include thinking blocks and/or tool results in transcripts |
+
+## Database
+
+claudbg stores its cache at `~/.claude/claudbg.db` (libsql/SQLite).
+The JSONL files under `~/.claude/projects/` are always the source of truth —
+the database is a read-through cache and can be deleted or rebuilt at any time.
+
+## Roadmap
+
+- **`tui`** — Terminal UI for browsing sessions interactively
+- **`query`** — Run ad-hoc SQL against the session cache (`claudbg query "SELECT ..."`)
+- **Token usage reports** — Aggregate cost/usage across sessions and date ranges
+- **Search** — Full-text search across session content
+- **Export** — Export transcripts to Markdown or HTML
+- **Watch mode** — Automatically index new sessions as Claude Code writes them
+
+## Development
+
+The project uses [Nix flakes](https://nixos.wiki/wiki/Flakes) for a reproducible dev environment:
+
+```bash
+nix develop    # enter the dev shell (provides rustup, cargo-nextest, etc.)
+cargo build
+cargo nextest run
+cargo clippy --all-targets -- -D warnings
+nix flake check   # runs the full CI suite
+```
+
+## License
+
+[MIT](LICENSE)