diff --git a/CLAUDE.md b/CLAUDE.md
index e65515a77..3104b32a2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,8 +6,8 @@ This is NanoClaw v2, a ground-up rewrite with breaking changes throughout. It ca
 
 **Do this instead:**
 1. Abort the merge: `git merge --abort` (or `git reset --hard ORIG_HEAD` if the merge already completed).
-2. Tell the user, verbatim: *"This is the v2 rewrite — it can't be merged into your existing install. Run `bash migrate-v2.sh` to migrate instead."*
-3. Wait for the user to confirm before doing anything else. Do not attempt the migration yourself.
+2. Tell the user, verbatim: *"This is the v2 rewrite — it can't be merged into your existing install. Run `! bash migrate-v2.sh` to migrate instead."*
+3. Wait for the user to confirm before doing anything else. Do not run the migration script yourself — it requires an interactive terminal and must be run by the user with the `!` prefix.
 
 If you are a fresh install (you ran `git clone`, not `git pull`) and there are no conflicts, ignore this banner and continue below.
 
diff --git a/migrate-v2.sh b/migrate-v2.sh
index eb5a38142..ac9f4e01d 100644
--- a/migrate-v2.sh
+++ b/migrate-v2.sh
@@ -5,6 +5,9 @@
 # Run from the v2 directory:
 #   bash migrate-v2.sh
 #
+# From Claude Code, use the ! prefix so it runs in your terminal:
+#   ! bash migrate-v2.sh
+#
 # Finds v1 automatically (sibling directory, or $NANOCLAW_V1_PATH).
 # Installs prerequisites (Node, pnpm, deps) via the existing setup.sh
 # bootstrap, then runs the migration steps.
@@ -17,6 +20,19 @@ set -uo pipefail
 PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$PROJECT_ROOT"
 
+# This script has interactive prompts (channel selection, service switchover)
+# and streams progress output — it must run in a real terminal, not inside
+# a tool subprocess (e.g. Claude Code's Bash tool, which collapses output).
+if ! [ -t 0 ] || ! [ -t 1 ]; then
+  echo "This script requires an interactive terminal."
+  echo ""
+  echo "If you're in Claude Code, run it directly with the ! prefix:"
+  echo "  ! bash migrate-v2.sh"
+  echo ""
+  echo "Or run it in a separate terminal session."
+  exit 1
+fi
+
 LOGS_DIR="$PROJECT_ROOT/logs"
 STEPS_DIR="$LOGS_DIR/migrate-steps"
 MIGRATE_LOG="$LOGS_DIR/migrate-v2.log"