Claude Code statusline: настройка строки состояния и рабочий скрипт
Для быстрой настройки используйте /statusline, для собственного формата — команду statusLine. Скрипт ниже показывает модель, каталог, ветку Git, занятый контекст и оценку стоимости, сохраняя различие между нулём и отсутствующими данными.
Содержание

Строку состояния Claude Code можно настроить командой /statusline или собственным скриптом через ключ statusLine. В обоих случаях механизм один: Claude Code передаёт JSON в стандартный ввод команды, а её текстовый вывод показывает внизу интерфейса. Если нужен понятный и легко проверяемый вариант, начните с небольшого скрипта: модель, текущий каталог, ветка Git и процент занятого контекста обычно полезнее сложной темы.
Ниже есть полный пример на Python 3, тестовый JSON и ожидаемая строка. Он использует данные из стандартного ввода, а для обычной ветки Git выполняет только локальный запрос к переданному каталогу. Сетевых запросов, чтения учётных данных и истории разговоров в этом примере нет.
Какой способ настройки выбрать
Для личной настройки без ручного редактирования файлов введите в Claude Code:
/statusline Показывай модель, текущий каталог, ветку Git и занятый контекст. Если данных нет, выводи вопросительный знак. Стоимость подпиши как оценку в USD.Claude Code может создать скрипт в пользовательском каталоге конфигурации и обновить настройки. После генерации посмотрите, какую команду он добавил и что читает скрипт. Генерация — удобный способ получить исходный вариант; она сама по себе не доказывает, что выбранные поля существуют или что внешний инструмент работает без сети. Механизм описан в официальном руководстве по statusline.
| Что вам нужно | Подходящий вариант | Что проверить перед использованием |
|---|---|---|
| Быстро получить личную строку | /statusline с описанием результата | Содержимое созданного скрипта и команду в настройках |
| Самостоятельно выбирать поля и подписи | Ручной statusLine и скрипт ниже | Вывод на тестовом JSON, путь к Python и файлу |
| Одинаковое поведение у коллег | Скрипт в репозитории и общие настройки проекта | Доступность интерпретатора и переносимость пути у каждого участника |
| Настраивать темы и готовые элементы через меню | Сторонний инструмент, например ccstatusline | Его зависимости и источники данных для выбранных элементов |
Начинать с личной настройки проще: домашний путь не становится зависимостью всего проекта. Общую настройку имеет смысл добавлять, когда команда уже согласовала скрипт и способ его запуска.
Подключите собственный скрипт
В этом примере нужен Python 3; установка Claude Code не означает, что Python уже есть на машине. В терминале проверьте python3 --version. Создайте каталог ~/bin и сохраните следующий код в файл ~/bin/claude-status.py в UTF-8. Не запускайте скрипт без входных данных в интерактивном терминале: он ждёт JSON до закрытия стандартного ввода.

