رفتن به محتوا

پیکربندی ترمینال برای Claude Code

Claude Code در هر ترمینالی بدونِ پیکربندی کار می‌کند. این صفحه برای وقتی است که چیزِ مشخصی آن‌طور که انتظار داری رفتار نمی‌کند. نشانه‌ات را پایین پیدا کن. اگر همه‌چیز از قبل درست به‌نظر می‌رسد، به این صفحه نیازی نداری.

این صفحه درباره‌ی این است که ترمینالت سیگنال‌های درست را به Claude Code بفرستد. برای تغییرِ اینکه خودِ Claude Code به کدام کلیدها پاسخ می‌دهد، به‌جایش keybindings را ببین.

واردکردنِ پرامپت‌های چندخطی

Section titled “واردکردنِ پرامپت‌های چندخطی”

فشردنِ Enter پیامت را ارسال می‌کند. برای افزودنِ یک شکستِ خط بدونِ ارسال، Ctrl+J را بزن، یا \ تایپ کن و بعد Enter را بزن. هر دو در هر ترمینالی بدونِ راه‌اندازی کار می‌کنند.

در بیشترِ ترمینال‌ها می‌توانی Shift+Enter را هم بزنی، اما پشتیبانی بسته به امولاتورِ ترمینال فرق می‌کند:

ترمینالShift+Enter برای خطِ جدید
Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal, Windows Terminalبدونِ راه‌اندازی کار می‌کند
VS Code, Cursor, Devin Desktop, Alacritty, Zedیک‌بار /terminal-setup را اجرا کن
gnome-terminal, JetBrains IDEs مثلِ PyCharm و Android Studioدر دسترس نیست؛ از Ctrl+J یا \ و بعد Enter استفاده کن

برای VS Code، Cursor، Devin Desktop، Alacritty و Zed، /terminal-setup کلیدِ Shift+Enter و دیگر keybindingها را در فایلِ پیکربندیِ ترمینال می‌نویسد. bindingهای موجود سرِجایشان می‌مانند؛ اگر پیامی مثلِ VSCode terminal Shift+Enter key binding already configured دیدی، یعنی تغییری اعمال نشده. /terminal-setup را مستقیم در خودِ ترمینالِ میزبان اجرا کن، نه داخلِ tmux یا screen، چون لازم است در فایلِ پیکربندیِ ترمینالِ میزبان بنویسد.

در VS Code، Cursor و Devin Desktop، /terminal-setup دو تنظیمِ ادیتور را هم به‌روز می‌کند: terminal.integrated.gpuAcceleration را روی "off" می‌گذارد تا از به‌هم‌ریختگیِ متن در ترمینالِ یکپارچه جلوگیری کند، و terminal.integrated.mouseWheelScrollSensitivity را برای اسکرولِ نرم‌تر در حالتِ fullscreen تنظیم می‌کند. برای برگرداندنِ تغییرِ شتاب‌دهیِ GPU، آن را به "auto" برگردان و پنجره‌ی ادیتور را reload کن.

اگر داخلِ tmux اجرا می‌کنی، Shift+Enter حتی وقتی ترمینالِ بیرونی پشتیبانی می‌کند، به پیکربندیِ tmuxِ پایین هم نیاز دارد.

برای bind کردنِ خطِ جدید به یک کلیدِ دیگر، یا جابه‌جا کردنِ رفتار تا Enter یک خطِ جدید درج کند و Shift+Enter ارسال کند، اکشن‌های chat:newline و chat:submit را در فایلِ keybindings خود نگاشت کن.

فعال‌کردنِ میان‌برهای کلیدِ Option روی macOS

Section titled “فعال‌کردنِ میان‌برهای کلیدِ Option روی macOS”

بعضی میان‌برهای Claude Code از کلیدِ Option استفاده می‌کنند، مثلِ Option+Enter برای خطِ جدید یا Option+P برای تعویضِ مدل‌ها. روی macOS، بیشترِ ترمینال‌ها به‌طور پیش‌فرض Option را به‌عنوان modifier نمی‌فرستند، پس این میان‌برها تا وقتی فعالش نکنی هیچ کاری نمی‌کنند. تنظیمِ ترمینال برای این معمولاً «Use Option as Meta Key» برچسب می‌خورد؛ Meta نامِ تاریخیِ یونیکس برای کلیدی است که الان Option یا Alt برچسب خورده.

