diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..003b286
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,35 @@
+# Smriti — project instructions for Claude Code
+
+This project uses Smriti as the shared reasoning-state backend.
+A SessionStart hook injects `smriti state smriti-dev` into your
+context automatically. Read it before doing anything else.
+
+## Session start checklist
+
+1. The state brief is already in your context (injected by the hook). Read it.
+2. Check `## Active work` — if another agent has an active claim on work you were about to start, pick different work or ask the human.
+3. Reconcile against the repo: `git log --oneline -10`. Check whether tasks from the state brief are already done.
+4. Create a work claim before starting substantial work: `smriti_claim(space="smriti-dev", scope="...", agent="claude-code")`.
+
+## During work
+
+- Checkpoint at inflection points only, not after every small step. Use `--author-agent claude-code`.
+- If exploring an alternative direction, fork first.
+- If state and repo disagree, stop and reconcile — do not guess.
+
+## Session end
+
+- Mark your work claims done or abandoned.
+- Push your branch if it should be visible.
+- State the branch disposition: ready to merge, needs review, or exploratory.
+
+## Do not
+
+- Write HANDOFF.md, NOTES.md, or similar files. The checkpoint is the handoff.
+- Start, restart, or manage the backend or Docker. You are a client.
+- Merge or push to main without human approval.
+- Checkpoint noise (save-button commits, end-of-session dumps).
+
+The full skill pack is at `.claude/skills/smriti/SKILL.md`. This file is the
+compact always-loaded version. Refer to the skill pack for detailed guidance
+on claims, branching, drift detection, and anti-patterns.
diff --git a/README.md b/README.md
index 3fd2c09..07df967 100644
--- a/README.md
+++ b/README.md
@@ -258,6 +258,8 @@ smriti state my-project                    # your agent's first action, every se
 
 From here, the skill pack teaches the agent to read state first, checkpoint at inflection points (not after every small step), fork before exploring alternatives, and never write `HANDOFF.md`. See `cli/README.md` for the full workflow walkthrough.
 
+**Optional: auto-inject state at session start.** Claude Code supports SessionStart hooks. Add a `.claude/settings.json` with a hook that runs `smriti state <project> --preview` at startup — the state brief is injected into the agent's context before it processes the first prompt. See `CLAUDE.md` for the compact project-level instructions that complement the hook.
+
 **Why this is better than markdown handoffs:** Smriti checkpoints are structured, branchable, comparable, and restorable. When reasoning drifts or an agent goes in the wrong direction, you can restore to a clean checkpoint and the bad context is excluded — not summarized, not hidden, actually excluded at the data layer. Markdown handoff files can't do that, and they fall apart the moment two agents need to work in parallel.
 
 ---