import json
import math
import os
import subprocess
import sys
import time
def obj(value):
return value if isinstance(value, dict) else {}
def text(value):
if not isinstance(value, str):
return ""
value = "".join(c if c.isprintable() else " " for c in value)
return " ".join(value.replace("|", "/").split())[:50]
def number(value):
if isinstance(value, bool) or not isinstance(value, (int, float)):
return None
return value if math.isfinite(value) else None
def percent(value):
value = number(value)
return f"{value:.0f} %" if value is not None and 0 <= value <= 100 else "?"
def git_branch(data, directory):
supplied = text(obj(data.get("worktree")).get("branch"))
if supplied:
return supplied
if not directory or not os.path.isdir(directory):
return "?"
def git(*args):
result = subprocess.run(
["git", "-C", directory, *args],
capture_output=True, text=True, timeout=0.4, check=False,
)
return text(result.stdout) if result.returncode == 0 else ""
try:
branch = git("symbolic-ref", "--quiet", "--short", "HEAD")
if branch:
return branch
commit = git("rev-parse", "--short", "HEAD")
return "detached:" + commit if commit else "—"
except (OSError, subprocess.TimeoutExpired):
return "?"
try:
raw = sys.stdin.read()
data = json.loads(raw) if raw.strip() else {}
if not isinstance(data, dict):
raise ValueError("ожидается объект JSON")
except (ValueError, RecursionError):
print("statusline: некорректный JSON", file=sys.stderr)
sys.exit(1)
model = obj(data.get("model"))
name = text(model.get("display_name")) or text(model.get("id")) or "модель ?"
workspace = obj(data.get("workspace"))
directory = workspace.get("current_dir") or data.get("cwd")
directory = directory if isinstance(directory, str) else ""
short_dir = text(directory.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1])
short_dir = short_dir or ("/" if directory == "/" else "каталог ?")
context = percent(obj(data.get("context_window")).get("used_percentage"))
cost = number(obj(data.get("cost")).get("total_cost_usd"))
estimate = f"{cost:.2f}".replace(".", ",") + " USD" if cost is not None and cost >= 0 else "?"
parts = [name, short_dir, "Git " + git_branch(data, directory),
"контекст " + context, "оценка " + estimate]
now = time.time()
limits = obj(data.get("rate_limits"))
for key, label in (("five_hour", "5 ч"), ("seven_day", "7 дней")):
window = obj(limits.get(key))
resets = number(window.get("resets_at"))
usage = percent(window.get("used_percentage"))
if resets is not None and resets > now and usage != "?":
parts.append(label + " " + usage)
print(" | ".join(parts))Скрипт сначала проверяет типы данных: null, строка вместо числа и отсутствующее поле дают ?. Настоящий числовой ноль остаётся нулём. Диагностика неверного JSON уходит в стандартный поток ошибок, а не в строку состояния. Функция text убирает управляющие символы и переносы строк из подписей.
Для Git приоритет имеет worktree.branch, если Claude Code его передал. В обычном репозитории скрипт запрашивает ветку через git -C именно в workspace.current_dir либо cwd, а не в каталоге, из которого случайно запустился Python. Ветка без первого коммита тоже определяется через symbolic-ref; отсоединённый HEAD отображается как detached:…. Знак — означает, что запросы не дали ни ветки, ни коммита; это бывает вне репозитория. ? означает отсутствие каталога, Git или превышение времени ожидания. Скрипт не проверяет незакоммиченные изменения, поэтому наличие имени ветки ничего не говорит о чистоте рабочего дерева.
В пользовательский файл ~/.claude/settings.json добавьте ключ statusLine, сохранив остальные настройки:
{
"statusLine": {
"type": "command",
"command": "python3 \"$HOME/bin/claude-status.py\""
}
}Это пример содержимого файла, а не указание заменить существующий файл целиком. Если там уже есть другие ключи, добавьте statusLine рядом с ними и проверьте запятые. При явном запуске через python3 файлу скрипта не нужен исполняемый бит; интерпретатору всё равно нужен доступ на чтение. Если команда python3 недоступна в среде Claude Code, укажите её полный путь.
Проверьте вывод на искусственном JSON
Сохраните рядом с собой файл statusline-test.json:
{
"model": {"id": "example-model", "display_name": "Claude Sonnet"},
"workspace": {"current_dir": "/example/проект"},
"worktree": {"branch": "feature/status"},
"context_window": {"used_percentage": 42},
"cost": {"total_cost_usd": 0.18}
}Передайте его в скрипт из терминала:
python3 "$HOME/bin/claude-status.py" < statusline-test.jsonОжидаемый вывод:
Claude Sonnet | проект | Git feature/status | контекст 42 % | оценка 0,18 USDВетка здесь тоже искусственная: наличие поля worktree.branch позволяет проверить формат без создания репозитория. Для проверки отсутствующих значений подайте пустой объект:
printf '%s' '{}' | python3 "$HOME/bin/claude-status.py"Результат:
модель ? | каталог ? | Git ? | контекст ? | оценка ?Признак успеха в терминале — ожидаемый текст в stdout и код завершения 0. После подключения признак успеха в Claude Code — та же структура строки с данными вашей сессии; до первого ответа часть значений может быть неизвестна. Форматирование, обработка искусственных данных и Git-переходы проверены локально на отдельных тестовых файлах. Работа в интерфейсе Claude Code, реальные лимиты аккаунта и запуск Windows-клиента в эту проверку не входили.
Какие данные показывает строка и как их читать
Точные имена полей важны: устаревший путь в JSON часто выглядит как «Claude Code перестал передавать данные». Текущая схема находится в документации statusline.
| Значение | Поле или источник | Что оно означает |
|---|---|---|
| Модель | model.display_name, запасной вариант model.id | model — объект, а не строка |
| Рабочий каталог | workspace.current_dir или cwd | Текущее место работы; workspace.project_dir — каталог запуска, он может отличаться |
| Ветка Git | Условное worktree.branch либо отдельный запрос Git | Общего поля git.branch в схеме нет |
| Занятый контекст | context_window.used_percentage | Доля входного контекста последнего ответа, а не расход подписки |
| Остаток контекста | context_window.remaining_percentage | Доля свободного контекстного окна, когда значение передано |
| Оценка стоимости сессии | cost.total_cost_usd | Клиентская оценка по ценам моделей, в USD |
| Пятичасовое и недельное окна | rate_limits.five_hour, rate_limits.seven_day | Необязательные данные об использовании соответствующего окна |
Процент контекста рассчитывается по входным токенам, включая создание и чтение кэша; выходные токены в этот процент не входят. Данные относятся к последнему ответу API. До первого ответа и сразу после /compact поле current_usage может быть null, а процент — ещё неизвестен. Команда /context дополнительно оценивает новые, пока не отправленные сообщения, поэтому её число может быть выше, чем в строке состояния. Это различие двух измерений, а не обязательно ошибка скрипта.
Оценка cost.total_cost_usd не является счётом и не подтверждает, чей аккаунт оплачивает запросы. Скрипт оставляет USD, не пересчитывая сумму в рубли без курса. Начиная с версии 2.1.211, /clear начинает новую сессию с нулевой оценкой; в старых версиях значение могло переноситься. Счётчики total_duration_ms и total_api_duration_ms, если вы решите их добавить, выражены в миллисекундах: первый считает время работы сессии, второй — ожидание API. Эти значения не дают остаток подписки. Описание стоимости и времени.
Почему лимиты могут отсутствовать
rate_limits передаётся после первого ответа для подписок claude.ai Pro/Max или Claude apps gateway с лимитами расходов. Отдельные окна могут отсутствовать независимо друг от друга. used_percentage у пятичасового и недельного окна означает использованную долю, а resets_at — время сброса в секундах Unix. После истечения окна оно удаляется из входных данных. Пример выше также скрывает уже истёкшее окно, если оно ещё осталось в переданном JSON. Неизвестное значение не превращается в «0 %» или «безлимит». Условия передачи лимитов.
У gateway есть отдельное spend_limit: его процент может превышать 100 и требует версии 2.1.251. Дополнительные used_usd, limit_usd и period требуют версии 2.1.284 и на клиенте, и на gateway; даже тогда эти поля необязательны. Суммы обновляются отдельно примерно раз в пять минут и могут отставать от процента. Поэтому наш скрипт не пытается применять к spend_limit ограничения пятичасового окна или вычислять недостающие суммы.
Дополнительный блок prompt_cache тоже не заменяет общий расход: он описывает только основную беседу и зависит от переданных провайдером счётчиков кэша. Его hit_ratio — доля от 0 до 1, а не уже готовый процент. Для первого варианта строки эти показатели можно оставить за пределами экрана.
Где сохранить настройки для себя и команды
Для личного использования подходят пользовательские настройки ~/.claude/settings.json. Личные настройки одного проекта обычно находятся в .claude/settings.local.json, общие — в .claude/settings.json. В Git/worktree расположение локального файла может относиться к основному checkout; есть платформенные исключения. Если файл не действует, проверьте загруженные источники через /status, а не создавайте копии наугад. Области настроек Claude Code.
Приоритет одного и того же ключа: управляемые настройки организации, затем --settings, локальные настройки проекта, общие настройки проекта и пользовательские. Отсутствующий ключ не отменяет нижележащее значение. Раздел Setting sources в /status показывает загруженные файлы, но не определяет источник каждого отдельного ключа.
Для общей настройки положите скрипт, например, в tools/claude-status.py и согласуйте запуск python3 tools/claude-status.py. Относительный путь должен разрешаться из каталога, в котором команда действительно выполняется; при переходе между каталогами это нужно учитывать. Личный абсолютный путь в домашний каталог коллеги не подойдёт. Общие настройки читаются из основной рабочей директории; начиная с 2.1.246, /cd загружает настройки новой директории. Перед коммитом проверьте общий путь и наличие Python у участников. Этот пример не требует хранить ключ API в репозитории.
Большинство настроек перечитываются после сохранения, а изменение самой команды statusLine запускает её сразу. Для отключения удалите только ключ statusLine в нужной области либо попросите /statusline убрать строку; остальные настройки сохраните. Если строка задана на более высоком уровне, удаление личного ключа её не отменит. Правила загрузки настроек.
Когда строка обновляется и почему данные отстают
Claude Code запускает команду при старте или возобновлении сессии, после сообщения ассистента, завершения /compact, смены режима разрешений или Vim и других предусмотренных событий. Обновления объединяются с задержкой 300 мс; новое обновление отменяет ещё выполняющийся скрипт. Изменение файла скрипта станет видно при следующем запуске команды. События обновления.
Если в обычном репозитории ветку получает локальный запрос Git, добавьте таймер, чтобы повторять этот запрос и во время простоя. В объекте statusLine укажите:
"refreshInterval": 10Это интервал в секундах, минимальное значение — 1. Он заново запускает команду, но не делает данные последнего API-ответа свежим измерением: контекст или оценка, полученная от сервиса, не обязаны измениться. Таймер полезен для внешнего относительно JSON состояния, например локальной ветки, или для зависящих от времени подписей.
В нашем скрипте нет кэша и проверки всех изменённых файлов. Каждый Git-запрос ограничен 0,4 секунды; это ограничение ожидания запроса, а не измеренная скорость всей строки. Если позже добавите кэш, учитывайте и сессию, и рабочий каталог: один session_id не предотвращает устаревший результат после смены директории. PID или $$ также не подходят как постоянный идентификатор сессии.
Вывод команды захватывается Claude Code и не подключён напрямую к терминалу. Для адаптации к ширине доступны COLUMNS и LINES; запрос ширины через tput cols не заменяет этот источник. Начните с обычного текста. Несколько строк, ANSI-цвета и ссылки OSC 8 поддерживаются с оговорками терминала; например, Terminal.app не делает OSC 8 ссылки кликабельными. Узкое окно и уведомления могут обрезать строку. Во время подсказок или запросов разрешения она может временно скрываться — это не всегда неисправность.
Как запустить этот вариант на Windows
На Windows проверьте, какой Python установлен и как он вызывается. Для приведённого скрипта можно явно указать интерпретатор и файл в statusLine.command, используя прямые слеши:
{
"statusLine": {
"type": "command",
"command": "\"C:/Python313/python.exe\" -X utf8 \"C:/Users/Anna/bin/claude-status.py\""
}
}Это пример путей: замените оба на свои. Скрипт сохраните в UTF-8; параметр -X utf8 задаёт Python ту же кодировку для ввода и вывода. Текущий Claude Code на Windows использует Git Bash, если он установлен, иначе PowerShell; старое правило «всегда cmd» здесь не подходит. Для отдельного PowerShell-скрипта официальная документация также показывает явный запуск powershell -NoProfile -File …. Настройка statusline на Windows.
Проверить наш Python-вариант в PowerShell можно так:
$OutputEncoding = [System.Text.UTF8Encoding]::new()
Get-Content -Raw -Encoding UTF8 ./statusline-test.json | & "C:/Python313/python.exe" -X utf8 "C:/Users/Anna/bin/claude-status.py"Команда проверки и команда в настройках должны ссылаться на тот же интерпретатор и файл. Если формат в терминале правильный, но внутри клиента не работает, проверяйте оболочку запуска и загруженный ключ statusLine. Успешная проверка синтетического пути Windows в Python сама по себе не подтверждает запуск в Windows-клиенте.
Если строка пустая, исчезает или показывает старые значения