Settings → Profiles → Keyboard را باز کن و «Use Option as Meta Key» را تیک بزن.

اگر پرامپتِ اولین اجرای Claude Code را پذیرفتی که «Option+Enter for newlines and visual bell» را پیشنهاد می‌داد، این از قبل انجام شده. آن پرامپت /terminal-setup را برایت اجرا می‌کند، که Option را به‌عنوان Meta فعال می‌کند و bellِ صوتی را در پروفایلِ Apple Terminal تو به یک چشمکِ بصریِ صفحه تبدیل می‌کند.

برای Ghostty، Kitty و دیگر ترمینال‌ها، دنبالِ یک تنظیمِ Option-as-Alt یا Option-as-Meta در فایلِ پیکربندیِ ترمینال بگرد.

گرفتنِ bellِ ترمینال یا اعلان

Section titled “گرفتنِ bellِ ترمینال یا اعلان”

وقتی Claude کاری را تمام می‌کند یا برای یک پرامپتِ دسترسی مکث می‌کند، یک رویدادِ اعلان شلیک می‌کند. نمایان‌کردنِ این به‌صورتِ bellِ ترمینال یا اعلانِ دسکتاپ به تو اجازه می‌دهد حین اجرای یک کارِ طولانی به کارهای دیگر بپردازی.

به‌طور پیش‌فرض Claude Code فقط در Ghostty، Kitty و iTerm2 اعلانِ دسکتاپ می‌فرستد. در ترمینال‌های دیگر، preferredNotifChannel را روی "terminal_bell" بگذار تا به‌جایش bellِ ترمینال را به‌صدا درآورد، یا یک Notification hook برای صدا یا دستورِ سفارشی پیکربندی کن.

اعلانِ دسکتاپ روی SSH به دستگاهِ محلی‌ات می‌رسد، پس یک نشستِ راه‌دور هم می‌تواند به تو هشدار بدهد. Ghostty و Kitty آن را بدونِ راه‌اندازیِ بیشتر به مرکزِ اعلانِ سیستم‌عاملت می‌فرستند. iTerm2 لازم دارد forwarding را فعال کنی:

تنظیماتِ اعلانِ iTerm2 را باز کن

به Settings → Profiles → Terminal برو.

هشدارها را فعال کن

«Notification Center Alerts» را تیک بزن، بعد روی «Filter Alerts» کلیک کن و «Send escape sequence-generated alerts» را فعال کن.

اگر اعلان‌ها هنوز ظاهر نمی‌شوند، تأیید کن که اپلیکیشنِ ترمینالت در تنظیماتِ سیستم‌عاملت مجوزِ اعلان دارد، و اگر داخلِ tmux اجرا می‌کنی، passthrough را فعال کن.

پخشِ صدا با یک Notification hook

Section titled “پخشِ صدا با یک Notification hook”

در هر ترمینالی می‌توانی یک Notification hook پیکربندی کنی تا وقتی Claude به توجهت نیاز دارد، صدایی پخش کند یا دستورِ سفارشی‌ای اجرا کند. hookها در کنارِ اعلانِ داخلی اجرا می‌شوند، نه به‌جای آن، پس ترمینال‌هایی که اعلانِ دسکتاپ دریافت نمی‌کنند، مثلِ Warp یا ترمینالِ یکپارچه‌ی VS Code، می‌توانند از یک hook استفاده کنند یا به‌جایش preferredNotifChannel را روی "terminal_bell" بگذارند.

مثالِ زیر یک صدای سیستمی را روی macOS پخش می‌کند. راهنمای لینک‌شده دستورهای اعلانِ دسکتاپ برای macOS، Linux و Windows را دارد.

{
"hooks": {
"Notification": [
{
"hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
}
]
}
}

