01. Быстрый старт — AstraCode — Руководство пользователя

Цель этого документа — за 10 минут вы получите первый рабочий результат с AstraCode.

1. Установить (1 минута)

См. подробно 02-installation.md. Самый быстрый путь:

Откройте GitLab Package Registry, выберите пакет AstraCode версии 0.5.1 для своей платформы и установите его по инструкции из пакета.

После установки проверьте версию:

bash

astracode --version

Должны увидеть astracode-cli 0.5.1.

2. Запустить (10 секунд)

Перейдите в директорию проекта:

bash

cd ~/myproject
astracode

Откроется TUI. Первый запуск создаст ~/.astracode/ и попросит настроить провайдера.

3. Настроить модель (1 минута)

При первом запуске откроется форма добавления провайдера — три поля:

Display name — произвольное название (например, work-openai).
Base URL — адрес любого Chat Completions-совместимого endpoint'а (https://api.openai.com/v1, ваш on-prem шлюз и т.п.).
API key — ключ от этого endpoint'а (необязательно — если endpoint не требует авторизации, поле можно оставить пустым).

Провайдер не выбирается из пресетов вроде «OpenAI/Anthropic/Local»: вы вводите любой совместимый endpoint вручную, а slug провайдера выводится из Display name.

Ключ сохранится зашифрованно в ~/.astracode/secrets/local.age — больше его вводить не нужно.

Можно пропустить и настроить позже через /model.

4. Первая задача (3 минуты)

В нижней части экрана — composer (поле ввода). Напишите задачу:

text

Привет! Покажи структуру этого проекта в виде дерева, глубина 2 уровня.

Нажмите Enter. AstraCode: 1. Прочитает содержимое директории. 2. Покажет дерево в чате. 3. Объяснит, что увидел.

При запуске первой shell-команды (ls, tree) появится approval-диалог:

text

Tool wants to run: ls -la
[y] allow once   [a] allow always   [d] deny

Нажмите y — разрешить однократно. a — разрешать аналогичные действия до конца сессии. d — отказать.

5. Реальная задача (5 минут)

Теперь что-то полезное. Например:

text

Найди файл с тестами для модуля auth и запусти их. Если упадут — покажи мне, почему.

AstraCode: 1. Найдёт тестовый файл (grep/find). 2. Запустит тесты (cargo test, pytest, что у вас). 3. Если упадут — покажет stacktrace + объяснение. 4. Может предложить fix.

Если предложил fix:

text

Примени этот fix.

AstraCode попросит подтверждения на изменение файла (по умолчанию approval_policy = on-request).

6. Что делать дальше

Если задача растянулась

Если разговор стал длинным или вы перешли к новой задаче — /new (новая сессия, та же модель).

Если хотите продолжить эту задачу позже — закройте TUI (/exit или Ctrl-D). При следующем запуске:

text

/sessions

Откроется picker всех ваших сессий — выберите нужную. (/resume — алиас той же команды.)

Если задача большая

Поставьте цель:

text

/goal Реализовать OAuth-вход через Google

Цель сохранится в БД. Даже после /new или перезапуска AstraCode сможет вернуться к ней через /sessions. См. 07-goals.md.

Если хотите review перед коммитом

text

/review

Откроется меню — выберите «Uncommitted changes». Агент-ревьюер пройдётся по diff'у и напишет отчёт с findings.

Если что-то пошло не так

Ctrl-C — прервать текущий ответ модели.

Если ответ не соответствует запросу — попросите переделать:

text

Не то. Я хотел, чтобы ты использовал библиотеку X, а не Y.

Модель учтёт корректировку и переделает.

7. Самые важные команды

Команда	Что делает
`/help`	Справка по всем командам (`/help <команда>` — детали)
`/new`	Начать новую сессию
`/clear`	То же + очистить экран
`/sessions`	Открыть picker сохранённых сессий (`/resume` — алиас)
`/diff`	Показать `git diff`
`/review`	Code review текущих изменений
`/undo`	Выбрать и отменить изменение файлов, сделанное агентом
`/collapse` / `/expand`	Свернуть или раскрыть завершённые tool-блоки
`/model`	Сменить модель или провайдера
`/status`	Текущая модель, токены, sandbox
`Ctrl-C`	Прервать ответ
`/exit` или `Ctrl-D`	Выйти из TUI
`Tab`	Поставить сообщение в очередь (queue)
`@<file>`	Упомянуть файл в промпте
`!<cmd>`	Выполнить shell-команду вручную
`$<skill>`	Активировать скилл вручную

Полная шпаргалка — 04-commands-cheatsheet.md.

8. На русском?

Если вам комфортнее на русском:

text

/locale ru

(Доступно только до первого сообщения в сессии. Если уже что-то отправляли — /new, потом /locale ru.)

Эта настройка сохранится в config.toml. См. 14-customization.md.

9. Подводные камни первых дней

AstraCode не запоминает между сессиями всё подряд. Чтобы он помнил факты о вас или проекте — включите Память. Иначе при /new контекст с нуля.
API-ключи — деньги. Каждый запрос к OpenAI/Anthropic стоит токены. Long context = больше токены. /status показывает расход. /compact сжимает историю.
Sandbox блокирует часть команд. Это не баг, а защита. Если что-то нужное не работает — /approvals сменить уровень разрешений или /sandbox-add-read-dir добавить конкретный путь (команда доступна только на Windows). См. 13-safety.md.
MCP-серверы (Linear, GitHub, Slack и т.п.) добавляются через config.toml, не из UI. См. 11-mcp.md.

10. Что почитать дальше

03-tui-basics.md — где что на экране, какие хоткеи.
05-working-with-project.md — как эффективно работать в репозитории.
13-safety.md — что значат approval-диалоги.

Удачи! Если что-то не работает — 15-troubleshooting.md.