- Хотите отслеживать использование контекстного окна во время работы
- Нужно отслеживать затраты сеанса
- Работаете в нескольких сеансах и нужно их различать
- Хотите, чтобы ветка git и статус всегда были видны
esc для прерывания, ? для сочетаний клавиш и подсказку удерживайте пробел для голоса голосовой диктовки. Чтобы добавить интерактивные значки ссылок в нижний колонтитул, когда в беседе появляется ID, без написания скрипта, вместо этого настройте footerLinksRegexes.
Вот пример многострочной строки состояния, которая отображает информацию git в первой строке и цветовую полосу контекста во второй.

Настройка строки состояния
Используйте команду/statusline для автоматического создания скрипта Claude Code, или вручную создайте скрипт и добавьте его в ваши настройки.
Использование команды /statusline
Команда/statusline принимает инструкции на естественном языке, описывающие то, что вы хотите отображать. Claude Code генерирует файл скрипта в ~/.claude/ и автоматически обновляет ваши настройки:
Ручная настройка строки состояния
Добавьте полеstatusLine в ваши пользовательские настройки (~/.claude/settings.json, где ~ — это ваш домашний каталог) или настройки проекта. Установите type на "command" и укажите command на путь скрипта или встроенную команду оболочки. Для полного пошагового руководства по созданию скрипта см. Построение строки состояния пошагово.
command запускается в оболочке, поэтому вы также можете использовать встроенные команды вместо файла скрипта. Этот пример использует jq для разбора входных данных JSON и отображения имени модели и процента контекста:
padding добавляет дополнительное горизонтальное расстояние (в символах) к содержимому строки состояния. По умолчанию 0. Это заполнение добавляется к встроенному расстоянию интерфейса, поэтому оно управляет относительным отступом, а не абсолютным расстоянием от края терминала.
Необязательное поле refreshInterval повторно запускает вашу команду каждые N секунд в дополнение к обновлениям, управляемым событиями. Минимум — 1. Установите это, когда ваша строка состояния отображает данные на основе времени, такие как часы, или когда фоновые подагенты изменяют состояние git, пока основной сеанс неактивен. Оставьте это не установленным, чтобы запускать только при событиях.
Необязательное поле hideVimModeIndicator подавляет встроенный текст -- INSERT -- под приглашением. Установите это на true, когда ваш скрипт отображает vim.mode самостоятельно, чтобы режим не отображался дважды.
Отключение строки состояния
Запустите/statusline и попросите её удалить или очистить вашу строку состояния (например, /statusline delete, /statusline clear, /statusline remove it). Вы также можете вручную удалить поле statusLine из вашего settings.json.
Построение строки состояния пошагово
Это пошаговое руководство показывает, что/statusline настраивает для вас путём ручного создания строки состояния, которая отображает текущую модель, рабочий каталог и процент использования контекстного окна.
Запуск
/statusline с описанием того, что вы хотите, настраивает всё это автоматически.
1
Создайте скрипт, который читает JSON и выводит результат
Claude Code отправляет данные JSON в ваш скрипт через stdin. Этот скрипт использует
jq, парсер JSON командной строки, который вам может потребоваться установить, для извлечения имени модели, каталога и процента контекста, а затем выводит отформатированную строку.Сохраните это в ~/.claude/statusline.sh (где ~ — это ваш домашний каталог, например /Users/username на macOS или /home/username на Linux):2
Сделайте его исполняемым
Отметьте скрипт как исполняемый, чтобы ваша оболочка могла его запустить:
3
Добавьте в настройки
Скажите Claude Code запустить ваш скрипт как строку состояния. Добавьте эту конфигурацию в Ваша строка состояния появляется в нижней части интерфейса. Claude Code автоматически перезагружает настройки и запускает ваш скрипт сразу же после сохранения файла.
~/.claude/settings.json, которая устанавливает type на "command" (означает «запустить эту команду оболочки») и указывает command на ваш скрипт:Как работают строки состояния
Claude Code запускает ваш скрипт с данными сессии JSON на stdin и отображает всё, что скрипт выводит в stdout.Строка состояния работает локально и не потребляет токены API. Она временно скрывается во время определённых взаимодействий с пользовательским интерфейсом, включая меню справки и запросы разрешений.
Когда обновляется строка состояния
Ваш скрипт запускается один раз при запуске сессии, включая случаи, когда вы возобновляете её. После этого он запускается снова, когда:- Поступает новое сообщение ассистента
- Завершается
/compact - Изменяется режим разрешений
- Переключается режим Vim
- Вы изменяете
commandв настройкахstatusLine - Истекает таймер
refreshInterval, если вы его установили - Окно ограничения частоты запросов в данных, которые последними получил ваш скрипт, достигает времени
resets_at - Тёплый кэш промптов в данных, которые последними получил ваш скрипт, достигает времени
expires_at
command пропускает дебаунс: Claude Code запускает новую команду сразу же. Если новое обновление срабатывает, пока ваш скрипт всё ещё работает, Claude Code отменяет выполняющийся скрипт. Если вы отредактируете свой скрипт, изменения появятся в следующий раз, когда триггер обновления его повторно запустит.
Триггеры, управляемые событиями, могут затихнуть, когда основная сессия неактивна, например, пока координатор ждёт фоновых субагентов. Чтобы сегменты на основе времени или из внешних источников оставались актуальными во время периодов неактивности, установите refreshInterval, чтобы также повторно запускать команду по фиксированному таймеру.
Что может выводить ваш скрипт
Ваш скрипт может выводить не только одну строку простого текста:- Несколько строк: каждый оператор
echoилиprintотображается как отдельная строка. См. пример многострочности. - Цвета: используйте коды экранирования ANSI, такие как
\033[32mдля зелёного (терминал должен их поддерживать). См. пример статуса git. - Ссылки: используйте последовательности экранирования OSC 8 для создания кликабельного текста (Cmd+клик на macOS, Ctrl+клик на Windows/Linux). Требуется терминал, поддерживающий гиперссылки, такой как iTerm2, Kitty или WezTerm. См. пример кликабельных ссылок.
Размер вывода в соответствии с терминалом
Claude Code захватывает вывод вашего скрипта вместо прямого подключения к терминалу, поэтомуtput cols и определение ширины на уровне языка не могут прочитать размер терминала изнутри скрипта. Вместо этого читайте переменные окружения COLUMNS и LINES. Claude Code устанавливает эти значения в соответствии с текущими размерами терминала перед запуском вашего скрипта.
Доступные данные
Claude Code отправляет следующие поля JSON в ваш скрипт через stdin:Полная схема JSON
Полная схема JSON
Ваша команда строки состояния получает эту структуру JSON через stdin:Поля, которые могут отсутствовать (не присутствуют в JSON):
session_name: появляется, когда пользовательское имя было установлено с--nameили/rename, или после того как существует автоматически сгенерированный заголовок сеанса. Имя отображения по умолчанию, напримерmy-app-3f, не заполняет это полеprompt_id: появляется только после первого ввода пользователяworkspace.git_worktree: появляется только когда текущий каталог находится внутри связанного git worktreeworkspace.repo: появляется только внутри git репозитория с настроенным удалённым хранилищемorigineffort: появляется только когда текущая модель поддерживает параметр reasoning effortvim: появляется только когда режим vim включенagent: появляется только при запуске с флагом--agentили настроенными параметрами агентаpr: появляется только пока открытый PR или GitLab merge request найден для текущей ветки, и удаляется после того как он будет объединён или закрыт.pr.review_stateиpr.kindмогут быть независимо отсутствующимиworktree: появляется только во время сеанса в worktree сеансе. Когда присутствует,branchиoriginal_branchтакже могут отсутствовать для worktrees на основе hooksrate_limits: появляется только для подписчиков Claude.ai Pro и Max, или за шлюзом Claude apps, который устанавливает лимит расходов для вас, и только после первого ответа API в сеансе. Каждое окно (five_hour,seven_day,spend_limit) может быть независимо отсутствующим, и Claude Code удаляет окно после того как его времяresets_atпройдёт. Используйтеjq -r '.rate_limits.five_hour.used_percentage // empty'для корректной обработки отсутствия.prompt_cache: появляется после первого ответа API основного разговора. Смотрите поля prompt cache
null:context_window.current_usage:nullперед первым вызовом API в сеансе и снова после/compactдо следующего вызова API, который его переполнитcontext_window.used_percentage,context_window.remaining_percentage: могут бытьnullв начале сеанса
Поля контекстного окна
Объектcontext_window описывает живое контекстное окно из последнего ответа API.
- Совокупные итоги (
total_input_tokens,total_output_tokens): токены, находящиеся в контекстном окне.total_input_tokens— это суммаinput_tokens,cache_creation_input_tokensиcache_read_input_tokens;total_output_tokens— это выходные токены из последнего ответа. Оба равны0перед первым ответом API. - Использование по компонентам (
current_usage): те же подсчёты токенов, разбитые по категориям. Используйте это, когда вам нужны попадания в кэш отдельно от свежего входа.
current_usage содержит:
input_tokens: входные токены в текущем контекстеoutput_tokens: выходные токены, которые были сгенерированыcache_creation_input_tokens: токены, записанные в кэшcache_read_input_tokens: токены, прочитанные из кэша
used_percentage рассчитывается только из входных токенов: input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Оно не включает output_tokens.
Если вы рассчитываете процент контекста вручную из current_usage, используйте ту же формулу только для входных данных, чтобы соответствовать used_percentage.
Объект current_usage равен null перед первым вызовом API в сеансе и снова сразу после /compact до следующего вызова API, который его переполнит.
Поля лимита расходов
За шлюзом Claude apps с лимитами расходов объектrate_limits.spend_limit описывает лимит расходов, который применяется к вам. Он появляется после первого ответа API в сессии и требует Claude Code v2.1.251 или позже. Ваш скрипт получает его поля по разным графикам:
used_percentageиresets_at: приходят с каждым ответом, поэтому присутствуют всегда, когда присутствуетspend_limit.used_percentageварьируется от 0 до 100 или выше 100, когда вы превышаете лимит, аresets_at— это секунды эпохи Unix, когда сбрасывается период лимита.used_usd,limit_usdиperiod: ваши предполагаемые расходы на данный момент и ваш лимит в долларах США, а также период, на который распространяется лимит:daily,weeklyилиmonthly. Шлюз вычисляетused_usdна основе подсчётов токенов, поэтому это оценка, а не выставленная к оплате сумма. Claude Code получает их от шлюза отдельным запросом примерно каждые пять минут, пока вы отправляете запросы. Суммы в долларах могут быть примерно на пять минут старше, чемused_percentage, поэтому эти значения могут ненадолго расходиться. Требуется v2.1.284 или позже как для Claude Code, так и для шлюза.
used_usd, limit_usd и period необязательными, даже когда spend_limit присутствует. Ваш скрипт получает процент раньше них, и они остаются отсутствующими, если вы установили CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, что отключает этот запрос. Считывайте каждое из них с резервным вариантом в скрипте, например jq -r '.rate_limits.spend_limit.used_usd // empty'.
Поля prompt cache
Объектprompt_cache суммирует, как основной разговор сеанса использует prompt cache. Claude Code вычисляет его из подсчётов токенов кэша в ответах API, поэтому он работает на каждом поставщике.
Объект появляется после первого ответа API основного разговора. Claude Code не учитывает запросы подагентов в этой статистике. Требуется Claude Code v2.1.251 или позже.
Таблица перечисляет каждое поле с его значением. Временные метки — это секунды эпохи Unix, то же самое, что и rate_limits.*.resets_at. Строка состояния обычно показывает одно или два из них; warm и hit_ratio наиболее прямо суммируют состояние кэша.
Claude Code показывает ту же статистику в терминале на строке
/usage команды Prompt cache (main).
Причина последнего промаха
Объектlast_miss_cause сообщает, что Claude Code определил как вероятную причину самого последнего промаха. Его массив causes содержит одно или несколько названий причин, таких как tools_changed, system_prompt_changed, ttl_expired_5m или likely_server_side. Объект равен null до первого промаха сеанса и снова всякий раз, когда Claude Code не может определить причину самого последнего промаха. Требуется Claude Code v2.1.260 или позже.
Две причины добавляют подсчёты к объекту:
tools_addedиtools_removed: сtools_changed, сколько инструментов было добавлено в запрос или удалено из негоsystem_char_delta: сsystem_prompt_changed, изменение длины системного приглашения в символах
Примеры
Эти примеры показывают распространённые паттерны строк состояния. Чтобы использовать любой пример:- Сохраните скрипт в файл, например
~/.claude/statusline.sh(или.py/.js) - Сделайте его исполняемым:
chmod +x ~/.claude/statusline.sh - Добавьте путь в ваши настройки
jq для разбора JSON. Python и Node.js имеют встроенный разбор JSON.
Использование контекстного окна
Отобразите текущую модель и использование контекстного окна с визуальной полосой прогресса. Каждый скрипт читает JSON из stdin, извлекает полеused_percentage и строит 10-символьную полосу, где заполненные блоки (▓) представляют использование:

Статус git с цветами
Показывает ветку git с цветовыми индикаторами для подготовленных и изменённых файлов. Этот скрипт использует коды экранирования ANSI для цветов терминала:\033[32m — зелёный, \033[33m — жёлтый и \033[0m — сброс на значение по умолчанию.

Отслеживание затрат и продолжительности
Отслеживайте затраты API вашего сеанса и прошедшее время. Полеcost.total_cost_usd накапливает стоимость всех вызовов API в текущем сеансе. Поле cost.total_duration_ms измеряет общее прошедшее время с момента начала сеанса, а cost.total_api_duration_ms отслеживает только время, потраченное на ожидание ответов API.
Каждый скрипт форматирует стоимость как валюту и преобразует миллисекунды в минуты и секунды:

Отображение нескольких строк
Ваш скрипт может выводить несколько строк для создания более богатого отображения.
print или echo создаёт отдельную строку:
Кликабельные ссылки
Этот пример создаёт кликабельную ссылку на ваш репозиторий GitHub. Удерживайте Cmd (macOS) или Ctrl (Windows/Linux) и нажмите, чтобы открыть ссылку в браузере.
printf '%b', которая более надёжно интерпретирует экранирующие последовательности, чем echo -e в разных оболочках:
Использование лимита скорости
Отобразите в строке состояния использование ограничения частоты запросов подписки claude.ai или ваши расходы относительно лимита расходов шлюза приложений Claude. Для подписчиков объектrate_limits содержит скользящее окно five_hour и еженедельное окно seven_day. Каждое окно предоставляет used_percentage (от 0 до 100) и resets_at (секунды эпохи Unix, когда окно сбрасывается). За шлюзом считывайте объект spend_limit, описанный в разделе поля лимита расходов.
Объект rate_limits присутствует только для подписчиков claude.ai Pro и Max или за шлюзом приложений Claude с лимитами расходов, и только после первого ответа API. Каждый скрипт корректно обрабатывает отсутствующие поля, а за шлюзом выводит spend: $314.12 / $500 или spend: 63%, пока поля в долларах отсутствуют:
Кэширование дорогостоящих операций
Ваш скрипт строки состояния запускается часто во время активных сеансов. Команды, такие какgit status или git diff, могут быть медленными, особенно в больших репозиториях. Этот пример кэширует информацию git во временный файл и обновляет её только каждые 5 секунд.
Имя файла кэша должно быть стабильным во время вызовов строки состояния в рамках сеанса, но уникальным для разных сеансов, чтобы одновременные сеансы в разных репозиториях не читали состояние git друг друга. Идентификаторы на основе процесса, такие как $$, os.getpid() или process.pid, изменяются при каждом вызове и нарушают кэш. Вместо этого используйте session_id из входных данных JSON: он стабилен в течение жизни сеанса и уникален для каждого сеанса.
Каждый скрипт проверяет, отсутствует ли файл кэша или он старше 5 секунд, перед запуском команд git:
Конфигурация Windows
На Windows Claude Code запускает команды строки состояния через Git Bash, когда Git Bash установлен, или через PowerShell, когда Git Bash отсутствует. Git Bash обрабатывает неэкранированные обратные слэши как символы экранирования, поэтому путь в стиле Windows, такой какC:\Users\username\script.mjs, достигает средства запуска скрипта с удалёнными разделителями и команда не выполняется без видимой ошибки. Записывайте пути к файлам в строке command с прямыми слэшами, как показано в примерах ниже. Сокращение ~ также работает и расширяется до вашего домашнего каталога Windows.
Чтобы запустить скрипт PowerShell как вашу строку состояния, вызовите его через powershell. Это работает независимо от того, маршрутизирует ли Claude Code команду через Git Bash или PowerShell:
Строки состояния подагентов
ПараметрsubagentStatusLine отображает пользовательское тело строки для каждого подагента, показанного на панели агентов ниже приглашения. Используйте его для замены строки по умолчанию name · description · token count на ваше собственное форматирование.
columns с используемой шириной строки и массив tasks с одной записью на строку, описанный в разделе Поля задачи.
Напишите одну строку JSON в stdout для каждой строки, которую вы хотите переопределить, в форме {"id": "<task id>", "content": "<row body>"}. Строка content отображается как есть, включая цвета ANSI и гиперссылки OSC 8. Пропустите id задачи, чтобы сохранить отображение по умолчанию для этой строки; выведите пустую строку content, чтобы скрыть её.
Те же ворота доверия, disableAllHooks и allowManagedHooksOnly, которые применяются к statusLine, применяются здесь. Плагины могут поставлять subagentStatusLine по умолчанию в своём settings.json, но в отличие от hooks, значения плагинов не запускаются под allowManagedHooksOnly даже когда плагин принудительно включен в управляемых параметрах enabledPlugins.
Поля задачи
Каждая запись в массивеtasks описывает одну строку субагента с помощью полей ниже. Поля, помеченные как необязательные, опускаются, когда у них нет значения, поэтому учитывайте их возможное отсутствие в вашем скрипте.
Советы
- Тестирование с макетными входными данными:
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh - Сохраняйте вывод коротким: строка состояния имеет ограниченную ширину, поэтому длинный вывод может быть обрезан или неправильно обёрнут
- Кэшируйте медленные операции: ваш скрипт запускается часто во время активных сеансов, поэтому команды, такие как
git status, могут вызвать задержку. См. пример кэширования для того, как это обработать.
Устранение неполадок
Если строка состояния пустая, начните с раздела Строка состояния не отображается. Папка, которой вы не доверяете, и скрипт, завершающийся с ошибкой, также оставляют её пустой, как описано в разделах Требуется доверие рабочего пространства и Ошибки скрипта или зависания.Строка состояния не отображается
Если вы настроили строку состояния, но внизу интерфейса ничего не отображается, выполните следующие проверки:- Убедитесь, что ваш скрипт исполняемый:
chmod +x ~/.claude/statusline.sh - Проверьте, что ваш скрипт выводит в stdout, а не stderr
- Запустите ваш скрипт вручную, чтобы убедиться, что он выводит результат
- В Windows с установленным Git Bash обратные слэши в пути
commandвероятно будут использованы как символы экранирования перед запуском скрипта. Используйте прямые слэши в пути. См. Конфигурация Windows. - Если
disableAllHooksустановлен наtrueвне управляемых настроек после применения приоритета настроек, Claude Code запускает толькоstatusLineиз управляемых настроек, и без управляемогоstatusLineстрока состояния отключена. Удалите эту настройку или установите её наfalseв файле, который её устанавливает, чтобы повторно включить. См.disableAllHooks. - Если ваша организация устанавливает
allowManagedHooksOnlyв управляемых настройках, ваша пользовательская строка состояния исчезает без предупреждения: вы можете получить строку состояния только из значенияstatusLineв этих управляемых настройках. См. что запускается подallowManagedHooksOnlyдля полного поведения и спросите у вашего администратора, применяется ли эта настройка к вам. - Запустите
claude --debug, чтобы записать stderr вашего скрипта при каждом вызове строки состояния и его код выхода при первом вызове в сессии - Попросите Claude прочитать ваш файл настроек и выполнить команду
statusLineнапрямую, чтобы выявить ошибки
Строка состояния показывает -- или пустые значения
Поля могут быть null до завершения первого ответа API, поэтому обрабатывайте значения null в вашем скрипте с резервными вариантами, такими как // 0 в jq. Перезапустите Claude Code, если значения остаются пустыми после нескольких сообщений.
Процент контекста показывает неожиданные значения
Строка состояния сообщает количества из последнего ответа API, в то время как/context добавляет оценку для сообщений, добавленных с момента этого ответа, поэтому /context может показывать более высокие значения до следующего ответа. Используйте used_percentage для простейшего точного состояния контекста. Формулу, по которой вычисляется used_percentage, см. в разделе Поля контекстного окна.
Ссылки OSC 8 не кликабельны
Будет ли ссылка кликабельной, зависит от вашего терминала, от того, обнаруживает ли Claude Code в нём поддержку гиперссылок, от того, удаляют ли SSH или tmux управляющую последовательность, и от того, как ваш скрипт её выводит:- Убедитесь, что ваш терминал поддерживает гиперссылки OSC 8 (iTerm2, Kitty, WezTerm)
- Terminal.app не поддерживает кликабельные ссылки
-
Если текст ссылки отображается, но не кликабелен, Claude Code может не обнаружить поддержку гиперссылок в вашем терминале. Установите переменную окружения
FORCE_HYPERLINKдля переопределения обнаружения перед запуском Claude Code:В PowerShell сначала установите переменную в текущей сессии: - Сессии SSH и tmux могут удалять последовательности OSC в зависимости от конфигурации
-
Если последовательности экранирования отображаются как буквальный текст, например
\e]8;;, используйтеprintf '%b'вместоecho -eдля более надёжной обработки экранирования
Глюки отображения с последовательностями экранирования
Сложные последовательности экранирования (цвета ANSI, ссылки OSC 8) могут иногда вызывать искажённый вывод, если они перекрываются с другими обновлениями пользовательского интерфейса. Многострочные строки состояния с кодами экранирования более подвержены проблемам отображения, чем однострочный простой текст. Если вы видите повреждённый текст, попробуйте упростить ваш скрипт до простого текстового вывода.Требуется доверие рабочего пространства
Пока вы не примете диалог доверия рабочего пространства, строка состояния остаётся пустой. ПосколькуstatusLine выполняет команду оболочки, Claude Code запускает её под тем же правилом доверия рабочего пространства, что и хуки в файлах настроек. Достаточно принять диалог для папки или для родительского каталога, чьё доверие распространяется на неё.
До этого claude --debug записывает в лог Status line command skipped: workspace trust not accepted. Перезапустите Claude Code и примите диалог доверия, чтобы включить её.
Ошибки скрипта или зависания
Claude Code отображает вывод вашего скрипта только после того, как скрипт завершится с кодом 0:- Скрипты, которые выходят с ненулевыми кодами или не выводят результат, вызывают пустую строку состояния
- Медленные скрипты блокируют обновление строки состояния до их завершения. Держите скрипты быстрыми, чтобы избежать устаревшего вывода.
- Если новое обновление срабатывает, пока медленный скрипт работает, выполнение скрипта отменяется
- Протестируйте ваш скрипт независимо с макетными входными данными перед его настройкой
Уведомления делят строку со строкой состояния
Вне полноэкранного отображения Claude Code показывает уведомления на той же строке, что и ваша строка состояния. При полноэкранном отображении Claude Code выделяет уведомлениям отдельную строку.- Системные уведомления, такие как ошибки MCP-сервера и автоматические обновления, отображаются на правой стороне строки. Временные уведомления, такие как предупреждение о низком контексте, также циклически сменяются в этой области.
- Включение подробного режима добавляет в эту область счётчик токенов, который показывает размер вашего контекста согласно последнему ответу API, а не счётчик за ход рядом со спиннером
- На узких терминалах эти уведомления могут обрезать вывод вашей строки состояния