وقتی Claude Code داخلِ tmux اجرا می‌شود، دو چیز به‌طور پیش‌فرض خراب می‌شود: Shift+Enter به‌جای درجِ خطِ جدید ارسال می‌کند، و اعلان‌های دسکتاپ و نوارِ پیشرفت هرگز به ترمینالِ بیرونی نمی‌رسند. این خط‌ها را به ~/.tmux.conf اضافه کن، بعد tmux source-file ~/.tmux.conf را اجرا کن تا روی سرورِ در حالِ اجرا اعمال شوند:

Terminal window
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

خطِ allow-passthrough اجازه می‌دهد اعلان‌ها و به‌روزرسانی‌های پیشرفت به‌جای بلعیده‌شدن توسطِ tmux، به ترمینالِ بیرونی برسند. خط‌های extended-keys به tmux اجازه می‌دهند Shift+Enter را از Enterِ ساده تشخیص دهد تا میان‌برِ خطِ جدید کار کند.

از دستورِ /theme، یا انتخاب‌گرِ تم در /config، برای انتخابِ تمی از Claude Code که با ترمینالت هماهنگ باشد استفاده کن. انتخابِ گزینه‌ی auto پس‌زمینه‌ی روشن یا تاریکِ ترمینالت را تشخیص می‌دهد، پس تم هر وقت ترمینالت تغییر کند، تغییراتِ ظاهرِ سیستم‌عامل را دنبال می‌کند. Claude Code طرحِ رنگیِ خودِ ترمینال را کنترل نمی‌کند، که توسطِ اپلیکیشنِ ترمینال تنظیم می‌شود.

برای سفارشی‌کردنِ آنچه در پایینِ رابط ظاهر می‌شود، یک status lineِ سفارشی پیکربندی کن که مدلِ فعلی، پوشه‌ی کاری، شاخه‌ی گیت یا کانتکستِ دیگری را نشان دهد.

علاوه بر presetهای داخلی، /theme هر تمِ سفارشی‌ای که تعریف کرده‌ای و هر تمی که پلاگین‌های نصب‌شده آورده‌اند را فهرست می‌کند. در انتهای فهرست New custom theme… را انتخاب کن تا یکی را به‌صورتِ تعاملی بسازی: تم را نام می‌گذاری، بعد توکن‌های رنگیِ منفرد را برای override انتخاب می‌کنی. وقتی یک تمِ سفارشی برجسته است Ctrl+E را بزن تا ویرایشش کنی.

هر تمِ سفارشی یک فایلِ JSON در ~/.claude/themes/ است. نامِ فایل بدونِ پسوندِ .json اسلاگِ تم است، و انتخابِ تم، custom:<slug> را به‌عنوانِ ترجیحِ تمِ تو ذخیره می‌کند. فایل سه فیلدِ اختیاری دارد:

فیلدنوعتوضیح
namestringبرچسبِ نمایشی که در /theme نشان داده می‌شود. به‌طور پیش‌فرض همان اسلاگِ نامِ فایل
basestringpresetِ داخلی‌ای که تم از آن شروع می‌شود: dark، light، dark-daltonized، light-daltonized، dark-ansi یا light-ansi. پیش‌فرض dark
overridesobjectنگاشتِ نام‌های توکنِ رنگ به مقادیرِ رنگ. توکن‌هایی که اینجا فهرست نشده‌اند به presetِ پایه fall through می‌کنند

مقادیرِ رنگ این‌ها را می‌پذیرند: #rrggbb، #rgb، rgb(r,g,b)، ansi256(n)، یا ansi:<name> که در آن <name> یکی از ۱۶ نامِ استانداردِ رنگِ ANSI مثلِ red یا cyanBright است. توکن‌های ناشناخته و مقادیرِ رنگِ نامعتبر نادیده گرفته می‌شوند، پس یک غلطِ تایپی نمی‌تواند رندر را خراب کند.

مثالِ زیر تمی تعریف می‌کند که presetِ dark را نگه می‌دارد ولی رنگِ accentِ پرامپت، متنِ خطا و متنِ موفقیت را عوض می‌کند:

{
"name": "Dracula",
"base": "dark",
"overrides": {
"claude": "#bd93f9",
"error": "#ff5555",
"success": "#50fa7b"
}
}

