Перейти к основному содержанию

Claude Code statusline: настройка строки состояния и рабочий скрипт

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

LaoZhang AI TeamОпубликованоОбновлено 10 мин чтения
Содержание
Настройка Claude Code statusline через /statusline или statusLine с Python-скриптом и текстовым stdout

Строку состояния 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 до закрытия стандартного ввода.

Claude Code передаёт JSON скрипту; Git проверяется отдельно, а текст stdout становится строкой состояния

python
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, сохранив остальные настройки:

json
{
  "statusLine": {
    "type": "command",
    "command": "python3 \"$HOME/bin/claude-status.py\""
  }
}

Это пример содержимого файла, а не указание заменить существующий файл целиком. Если там уже есть другие ключи, добавьте statusLine рядом с ними и проверьте запятые. При явном запуске через python3 файлу скрипта не нужен исполняемый бит; интерпретатору всё равно нужен доступ на чтение. Если команда python3 недоступна в среде Claude Code, укажите её полный путь.

Проверьте вывод на искусственном JSON

Сохраните рядом с собой файл statusline-test.json:

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}
}

Передайте его в скрипт из терминала:

bash
python3 "$HOME/bin/claude-status.py" < statusline-test.json

Ожидаемый вывод:

Claude Sonnet | проект | Git feature/status | контекст 42 % | оценка 0,18 USD

Ветка здесь тоже искусственная: наличие поля worktree.branch позволяет проверить формат без создания репозитория. Для проверки отсутствующих значений подайте пустой объект:

bash
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.idmodel — объект, а не строка
Рабочий каталог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 укажите:

json
"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, используя прямые слеши:

json
{
  "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 можно так:

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, путь команды, загруженные настройки и действующую политику

Сначала повторите команду из настроек с тестовым 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 г..

  1. 1.официальном руководстве по statuslinecode.claude.com/docs/en/statusline
  2. 2.Области настроек Claude Codecode.claude.com/docs/en/settings
  3. 3.Точные условия допускаcode.claude.com/docs/en/settings-reference
  4. 4.ccstatuslinegithub.com/sirmalloc/ccstatusline
Ещё по теме Claude Code