Navi Code CLI

Терминальный клиент для общения с Navi через WebSocket.

Установка

CLI устанавливается вместе с пакетом navi:

pip install -e .

После установки доступна команда navi-code. Внутри репозитория можно запускать без установки:

python -m clients.terminal

Использование

Интерактивный режим

navi-code

Клиент подключается к http://localhost:8000, создаёт или восстанавливает сессию и запускает чат.

One-shot режим

navi-code "объясни, что делает этот файл"
navi-code --new-session "напиши pytest-тест для функции foo"

Параметры

Флаг	Описание
`--base-url URL`	Базовый URL сервера Navi.
`--ws-url URL`	URL WebSocket (по умолчанию производный от `--base-url`).
`--profile-id ID`	Профиль для новой сессии.
`--new-session`	Создать новую сессию, даже если сохранена старая.
`--show-thinking`	Показывать блоки рассуждений модели.
`--no-events`	Скрывать события `tool_started` / `tool_call`.
`--mouse` / `--no-mouse`	Включить/выключить мышь в TUI на один запуск (перекрывает `tui.json`).
`--theme NAME`	Запустить TUI с указанной темой.
`--raw`	Запустить plain CLI вместо TUI (используется по умолчанию, когда передан позиционный запрос).
`--version`	Версия клиента.
`-h`, `--help`	Показать справку по использованию.

Любой позиционный аргумент воспринимается как запрос и запускает plain CLI в one-shot режиме (например navi-code "объясни этот файл"). Неизвестные флаги передаются как часть запроса.

Команды в интерактивном режиме

Команда	Описание
`/help`	Список команд.
`/new`	Создать новую сессию.
`/sessions`	Список сессий на сервере.
`/switch <id>`	Переключиться на другую сессию (можно по префиксу id).
`/profile`	Показать текущий профиль и id сессии.
`/export [path]`	Экспортировать текущую сессию в Markdown; без пути — во временный файл и `$EDITOR`. Если редактор не запускается, ошибка выводится в чат.
`/themes`	Открыть выбор темы с live-preview.
`/mouse on	off`	Включить/выключить поддержку мыши (требует перезапуска).
`/thinking`	Переключить отображение thinking-блоков в текущей сессии.
`/compact`	Вручную запустить сжатие контекста текущей сессии.
`/clear`	Очистить локально сохранённый `session_id`.
`/quit`	Выйти.

Интерфейс TUI

В интерактивном режиме (navi-code) экран разделён на три зоны:

Левая панель (ChatPanel) — история сообщений, поле ввода и текущий статус.
Правая верхняя панель (StatusPanel) — текущий профиль, модель, статус соединения, токены и оставшиеся итерации.
Правая нижняя панель (SessionsPanel) — список сессий на сервере с колонками ID, профиль и превью. Клик или Enter на строке переключает сессию.

Список сессий обновляется автоматически при запуске и при выполнении /new, /sessions, /switch.

Поле ввода

Поле ввода многострочное — перенос текста по ширине автоматический, высота поля растёт вместе с содержимым (в пределах ограничения). Enter отправляет сообщение целиком (вместе с переносами). Принудительный перенос строки не поддерживается: терминалы не различают Ctrl+Enter от обычного Enter, поэтому сделан только автоматический перенос.

Карточки в чате

Помимо обычных сообщений и блоков рассуждений, чат рендерит карточки для специальных событий:

Планирование. Пока работает планировщик, показывается rolling-индикатор ⚙ Planning · <фаза> (обновляется на месте, а не плодит строки). Когда план готов — карточка Plan с содержимым плана.
Субагент (spawn_agent). Отдельная карточка ↘ subagent · <профиль> при запуске и ↙ subagent · <профиль> ✓/✗ с результатом. Имя задачи и брифинг показаны в теле карточки.
Вложенные события субагента. Рассуждения, планирование, карточки инструментов и плана субагента показываются с отступом и приглушённым стилем, чтобы визуально отделить их от основного хода сессии (TUI использует плоскую модель, вложенность передаётся через отступ).

Состояние

Клиент сохраняет session_id в ~/.navi_code/state.json, чтобы восстановить диалог при следующем запуске. Удалите файл или используйте /clear, чтобы начать с чистого листа.

Рендеринг событий

События WebSocket рендерятся по-разному в TUI и в plain CLI (--raw):

stream_delta — печатается inline, как в обычном чате.
tool_started / tool_call — карточки инструментов: имя, аргументы, краткий результат (если включено --show-events / --no-events не задан).
thinking_delta / thinking_end — блоки рассуждений, показываются только с --show-thinking.
planning_status — индикатор текущей фазы планирования (в TUI — rolling-строка ⚙ Planning · <фаза>; в plain CLI — [planning] <фаза>).
plan_ready — готовый план (в TUI — карточка Plan; в plain CLI — блок [plan]…[/plan]).
turn_thinking — полный блок рассуждений субагента целиком (не стримится по частям); в TUI это subagent thinking с отступом, в plain CLI — [thinking]…(subagent).
error — красным цветом.

Пример сессии

$ navi-code
Created session a1b2c3d4 (profile navi_code)
Navi Code interactive mode. Type /quit to exit, /help for commands.
You: напиши скрипт, который считает строки в текущей директории
[tool: terminal]
{'cmd': 'find . -type f | wc -l'}
[tool result: terminal success=True]
42

Я насчитал 42 файла в текущей директории и её поддиректориях.
You: /quit

Разработка

Код CLI находится в clients/terminal/:

cli.py — точка входа и интерактивный цикл.
ws_client.py — WebSocket-клиент.
api.py — REST-запросы к серверу.
render.py — рендеринг событий в терминал.
state.py — сохранение session_id в ~/.navi_code/state.json.
config.py — настройки из переменных окружения NAVI_CODE_*.
tui/tui_app.py — Textual-приложение.
tui/widgets/ — виджеты (ChatPanel, StatusPanel, SessionsPanel, InputBox).
tui/renderers/ — рендереры карточек по типам событий (сообщения, рассуждения, инструменты, планирование, субагент); диспетчеризация через RendererRegistry.
tui/commands/ — slash-команды (/new, /sessions, /switch, /export, /themes, /mouse).
tui/settings.py — persisted TUI config (~/.navi_code/tui.json).

Тесты: tests/clients/test_terminal_client.py, tests/clients/test_terminal_ws.py, tests/clients/test_tui_*.py.