Claude Code پوشه‌ی ~/.claude/themes/ را تماشا می‌کند و وقتی فایلی تغییر کند دوباره بارگذاری می‌کند، پس ویرایش‌هایی که در ادیتورت می‌کنی بدونِ ری‌استارت روی یک نشستِ در حالِ اجرا اعمال می‌شوند.

مرجعِ زیر توکن‌هایی را که می‌توانی در overrides تنظیم کنی پوشش می‌دهد. ادیتورِ تعاملی در /theme همان توکن‌ها را با پیش‌نمایشِ زنده نشان می‌دهد، به‌علاوه‌ی چند accentِ تک‌منظوره مثلِ رنگ‌های صفحه‌ی onboarding که اینجا حذف شده‌اند.

مرجعِ توکن‌های رنگ

مثالِ زیر توکن‌هایی از چند گروهِ پایین را ترکیب می‌کند: accentِ برند، حاشیه‌ی plan mode، پس‌زمینه‌های diff، و پس‌زمینه‌ی پیامِ fullscreen.

{
"name": "Midnight",
"base": "dark",
"overrides": {
"claude": "#a78bfa",
"planMode": "#38bdf8",
"diffAdded": "#14532d",
"diffRemoved": "#7f1d1d",
"userMessageBackground": "#1e1b4b"
}
}

accentِ اصلیِ برند و سایه‌های متنِ پیش‌زمینه‌ای را که در سراسرِ رابط استفاده می‌شوند کنترل کن.

توکنچه چیزی را کنترل می‌کند
claudeaccentِ اصلیِ برند، که برای اسپینر و برچسبِ دستیار استفاده می‌شود
textمتنِ پیش‌زمینه‌ی پیش‌فرض
inverseTextمتنی که روی یک پس‌زمینه‌ی رنگی کشیده می‌شود، مثلِ نشان‌های وضعیت
inactiveمتنِ ثانویه مثلِ نکته‌ها، timestampها و آیتم‌های غیرفعال
subtleحاشیه‌های کم‌رنگ و متنِ ثانویه‌ی کم‌اهمیت
suggestionپیشنهادهای autocomplete و هایلایتِ انتخاب در انتخاب‌گرها
permissionحاشیه‌های دیالوگ، شاملِ پرامپت‌های دسترسی و انتخاب‌گرها
rememberنشانگرهای حافظه و CLAUDE.md

حالت‌های موفقیت، شکست و هشدار را در پیام‌ها و نشانگرها علامت بزن.

توکنچه چیزی را کنترل می‌کند
successپیام‌های موفقیت و بررسی‌های موفق
errorپیام‌های خطا و شکست‌ها
warningهشدارها، پیام‌های احتیاط، و حاشیه‌ی auto mode
mergedوضعیتِ pull requestِ merge‌شده

جعبه‌ی ورودی و نشانگرهای حالت

Section titled “جعبه‌ی ورودی و نشانگرهای حالت”

رنگِ حاشیه‌ی جعبه‌ی ورودی و accentی را که هنگامِ فعال‌بودنِ یک permission mode یا نشانگر نشان داده می‌شود تنظیم کن.

توکنچه چیزی را کنترل می‌کند
promptBorderحاشیه‌ی جعبه‌ی ورودی در permission modeِ پیش‌فرض
planModeaccent و حاشیه‌ی plan mode
autoAcceptaccent و حاشیه‌ی حالتِ accept-edits
bashBorderحاشیه‌ی جعبه‌ی ورودی هنگامِ واردکردنِ یک دستورِ شلِ !
ideنشانگرِ اتصالِ IDE
fastModeنشانگرِ fast mode

کدِ افزوده‌شده و حذف‌شده را در ویرایش‌های فایل و بازبینی‌ها رنگ کن.

