diff --git a/.gitignore b/.gitignore
index 3b948d4..918dce5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
+# Claude Code worktrees
+.claude/worktrees
+
 # build output
 target/
 
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..dbb4675
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,66 @@
+## Using atgc
+
+When doing repo operations, always use the global install of `atgc` (not the one from your in-progress branch). To get a briefing, run `atgc agent` at the start of a session or when the version changes.
+
+## Feature branch workflow
+
+Some points to keep in mind:
+
+- If asked to do work, unless directly instructed otherwise, do not make changes to the user's top-level git checkout (other than making subtrees attached to it).
+- While doing work, you are one of many agents running on a system:
+    - Do not restart, reload, or otherwise modify the configuration of shared services.
+    - If you need temporary folders or other artifacts that exist outside your worktree (such as Docker images), reduce conflicts by tagging them with your current branch and/or SHA.
+    - Check available system resources before running expensive commands (memory or CPU).
+- All code will be human-reviewed. All commentary about feature implementation should be concise, avoid flowery or verbose language, and focus on what the change accomplishes.
+
+Before starting work on a feature:
+
+- Create a new branch like "claude/short-feature-name", based on `origin/main`
+- Create a worktree in `.claude/worktrees` for working on the feature branch
+- Enter the worktree so that all commands run inside of it
+- Double check that the repo-local `.git/config` `[user]` section has an ATProto `@-` handle as a `name` and its `did:plc` as an email
+
+Each feature branch should include supporting work:
+
+- Maintenance work to reduce duplicated or dead code
+- Adding new debug log lines or similar observability
+- An update to any high-level documentation (if needed)
+- A few of high-value tests (if applicable)
+- Checking off completed issues in TODO.md
+
+Structure your commits:
+
+- Break work into logical commits, typically 1-5 for an average feature.
+- Use Conventional Commits, including adding "!" indicators for breaking behavior changes.
+- Don't write more than 1 short sentence + 1 short paragraph into a commit body.
+
+Before submitting a PR:
+
+- Check for a rebase against `origin/main` and fix any conflicts
+- Ensure that `cargo fmt`, `cargo clippy` and `scripts/check-boundaries.sh` are clean. This repo has no `prek` config; those are the checks it has.
+- Ensure that relevant tests pass
+
+When writing any PRs, updates to PRs, or comments on PRs:
+
+- The PR title should be simple and descriptive, and should use Conventional Commits.
+- The PR body should contain a before/after screenshot if the change has a visible effect (UI, rendered output, a CLI's printed text). Attach this with Markdown image syntax and a local image path: the `atgc` commands will upload it for you.
+
+To submit a PR:
+
+- Push the rebased branch to the origin. Tangled uses patch-based rounds, so pushing a remote and submitting a PR are different operations.
+- If the PR is a handful of commits, submit it via `atgc pr create`
+- If the PR would be more than a handful of commits, prefer `atgc stack create` to break it into reviewable PRs for logical sub-features. `atgc stack resubmit` reconciles the chain after a rebase or reorder.
+- When the PR has been created, post the Tangled PR link for the user to review.
+
+If asked to iterate post-submission, each iteration should:
+
+- Rebase against the latest `origin/main`, implement the changes, and repeat verification.
+- Push the latest updates to the feature branch.
+- Push a new patch to the existing PR via `atgc pr resubmit` or `atgc stack resubmit`.
+- Push a new PR title/body (including new screenshots) with `atgc pr edit`.
+
+After a feature is merged:
+
+- Clean up your own worktree.
+- Delete both the local and the remote feature branch.
+- Leave any temporary artifacts (like Docker images).