diff --git a/integrations/claude-code/README.md b/integrations/claude-code/README.md
new file mode 100644
index 00000000..29be14a6
--- /dev/null
+++ b/integrations/claude-code/README.md
@@ -0,0 +1,64 @@
+# Claude Code Integration for Beads
+
+Slash command for converting [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plans to beads tasks.
+
+## Prerequisites
+
+```bash
+# Install beads
+curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Install hooks (auto-injects workflow context on session start)
+bd setup claude
+```
+
+## Installation
+
+```bash
+cp commands/plan-to-beads.md ~/.claude/commands/
+```
+
+Optionally add to `~/.claude/settings.json` under `permissions.allow`:
+
+```json
+"Bash(bd:*)"
+```
+
+## /plan-to-beads
+
+Converts a Claude Code plan file into a beads epic with tasks.
+
+```
+/plan-to-beads                    # Convert most recent plan
+/plan-to-beads path/to/plan.md    # Convert specific plan
+```
+
+**What it does:**
+- Parses plan structure (title, summary, phases)
+- Creates an epic for the plan
+- Creates tasks from each phase
+- Sets up sequential dependencies
+- Uses Task agent delegation for context efficiency
+
+**Example output:**
+```
+Created from: peaceful-munching-spark.md
+
+Epic: Standardize ID Generation (bd-abc)
+  ├── Add dependency (bd-def) - ready
+  ├── Create ID utility (bd-ghi) - blocked by bd-def
+  └── Update schema (bd-jkl) - blocked by bd-ghi
+
+Total: 4 tasks
+Run `bd ready` to start.
+```
+
+## Related
+
+- `bd prime` - Workflow context (auto-injected via hooks)
+- `bd setup claude` - Install/manage Claude Code hooks
+- `bd ready` - Find unblocked work
+
+## License
+
+Same as beads (see repository root).
diff --git a/integrations/claude-code/commands/plan-to-beads.md b/integrations/claude-code/commands/plan-to-beads.md
new file mode 100644
index 00000000..ab0a854f
--- /dev/null
+++ b/integrations/claude-code/commands/plan-to-beads.md
@@ -0,0 +1,62 @@
+# Convert Plan to Beads Tasks
+
+## description:
+Convert a Claude Code plan file into beads epic + tasks for cross-session tracking.
+
+## Arguments
+$ARGUMENTS (optional - path to plan file, defaults to most recent in ~/.claude/plans/)
+
+---
+
+Use the **Task tool** with `subagent_type='general-purpose'` to convert the plan.
+
+## Agent Instructions
+
+The agent should:
+
+1. **Find the plan file**
+   - If argument provided, use that path
+   - Otherwise: `ls -t ~/.claude/plans/*.md | head -1`
+
+2. **Parse the plan structure**
+   - Title: First `# Plan:` or `#` heading
+   - Description: Content under `## Summary`
+   - Tasks: Each `### Phase N:` or `### N.` section
+   - File list: Include in epic description
+
+3. **Create the epic**
+   ```bash
+   bd create "[Plan Title]" -t epic -p 1 -d "[summary]. Files: N to modify." --json
+   ```
+
+4. **Create tasks from phases**
+   - Each phase becomes a task
+   - Use first paragraph of phase content as description
+   ```bash
+   bd create "[Phase title]" -t task -p 2 -d "[description]" --json
+   ```
+
+5. **Add sequential dependencies**
+   - Phases are sequential: `bd dep add <phase2> <phase1>`
+
+6. **Link tasks to epic**
+   - `bd dep add <epic> <task>` for each task
+
+7. **Return a concise summary** (not raw output):
+   ```
+   Created from: [filename]
+
+   Epic: [title] ([epic-id])
+     ├── [Phase 1] ([id]) - ready
+     ├── [Phase 2] ([id]) - blocked by [prev]
+     └── [Phase 3] ([id]) - blocked by [prev]
+
+   Total: [N] tasks
+   Run `bd ready` to start.
+   ```
+
+## Notes
+
+- Original plan file is preserved for reference
+- Task descriptions use first paragraph only (keeps them scannable)
+- Sequential phases get automatic dependencies