توکنچه چیزی را کنترل می‌کند
diffAddedپس‌زمینه‌ی خط‌های افزوده‌شده
diffRemovedپس‌زمینه‌ی خط‌های حذف‌شده
diffAddedDimmedپس‌زمینه‌ی کانتکستِ بدون‌تغییر نزدیکِ خط‌های افزوده‌شده
diffRemovedDimmedپس‌زمینه‌ی کانتکستِ بدون‌تغییر نزدیکِ خط‌های حذف‌شده
diffAddedWordهایلایتِ کلمه‌ای در داخلِ یک خطِ افزوده‌شده
diffRemovedWordهایلایتِ کلمه‌ای در داخلِ یک خطِ حذف‌شده

فقط در حالتِ رندرِ fullscreen اعمال می‌شوند، جایی که پیام‌ها پس‌زمینه‌ی پُرشده دارند.

توکنچه چیزی را کنترل می‌کند
userMessageBackgroundپس‌زمینه‌ی پشتِ پیام‌های تو در transcript
userMessageBackgroundHoverپس‌زمینه‌ی پشتِ یک پیام هنگامِ hover یا باز شدن
messageActionsBackgroundپس‌زمینه‌ی پشتِ پیامِ انتخاب‌شده وقتی نوارِ اقدام باز است
bashMessageBackgroundColorپس‌زمینه‌ی پشتِ ورودی‌های دستورِ شلِ ! در transcript
memoryBackgroundColorپس‌زمینه‌ی پشتِ ورودی‌های حافظه‌ی # در transcript
selectionBgپس‌زمینه‌ی متنی که با ماوس انتخاب شده

سنجه‌ی استفاده و برچسب‌های گوینده

Section titled “سنجه‌ی استفاده و برچسب‌های گوینده”

نواری را که در نمای /usage نشان داده می‌شود و برچسب‌هایی را که پیام‌های تو را از پیام‌های Claude متمایز می‌کنند تنظیم کن.

توکنچه چیزی را کنترل می‌کند
rate_limit_fillبخشِ پُرشده‌ی سنجه‌ی استفاده
rate_limit_emptyبخشِ پُرنشده‌ی سنجه‌ی استفاده
briefLabelYouرنگِ برچسبِ You روی پیام‌های تو
briefLabelClaudeرنگِ برچسبِ Claude روی پیام‌های دستیار

گونه‌های shimmer و رنگ‌های ساب‌ایجنت

Section titled “گونه‌های shimmer و رنگ‌های ساب‌ایجنت”

چند توکن یک گونه‌ی shimmerِ جفت‌شده دارند که رنگِ روشن‌ترِ به‌کاررفته در گرادیانِ متحرکِ اسپینر را فراهم می‌کند. اگر انیمیشن ناهماهنگ به‌نظر رسید، shimmer را در کنارِ توکنِ پایه‌اش override کن.

  • claude و claudeShimmer
  • warning و warningShimmer
  • permission و permissionShimmer
  • promptBorder و promptBorderShimmer
  • inactive و inactiveShimmer
  • fastMode و fastModeShimmer

هر ساب‌ایجنت و کارِ موازی در یکی از هشت رنگِ نام‌دار نشان داده می‌شود تا بتوانی آن‌ها را در transcript از هم تشخیص دهی. نام‌های توکن از الگوی <color>_FOR_SUBAGENTS_ONLY پیروی می‌کنند، که در آن <color> یکی از red، blue، green، yellow، purple، orange، pink یا cyan است. این‌ها را override کن تا ظاهرِ هر رنگِ نام‌دار را تغییر دهی. مثلاً یک ساب‌ایجنت با color: blue در تعریفش با مقدارِ blue_FOR_SUBAGENTS_ONLY کشیده می‌شود.

کلیدواژه‌های ultrathink و ultraplan در ورودیِ پرامپت با یک گرادیانِ رنگین‌کمانیِ هفت‌رنگ رندر می‌شوند. نام‌های توکن از الگوی rainbow_<color> و rainbow_<color>_shimmer پیروی می‌کنند، که در آن <color> یکی از red، orange، yellow، green، blue، indigo یا violet است.