Сначала повторите команду из настроек с тестовым JSON. Это отделяет ошибку пути или скрипта от условий запуска внутри Claude Code.
| Что вы видите | Что проверить | Следующий шаг |
|---|---|---|
| Команда не запускается даже в терминале | Существуют ли интерпретатор и файл, правильно ли стоят кавычки | Исправить путь; для явного Python-запуска проверить чтение файла |
| Есть текст ошибки, но нет строки | stderr, stdout и код завершения | Исправить ошибку; видимый текст печатать в stdout |
контекст ?, но остальные сегменты есть | Был ли первый ответ, завершился ли /compact, правильное ли имя поля | Использовать used_percentage, дождаться следующего ответа |
| Git показывает другой каталог или ветку | Какой каталог передан в JSON и где выполняется Git | Привязать запрос к переданному каталогу, убрать устаревший кэш |
| Изменения скрипта ещё не видны | Произошёл ли новый запуск команды | Дождаться события; для локальных фоновых изменений добавить таймер |
| Строка мигает или скрипт постоянно прерывается | Долгие Git, сеть, чтение больших файлов | Убрать тяжёлую работу, ограничить ожидание и сократить число сегментов |
| Текст работает, оформление ломается | Возможности терминала и ширину | Вернуться к обычному тексту, затем добавлять оформление по одному элементу |
Если команда отдельно работает, проверьте настройки и условия её допуска. Управляемое disableAllHooks: true или недоверенное рабочее пространство отключают все настраиваемые строки состояния, включая управляемые. allowManagedHooksOnly, действующее неуправляемое disableAllHooks: true или --safe-mode допускают значения только из управляемых настроек: корпоративная строка может работать, а личная — пропускаться без предупреждения. Разрешённые хуки управляемого плагина не означают, что разрешён его statusLine: само значение должно поступать из управляемых настроек. Точные условия допуска.
При ограничении организации передайте администратору команду и симптомы; не отключайте корпоративные правила ради оформления. Для локальной ошибки проверьте JSON настроек и сообщения запуска: claude doctor может сообщить об отклонённых значениях. Отсутствие чисел в уже работающей строке требует проверки полей и момента обновления, а не изменения разрешений.
Когда удобнее ccstatusline
ccstatusline подходит, если вам нужны готовые элементы, несколько строк, темы или настройка через текстовое меню. В README предлагается запуск npx -y ccstatusline@latest либо bunx -y ccstatusline@latest; для первого пути нужен Node.js с npm, для второго — Bun. Это уже загрузка и запуск стороннего пакета. Пункт Pinned global install в меню устанавливает выбранную версию глобально и записывает закреплённую команду. Настройки самого инструмента находятся в ~/.config/ccstatusline/settings.json.
Выбирайте элементы с пониманием источника: часть показателей использует входной JSON, но виджеты использования могут обращаться к учётным данным или Keychain и напрямую к Anthropic usage API. Другие показатели могут читать файлы разговоров или кэш, а состояние сервисов требует сети. Поэтому ccstatusline нельзя целиком описывать как автономный обработчик stdin. В этой статье пакет не устанавливался и такие обращения не проверялись; основание для выбора — документированные возможности настройки, а не измеренное преимущество в скорости или надёжности.
Если нужны только поля из примера выше, собственный скрипт проще связать с конкретным входом и проверить. Если удобство меню важнее этой простоты, начните с нужных элементов ccstatusline и проверьте их зависимости перед подключением.
Короткие ответы
Чем отличаются statusline, /statusline и statusLine?
statusline — название строки состояния, /statusline — команда её настройки, а statusLine — ключ в JSON настроек. Регистр ключа важен: statusline вместо statusLine не является тем же параметром.
Строка состояния расходует токены модели?
Запуск нашего скрипта не вызывает модель: он форматирует переданный JSON и запрашивает локальный Git. Однако произвольная команда или генерация скрипта через /statusline — другие действия; нельзя обещать отсутствие обращений ко внешним сервисам для любого стороннего инструмента.
Почему 0 % и ? должны выглядеть по-разному?
Число 0 означает переданное измерение с нулевым использованием. null, отсутствующее поле и истёкшее окно означают, что пригодного текущего измерения нет. Особенно важно сохранять это различие для контекста после /compact и необязательных rate_limits. Описание входных полей.
Можно ли сделать отдельные строки для подагентов?
Да, через subagentStatusLine, но у него другой формат: на входе массив tasks и columns, на выходе отдельная строка JSON с id и content для каждого переопределённого задания. Если id не возвращён, остаётся стандартная строка; пустой content скрывает её. Скрипт основной строки нельзя подключить туда без изменения. Действуют те же условия допуска из настроек. Строки состояния подагентов.
Источники4
Внешние страницы, на которые ссылается это руководство, в порядке упоминания. Последнее обновление: 8 окт. 2026 г..
Источники4
Внешние страницы, на которые ссылается это руководство, в порядке упоминания. Последнее обновление: 8 окт. 2026 г..





