Claude Code Statusline: маршруты, поля, скрипты и диагностика

Claude Code statusline - это локальная команда, а не тема терминала. Claude Code передает JSON текущей сессии в stdin, ваш скрипт печатает строку в stdout, и именно эта строка появляется внизу интерфейса. Для быстрого личного старта используйте /statusline; для контролируемой настройки используйте ручной statusLine; в проектные настройки переносите команду только после проверки безопасности для всей команды.

Правильный порядок: маршрут, контракт команды, область настроек, затем поля. Statusline может показать модель, каталог, ветку git, использование context, оценку cost и иногда rate-limit данные. Но каждое поле нужно считать опциональным, пока ваш скрипт не умеет обрабатывать отсутствие или null.

Что на самом деле делает statusline

Statusline - это командный интерфейс внутри Claude Code. Claude Code запускает настроенную команду, пишет JSON в stdin, читает stdout и показывает результат как нижнюю строку. Поэтому сначала думайте о локальном выполнении, а уже потом о красивом виде.

У этой модели есть три последствия. Команда выполняется на вашей машине и может вызвать git, прочитать файлы или запустить скрипт из домашнего каталога. Это удобно для личной строки, но опасно для общего проекта без доверия.

Скрипт должен быть защитным. JSON может содержать model, workspace, git, cost, context, session, version, output style, vim, agent, worktree и rate-limit данные. Но разные версии, аккаунты и маршруты не обязаны отдавать один и тот же набор полей. Хороший скрипт печатает ctx:? или git:-, а не падает.

И наконец, stdout - это пользовательская поверхность. Логи отладки должны уходить в stderr. Строка, которую видит разработчик, должна быть короткой, стабильной и быстрой.

Быстрый старт через /statusline

Для первой личной версии запустите:

text
/statusline

Попросите простой результат:

text
Show model, current directory, git branch, context percentage, and estimated cost. Keep it one line and handle missing fields.

Claude Code может создать и установить скрипт. После этого откройте файл и прочитайте его. Вы подтверждаете локальную команду, а не просто цветовую схему. Если внутри есть абсолютный путь одного пользователя, сетевой вызов, приватный endpoint или тяжелый git status, не переносите это в командный проект.

/statusline хорош для исследования: какие поля полезны, какие подписи читаются, где строка становится слишком длинной. Когда нужен командный стандарт, вернитесь к ручному statusLine и проверьте путь, fallback, скорость и доверие.

Ручной statusLine для контролируемой настройки

Ручная настройка делает поведение повторяемым. В settings это command object:

json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline/statusline.js",
    "refreshInterval": 5
  }
}

Ключевые части - type и command. refreshInterval необязателен. Добавляйте его только если в строке есть значение, которое должно обновляться по времени. В обычной работе Claude Code и так обновляет строку по событиям, а слишком частая периодика только усиливает проблему медленного скрипта.

Личная команда может жить в ~/.claude/. Командная команда должна быть в репозитории только после review. Не коммитьте путь из домашнего каталога, секреты или зависимость от локальной машины.

Проверяйте скрипт на mock JSON

Минимальный Node.js скрипт должен читать stdin, безопасно парсить JSON и печатать одну строку:

js
#!/usr/bin/env node

let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
  input += chunk;
});

process.stdin.on("end", () => {
  let data = {};
  try {
    data = input.trim() ? JSON.parse(input) : {};
  } catch (error) {
    console.error(`statusline JSON parse failed: ${error.message}`);
  }

  const model = data.model?.display_name || data.model?.id || "model?";
  const cwd = data.workspace?.current_dir || data.cwd || "";
  const dir = cwd ? cwd.split("/").filter(Boolean).pop() : "workspace?";
  const branch = data.git?.branch ? `git:${data.git.branch}` : "git:-";
  const context =
    typeof data.context_window?.percentage === "number"
      ? `ctx:${Math.round(data.context_window.percentage)}%`
      : "ctx:?";
  const cost =
    typeof data.cost?.total_cost_usd === "number"
      ? `$${data.cost.total_cost_usd.toFixed(2)} est`
      : "$? est";

  process.stdout.write(`${model} | ${dir} | ${branch} | ${context} | ${cost}`);
});