اگر نمایش حین کارِ Claude چشمک می‌زند یا موقعیتِ اسکرول می‌پرد، به حالتِ رندرِ fullscreen تعویض کن. این به‌جای افزودن به scrollbackِ معمولی‌ات، روی صفحه‌ای جداگانه می‌کشد که ترمینال برای اپلیکیشن‌های تمام‌صفحه کنار می‌گذارد، که مصرفِ حافظه را ثابت نگه می‌دارد و برای اسکرول و انتخاب پشتیبانیِ ماوس اضافه می‌کند. در این حالت به‌جای scrollbackِ بومیِ ترمینالت، با ماوس یا PageUp در داخلِ Claude Code اسکرول می‌کنی؛ برای اینکه ببینی چطور جست‌وجو و کپی کنی صفحه‌ی fullscreen را ببین.

/tui fullscreen را اجرا کن تا در نشستِ فعلی با گفت‌وگوی دست‌نخورده تعویض کنی. برای اینکه پیش‌فرضش کنی، متغیرِ محیطیِ CLAUDE_CODE_NO_FLICKER را پیش از راه‌اندازیِ Claude Code تنظیم کن:

Terminal window
CLAUDE_CODE_NO_FLICKER=1 claude
Terminal window
$env:CLAUDE_CODE_NO_FLICKER = "1"; claude
{
"env": {
"CLAUDE_CODE_NO_FLICKER": "1"
}
}

وقتی بیش از ۱۰٬۰۰۰ کاراکتر در پرامپت paste می‌کنی، Claude Code ورودی را به یک placeholderِ [Pasted text] جمع می‌کند تا جعبه‌ی ورودی قابل‌استفاده بماند. محتوای کامل وقتی ارسال کنی همچنان به Claude فرستاده می‌شود.

ترمینالِ یکپارچه‌ی VS Code می‌تواند پیش از رسیدنِ pasteهای خیلی بزرگ به Claude Code، کاراکترهایی را بیندازد، پس آنجا ورک‌فلوهای مبتنی‌بر فایل را ترجیح بده. برای ورودی‌های خیلی بزرگ مثلِ کلِ فایل‌ها یا لاگ‌های طولانی، محتوا را در یک فایل بنویس و از Claude بخواه آن را بخواند به‌جای paste کردن. این کار، transcriptِ گفت‌وگو را خوانا نگه می‌دارد و به Claude اجازه می‌دهد در نوبت‌های بعدی فایل را با مسیرش ارجاع دهد.

ویرایشِ پرامپت‌ها با keybindingهای Vim

Section titled “ویرایشِ پرامپت‌ها با keybindingهای Vim”

Claude Code یک حالتِ ویرایشِ سبکِ Vim برای ورودیِ پرامپت دارد. آن را از طریقِ /config → Editor mode فعال کن، یا با تنظیمِ editorMode روی "vim" در ~/.claude/settings.json. برای خاموش‌کردن، Editor mode را به normal برگردان.

حالتِ Vim زیرمجموعه‌ای از motionها و operatorهای حالتِ NORMAL و VISUAL را پشتیبانی می‌کند، مثلِ پیمایشِ hjkl، انتخابِ v/V، و d/c/y با text objectها. برای جدولِ کاملِ کلیدها مرجعِ حالتِ ادیتورِ Vim را ببین. motionهای Vim از طریقِ فایلِ keybindings قابلِ نگاشتِ مجدد نیستند.

فشردنِ Enter در حالتِ INSERT هنوز پرامپتت را ارسال می‌کند، برخلافِ Vimِ استاندارد. به‌جایش از o یا O در حالتِ NORMAL، یا Ctrl+J، برای درجِ خطِ جدید استفاده کن.

  • حالتِ تعاملی: مرجعِ کاملِ میان‌برهای صفحه‌کلید و جدولِ کلیدهای Vim
  • Keybindings: هر میان‌برِ Claude Code را نگاشتِ مجدد کن، از جمله Enter و Shift+Enter
  • رندرِ fullscreen: جزئیاتِ اسکرول، جست‌وجو و کپی در حالتِ fullscreen
  • راهنمای hooks: مثال‌های بیشترِ Notification hook برای Linux و Windows
  • عیب‌یابی: رفعِ مشکلاتِ بیرون از پیکربندیِ ترمینال