Перед включением проверьте его напрямую:

bash
chmod +x ~/.claude/statusline/statusline.js
printf '%s' '{"model":{"display_name":"Claude Sonnet"},"workspace":{"current_dir":"/Users/me/project"},"git":{"branch":"main"},"context_window":{"percentage":42},"cost":{"total_cost_usd":0.18}}' | ~/.claude/statusline/statusline.js

Ожидайте одну чистую строку. Если она не работает вне Claude Code, чините скрипт, а не настройки Claude Code.

Какие поля стоит показывать

Statusline должен отвечать на рабочий вопрос: где я, какая модель, чистая ли ветка, сколько context осталось и какой примерный cost у сессии.

Практичный формат:

text
Sonnet | api-docs | main* | ctx:42% | $0.18 est

Если cost не нужен, уберите его. Если git status тормозит, оставьте только branch. Строка должна помогать, а не доказывать, что вы нашли все поля JSON.

Область настроек решает безопасность

Settings бывают личные, локальные для проекта, общие проектные, managed и временные session flags. Statusline должен жить там, где команда безопасна.

Командный шаблон:

json
{
  "statusLine": {
    "type": "command",
    "command": "./.claude/statusline/statusline.js"
  }
}

Такой скрипт должен быть быстрым, без секретов, без приватных endpoint, с fallback и понятным отключением.

Производительность и refresh

Statusline вызывается повторно. Не делайте из него тяжелый мониторинг. Сначала используйте поля, которые Claude Code уже передал. Дорогие git проверки кешируйте. refreshInterval используйте только для значений, которым действительно нужна периодика.

Измеряйте отдельно:

bash
time printf '{}' | ~/.claude/statusline/statusline.js

Если напрямую медленно, Claude Code не исправит ситуацию. Уберите сетевые вызовы, сократите git status, сохраните вычисления в кеш или уменьшите количество сегментов.

Windows и терминал

На Windows чаще ломается shell/path, а не JSON. Git Bash, PowerShell, WSL и Node могут по-разному обрабатывать кавычки и пути. Проверяйте именно ту команду, которую будет запускать Claude Code.

Сначала сделайте plain text. Цвета, powerline glyphs и OSC 8 links добавляйте позже. Если строка работает на macOS, но не на Windows, проверьте interpreter path, executable path, line endings и cwd.

Когда брать third-party formatter

Formatter полезен, если нужны темы, powerline layout или готовое форматирование. Но он остается локальной командой.

Если вы не можете объяснить, что выполняет formatter, оставьте маленький собственный скрипт.

Диагностика пустой или устаревшей строки

disableAllHooks тоже относится к диагностике. Не переключайте его случайно: он может изменить поведение hook-like команд.

Соседние материалы Claude Code

• Установка CLI: Claude Code install.
• Route и credentials: Claude Code API configuration.
• API key и subscription billing: Claude Code API key vs subscription billing.
• Постоянный контекст: Claude Code memory.
• Переиспользуемые workflow блоки: Claude Code best skills.

Часто задаваемые вопросы

statusline и statusLine одинаковы?

Нет. statusline - обычное название, /statusline - slash command, а statusLine - ключ JSON settings.

Statusline тратит API token?

Сама команда выполняется локально и не делает дополнительный model request. Она может показать данные, которые Claude Code уже передал.

Можно ли показывать rate limits?

Да, если активный маршрут и аккаунт передают эти данные. Скрипт должен нормально работать без rate_limits.

Можно ли коммитить скрипт?

Только если он безопасен для всех: без секретов, быстрый, path-safe, с fallback и review.

Почему видно undefined?

Скрипт предполагает поле, которого нет. Проверьте mock JSON без этого поля и добавьте fallback.

Лучшая первая строка?

Модель, basename каталога, git branch, context процент и cost estimate, если эти поля есть. Цвета и formatter добавляйте после стабильной работы.